[libcamera-devel] [PATCH v4 36/37] Documentation: Add IPA writers guide

[Paul Elder]

Add a guide about writing IPAs.

Signed-off-by: Paul Elder <paul.elder at ideasonboard.com>

---

So far it only covers stuff about the IPA interface...

New in v4
---
 Documentation/guides/ipa.rst | 112 +++++++++++++++++++++++++++++++++++
 Documentation/index.rst      |   1 +
 Documentation/meson.build    |   1 +
 3 files changed, 114 insertions(+)
 create mode 100644 Documentation/guides/ipa.rst

diff --git a/Documentation/guides/ipa.rst b/Documentation/guides/ipa.rst
new file mode 100644
index 00000000..4b270eb7
--- /dev/null
+++ b/Documentation/guides/ipa.rst
@@ -0,0 +1,112 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+IPA Writers Guide
+=================
+
+IPA are Image Processing Algorithm modules. They provide functionality that
+the pipeline handler can use for image processing.
+
+The IPA interface and protocol
+------------------------------
+
+The IPA interface defines the interface between the pipeline handler and the
+IPA. Specifically, it defines the functions that the IPA exposes that the
+pipeline handler can call, and the Signals that the pipeline handler can
+connect to to receive data from the IPA asyncrhonously. In addition, it
+contains any custom data structures that the pipeline handler and IPA may
+pass to each other.
+
+The IPA protocol refers to the agreement between the pipeline handler and the
+IPA regarding the expected response(s) from the IPA for given calls to the IPA.
+This protocol doesn't need to be declared anywhere in code, but it would be
+useful to document it, as there may be different IPAs for some pipeline handler.
+
+The IPA interface must be defined in a mojom file. The interface includes the
+functions that the pipeline handler can call from the IPA, Signals in the
+pipeline handler that the IPA can emit, and any data structures that are to
+be passed between the pipeline handler and the IPA. All IPA of a given pipeline
+handler use the same IPA interface. The IPA interface definition is thus
+likely to be written by the pipeline handler author, based on how they imagine
+the pipeline handler will interact with the IPA.
+
+Any custom structs that the IPA interfaces use must be defined in in a file
+named {pipeline_name}.mojom under include/libcamera/ipa/ using the mojo
+mojo interface definition language.
+
+It is recommended to use namespacing, to avoid potential collisions with
+libcamera types. Use mojom's module directive for this.
+
+The Main IPA interface
+----------------------
+
+The IPA interface is split in two parts, the Main IPA interface, which
+describes the functions that the pipeline handler can call from the IPA,
+and the Event IPA interface, which describes the Signals in the pipeline
+handler that the IPA can emit. Both must be defined. This section focuses
+on the Main IPA interface.
+
+The main interface must be named as IPA{pipeline_name}Interface.
+
+At minimum, the following three functions must be present (and implemented):
+- init(IPASettings settings) => (int32 ret);
+- start() => (int32 ret);
+- stop();
+
+All three of these functions are synchronous.
+
+All input parameters will become const references, except for arithmetic types,
+which will be passed by value. Output parameters will become pointers, unless
+there is only one primitive output parameter, in which case it will become a
+a regular return value.
+
+const is not allowed inside of arrays and maps. mojo arrays will become C++
+std::vector<>.
+
+By default, all methods defined in the main interface are synchronous. This
+means that in the case of IPC (ie. isolated IPA), the function call will not
+return until the return value or output parameters are ready. To specify an
+asynchronous function, the [async] attribute can be used. Asynchronous
+methods must not have any return value or output parameters, since in the
+case of IPC the call needs to return immediately.
+
+It is also possible that the IPA will not be run in isolation. In this case,
+the IPA thread will not exist until start() is called. This means that in the
+case of no isolation, asynchronous calls cannot be made before start(). Since
+the IPA interface must be the same regardless of isolation, the same
+restriction applies to the case of isolation, and any function that will be
+called before start() must be synchronous.
+
+In addition, any call made after start() and before stop() must be
+asynchronous. The motivation for this is to avoid damaging real time
+performance of the pipeline handler. If the pipeline handler wants some data
+from the IPA, the IPA should return the data asynchronously via an event
+(see "The Event IPA interface").
+
+In addition the following must be defined in {pipeline_name}.h in the
+libcamera namespace:
+
+static ControlInfoMap {pipeline_name}::controls;
+
+It may be empty. This will be the default ControlInfoMap used when
+serializing and deserializing any ControlLists if it is not specified
+in the ControlList.
+
+
+The Event IPA interface
+-----------------------
+
+The event IPA interface describes the Signals in the pipeline handler that the
+IPA can emit. It must be defined. If there are no event functions, then it may
+be empty. These emissions are meant to notify the pipeline handler of some
+event, such as reqeust data is ready, and *must not* be used to drive the
+camera pipeline from the IPA.
+
+The event interface must be named as IPA{pipeline_name}EventInterface.
+
+Methods defined in the event interface are implictly asynchronous.
+They thus can't return any value. Specifying the [async] tag is not
+necessary.
+
+Methods defined in the event interface will become Signals in the IPA
+interface. The IPA can emit signals, while the pipeline handler can connect
+slots to them.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ff697d4f..8bc8922e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -16,4 +16,5 @@
    Developer Guide <guides/introduction>
    Application Writer's Guide <guides/application-developer>
    Pipeline Handler Writer's Guide <guides/pipeline-handler>
+   IPA Writer's guide <guides/ipa>
    Tracing guide <guides/tracing>
diff --git a/Documentation/meson.build b/Documentation/meson.build
index 59107151..17f3b9d7 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -52,6 +52,7 @@ if sphinx.found()
         'docs.rst',
         'index.rst',
         'guides/introduction.rst',
+        'guides/ipa.rst',
         'guides/application-developer.rst',
         'guides/pipeline-handler.rst',
         'guides/tracing.rst',
-- 
2.27.0