From e228c290c956ac7823fb9347be8ea957cf6d6172 Mon Sep 17 00:00:00 2001
From: Kieran Bingham <kieran.bingham@ideasonboard.com>
Date: Sat, 19 Jun 2021 00:27:42 +0100
Subject: libcamera/base: Validate internal headers as private

Headers which must not be exposed as part of the public libcamera API
should include base/private.h.

Any interface which includes the private.h header will only be able to
build if the libcamera_private dependency is used (or the
libcamera_base_private dependency directly).

Build targets which are intended to use the private API's will use the
libcamera_private to handle the automatic definition of the inclusion
guard.

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
---
 include/libcamera/base/event_dispatcher.h      |  2 ++
 include/libcamera/base/event_dispatcher_poll.h |  2 ++
 include/libcamera/base/event_notifier.h        |  2 ++
 include/libcamera/base/file.h                  |  2 ++
 include/libcamera/base/log.h                   |  2 ++
 include/libcamera/base/meson.build             |  1 +
 include/libcamera/base/private.h               | 22 ++++++++++++++++++++++
 include/libcamera/base/semaphore.h             |  1 +
 include/libcamera/base/thread.h                |  2 ++
 include/libcamera/base/timer.h                 |  2 ++
 include/libcamera/base/utils.h                 |  2 ++
 11 files changed, 40 insertions(+)
 create mode 100644 include/libcamera/base/private.h

(limited to 'include')

diff --git a/include/libcamera/base/event_dispatcher.h b/include/libcamera/base/event_dispatcher.h
index 045df27f..825af7a3 100644
--- a/include/libcamera/base/event_dispatcher.h
+++ b/include/libcamera/base/event_dispatcher.h
@@ -9,6 +9,8 @@
 
 #include <vector>
 
+#include <libcamera/base/private.h>
+
 namespace libcamera {
 
 class EventNotifier;
diff --git a/include/libcamera/base/event_dispatcher_poll.h b/include/libcamera/base/event_dispatcher_poll.h
index ae2a3f04..683934bf 100644
--- a/include/libcamera/base/event_dispatcher_poll.h
+++ b/include/libcamera/base/event_dispatcher_poll.h
@@ -11,6 +11,8 @@
 #include <map>
 #include <vector>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/event_dispatcher.h>
 
 struct pollfd;
diff --git a/include/libcamera/base/event_notifier.h b/include/libcamera/base/event_notifier.h
index 5aa2784a..5055ccbf 100644
--- a/include/libcamera/base/event_notifier.h
+++ b/include/libcamera/base/event_notifier.h
@@ -7,6 +7,8 @@
 #ifndef __LIBCAMERA_BASE_EVENT_NOTIFIER_H__
 #define __LIBCAMERA_BASE_EVENT_NOTIFIER_H__
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/object.h>
 #include <libcamera/base/signal.h>
 
diff --git a/include/libcamera/base/file.h b/include/libcamera/base/file.h
index 465f3ef8..7dd1559d 100644
--- a/include/libcamera/base/file.h
+++ b/include/libcamera/base/file.h
@@ -12,6 +12,8 @@
 #include <map>
 #include <string>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/class.h>
 #include <libcamera/base/span.h>
 
diff --git a/include/libcamera/base/log.h b/include/libcamera/base/log.h
index b93c947a..866a2133 100644
--- a/include/libcamera/base/log.h
+++ b/include/libcamera/base/log.h
@@ -10,6 +10,8 @@
 #include <chrono>
 #include <sstream>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/class.h>
 #include <libcamera/base/utils.h>
 
diff --git a/include/libcamera/base/meson.build b/include/libcamera/base/meson.build
index 6b90f9f7..7c499b55 100644
--- a/include/libcamera/base/meson.build
+++ b/include/libcamera/base/meson.build
@@ -12,6 +12,7 @@ libcamera_base_headers = files([
     'log.h',
     'message.h',
     'object.h',
+    'private.h',
     'semaphore.h',
     'signal.h',
     'span.h',
diff --git a/include/libcamera/base/private.h b/include/libcamera/base/private.h
new file mode 100644
index 00000000..163012bf
--- /dev/null
+++ b/include/libcamera/base/private.h
@@ -0,0 +1,22 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2021, Google Inc.
+ *
+ * private.h - Private Header Validation
+ *
+ * A selection of internal libcamera headers are installed as part
+ * of the libcamera package to allow sharing of a select subset of
+ * internal functionality with IPA module only.
+ *
+ * This functionality is not considered part of the public libcamera
+ * API, and can therefore potentially face ABI instabilities which
+ * should not be exposed to applications. IPA modules however should be
+ * versioned and more closely matched to the libcamera installation.
+ *
+ * Components which include this file can not be included in any file
+ * which forms part of the libcamera API.
+ */
+
+#ifndef LIBCAMERA_BASE_PRIVATE
+#error "Private headers must not be included in the libcamera API"
+#endif
diff --git a/include/libcamera/base/semaphore.h b/include/libcamera/base/semaphore.h
index c8e62e3e..d8146eb8 100644
--- a/include/libcamera/base/semaphore.h
+++ b/include/libcamera/base/semaphore.h
@@ -9,6 +9,7 @@
 
 #include <condition_variable>
 
+#include <libcamera/base/private.h>
 #include <libcamera/base/thread.h>
 
 namespace libcamera {
diff --git a/include/libcamera/base/thread.h b/include/libcamera/base/thread.h
index 2ed18d49..762beab2 100644
--- a/include/libcamera/base/thread.h
+++ b/include/libcamera/base/thread.h
@@ -12,6 +12,8 @@
 #include <sys/types.h>
 #include <thread>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/message.h>
 #include <libcamera/base/signal.h>
 #include <libcamera/base/utils.h>
diff --git a/include/libcamera/base/timer.h b/include/libcamera/base/timer.h
index e79e85f1..79882161 100644
--- a/include/libcamera/base/timer.h
+++ b/include/libcamera/base/timer.h
@@ -10,6 +10,8 @@
 #include <chrono>
 #include <stdint.h>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/object.h>
 #include <libcamera/base/signal.h>
 
diff --git a/include/libcamera/base/utils.h b/include/libcamera/base/utils.h
index d1aaff65..07685045 100644
--- a/include/libcamera/base/utils.h
+++ b/include/libcamera/base/utils.h
@@ -19,6 +19,8 @@
 #include <utility>
 #include <vector>
 
+#include <libcamera/base/private.h>
+
 #ifndef __DOXYGEN__
 
 /* uClibc and uClibc-ng don't provide O_TMPFILE */
-- 
cgit v1.2.1