[libcamera-devel] [PATCH v7 08/12] ipa: raspberrypi: Add mojom data definition file

[Paul Elder]

Add a mojom data definition for raspberrypi pipeline handler's IPAs.
This simplifies the API between the raspberrypi pipeline handler and the
IPA, and is not a direct translation of what was used before with
IPAOperationData.

Also move the enums from raspberrypi.h to raspberrypi.mojom

Signed-off-by: Paul Elder <paul.elder at ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

---
Changes in v7:
- fix some wording
- rename ConfigParameters to ConfigOutputParameters
  - because we don't actually need the input ones
- rename op to params in ConfigOutputParameters
- remove hasControls from StartControls
- remove ret return value from start() (as it always succeeds)
- add vblank
- rename setStaggered to setDelayedControls

Changes in v6:
- rebase on "pipeline: ipa: raspberrypi: Handle failures during IPA
  configuration"
- move enums and consts to the mojom file
- use the custom start()
- remove unnecessary ConfigParameters, and remove lsTableHandleStatic
  from ConfigInput

Changes in v5:
- rename some structs

Changes in v4:
- rename IPARPiCallbackInterface to IPARPiEventInterface

Changes in v3:
- remove stray comment about how our compiler will generate code
- add ipa.rpi namespace
  - not ipa.RPi, because namespace conflict
- remove RPi prefix from struct and enum names
- add transform parameter to struct ConfigInput

Changes in v2:
- rebased on "libcamera: pipeline: ipa: raspberrypi: Rework drop frame
  signalling"
- add license
- move generic documentation to core.mojom
- move documentation from IPA interface
- customize the RPi IPA interface to make the pipeline and IPA code
  cleaner
---
 include/libcamera/ipa/meson.build       |   4 +-
 include/libcamera/ipa/raspberrypi.h     |  20 ----
 include/libcamera/ipa/raspberrypi.mojom | 131 ++++++++++++++++++++++++
 3 files changed, 134 insertions(+), 21 deletions(-)
 create mode 100644 include/libcamera/ipa/raspberrypi.mojom

diff --git a/include/libcamera/ipa/meson.build b/include/libcamera/ipa/meson.build
index 499d1bc0..785c1241 100644
--- a/include/libcamera/ipa/meson.build
+++ b/include/libcamera/ipa/meson.build
@@ -54,7 +54,9 @@ libcamera_generated_ipa_headers += custom_target('core_ipa_serializer_h',
                       './' +'@INPUT@'
                   ])
 
-ipa_mojom_files = []
+ipa_mojom_files = [
+    'raspberrypi.mojom',
+]
 
 ipa_mojoms = []
 
diff --git a/include/libcamera/ipa/raspberrypi.h b/include/libcamera/ipa/raspberrypi.h
index d333c2ed..cadb660b 100644
--- a/include/libcamera/ipa/raspberrypi.h
+++ b/include/libcamera/ipa/raspberrypi.h
@@ -18,26 +18,6 @@ namespace libcamera {
 
 namespace RPi {
 
-enum ConfigParameters {
-	IPA_CONFIG_LS_TABLE = (1 << 0),
-	IPA_CONFIG_STARTUP_CTRLS = (1 << 1),
-	IPA_RESULT_CONFIG_FAILED = (1 << 2),
-	IPA_RESULT_SENSOR_PARAMS = (1 << 3),
-	IPA_RESULT_SENSOR_CTRLS = (1 << 4),
-	IPA_RESULT_DROP_FRAMES = (1 << 5),
-};
-
-enum Operations {
-	IPA_ACTION_SET_DELAYED_CTRLS = 1,
-	IPA_ACTION_V4L2_SET_ISP,
-	IPA_ACTION_STATS_METADATA_COMPLETE,
-	IPA_ACTION_RUN_ISP,
-	IPA_ACTION_EMBEDDED_COMPLETE,
-	IPA_EVENT_SIGNAL_STAT_READY,
-	IPA_EVENT_SIGNAL_ISP_PREPARE,
-	IPA_EVENT_QUEUE_REQUEST,
-};
-
 enum BufferMask {
 	ID		= 0x00ffff,
 	STATS		= 0x010000,
diff --git a/include/libcamera/ipa/raspberrypi.mojom b/include/libcamera/ipa/raspberrypi.mojom
new file mode 100644
index 00000000..bab19a94
--- /dev/null
+++ b/include/libcamera/ipa/raspberrypi.mojom
@@ -0,0 +1,131 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+
+module ipa.rpi;
+
+import "include/libcamera/ipa/core.mojom";
+
+enum BufferMask {
+	MaskID			= 0x00ffff,
+	MaskStats		= 0x010000,
+	MaskEmbeddedData	= 0x020000,
+	MaskBayerData		= 0x040000,
+	MaskExternalBuffer	= 0x100000,
+};
+
+/* Size of the LS grid allocation. */
+const uint32 MaxLsGridSize = 0x8000;
+
+enum ConfigOutputParameters {
+	ConfigStaggeredWrite = 0x01,
+};
+
+struct SensorConfig {
+	uint32 gainDelay;
+	uint32 exposureDelay;
+	uint32 vblank;
+	uint32 sensorMetadata;
+};
+
+struct ISPConfig {
+	uint32 embeddedbufferId;
+	uint32 bayerbufferId;
+};
+
+struct ConfigInput {
+	uint32 op;
+	uint32 transform;
+	FileDescriptor lsTableHandle;
+};
+
+struct ConfigOutput {
+	uint32 params;
+	SensorConfig sensorConfig;
+	ControlList controls;
+};
+
+struct StartControls {
+	ControlList controls;
+	int32 dropFrameCount;
+};
+
+interface IPARPiInterface {
+	init(IPASettings settings) => (int32 ret);
+	start(StartControls controls) => (StartControls result);
+	stop();
+
+	/**
+	 * \fn configure()
+	 * \brief Configure the IPA stream and sensor settings
+	 * \param[in] sensorInfo Camera sensor information
+	 * \param[in] streamConfig Configuration of all active streams
+	 * \param[in] entityControls Controls provided by the pipeline entities
+	 * \param[in] ipaConfig Pipeline-handler-specific configuration data
+	 * \param[out] results Pipeline-handler-specific configuration result
+	 *
+	 * This method shall be called when the camera is configured to inform
+	 * the IPA of the camera's streams and the sensor settings.
+	 *
+	 * The \a sensorInfo conveys information about the camera sensor settings that
+	 * the pipeline handler has selected for the configuration.
+	 *
+	 * The \a ipaConfig and \a results parameters carry data passed by the
+	 * pipeline handler to the IPA and back.
+	 */
+	configure(CameraSensorInfo sensorInfo,
+		  map<uint32, IPAStream> streamConfig,
+		  map<uint32, ControlInfoMap> entityControls,
+		  ConfigInput ipaConfig)
+		=> (ConfigOutput results, int32 ret);
+
+	/**
+	 * \fn mapBuffers()
+	 * \brief Map buffers shared between the pipeline handler and the IPA
+	 * \param[in] buffers List of buffers to map
+	 *
+	 * This method informs the IPA module of memory buffers set up by the pipeline
+	 * handler that the IPA needs to access. It provides dmabuf file handles for
+	 * each buffer, and associates the buffers with unique numerical IDs.
+	 *
+	 * IPAs shall map the dmabuf file handles to their address space and keep a
+	 * cache of the mappings, indexed by the buffer numerical IDs. The IDs are used
+	 * in all other IPA interface methods to refer to buffers, including the
+	 * unmapBuffers() method.
+	 *
+	 * All buffers that the pipeline handler wishes to share with an IPA shall be
+	 * mapped with this method. Buffers may be mapped all at once with a single
+	 * call, or mapped and unmapped dynamically at runtime, depending on the IPA
+	 * protocol. Regardless of the protocol, all buffers mapped at a given time
+	 * shall have unique numerical IDs.
+	 *
+	 * The numerical IDs have no meaning defined by the IPA interface, and 
+	 * should be treated as opaque handles by IPAs, with the only exception
+	 * that ID zero is invalid.
+	 *
+	 * \sa unmapBuffers()
+	 */
+	mapBuffers(array<IPABuffer> buffers);
+
+	/**
+	 * \fn unmapBuffers()
+	 * \brief Unmap buffers shared by the pipeline to the IPA
+	 * \param[in] ids List of buffer IDs to unmap
+	 *
+	 * This method removes mappings set up with mapBuffers(). Numerical IDs
+	 * of unmapped buffers may be reused when mapping new buffers.
+	 *
+	 * \sa mapBuffers()
+	 */
+	unmapBuffers(array<uint32> ids);
+
+	[async] signalStatReady(uint32 bufferId);
+	[async] signalQueueRequest(ControlList controls);
+	[async] signalIspPrepare(ISPConfig data);
+};
+
+interface IPARPiEventInterface {
+	statsMetadataComplete(uint32 bufferId, ControlList controls);
+	runIsp(uint32 bufferId);
+	embeddedComplete(uint32 bufferId);
+	setIsp(ControlList controls);
+	setDelayedControls(ControlList controls);
+};
-- 
2.27.0