Patch Detail
Show a patch.
GET /api/patches/10384/?format=api
{ "id": 10384, "url": "https://patchwork.libcamera.org/api/patches/10384/?format=api", "web_url": "https://patchwork.libcamera.org/patch/10384/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20201106103707.49660-37-paul.elder@ideasonboard.com>", "date": "2020-11-06T10:37:06", "name": "[libcamera-devel,v4,36/37] Documentation: Add IPA writers guide", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "4ecc60bf27edc3585af50d569c188bcb25e9151e", "submitter": { "id": 17, "url": "https://patchwork.libcamera.org/api/people/17/?format=api", "name": "Paul Elder", "email": "paul.elder@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/10384/mbox/", "series": [ { "id": 1448, "url": "https://patchwork.libcamera.org/api/series/1448/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=1448", "date": "2020-11-06T10:36:30", "name": "IPA isolation implementation", "version": 4, "mbox": "https://patchwork.libcamera.org/series/1448/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/10384/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/10384/checks/", "tags": {}, "headers": { "Return-Path": "<libcamera-devel-bounces@lists.libcamera.org>", "X-Original-To": "parsemail@patchwork.libcamera.org", "Delivered-To": "parsemail@patchwork.libcamera.org", "Received": [ "from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id E6DCCBDB89\n\tfor <parsemail@patchwork.libcamera.org>;\n\tFri, 6 Nov 2020 10:38:39 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id B0DCD62D45;\n\tFri, 6 Nov 2020 11:38:39 +0100 (CET)", "from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id EA0E962D22\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 6 Nov 2020 11:38:37 +0100 (CET)", "from pyrite.rasen.tech (unknown\n\t[IPv6:2400:4051:61:600:2c71:1b79:d06d:5032])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 77E91A19;\n\tFri, 6 Nov 2020 11:38:35 +0100 (CET)" ], "Authentication-Results": "lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"BRUfp16Y\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1604659116;\n\tbh=YE8b4weRmvrJ45nSwtz1mzfWzhGU7R4XBOtzXbdLhjU=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=BRUfp16YxDf/ufSz3ynMR8b+lxUGa2Mp1SehpS7rismv4Oihm32xYXWmPyRBMoear\n\tY51K2yk8E5m3LxGMuimTxjrtoDc9+62lV4kGGN08Fg1ZRm4mQ8vnjBFz/DT3jOPELJ\n\tD3XOzHkU1sO+8bi1eSEuzEYZpjioZHaBjVLSbX20=", "From": "Paul Elder <paul.elder@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Fri, 6 Nov 2020 19:37:06 +0900", "Message-Id": "<20201106103707.49660-37-paul.elder@ideasonboard.com>", "X-Mailer": "git-send-email 2.27.0", "In-Reply-To": "<20201106103707.49660-1-paul.elder@ideasonboard.com>", "References": "<20201106103707.49660-1-paul.elder@ideasonboard.com>", "MIME-Version": "1.0", "Subject": "[libcamera-devel] [PATCH v4 36/37] Documentation: Add IPA writers\n\tguide", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "Content-Type": "text/plain; charset=\"us-ascii\"", "Content-Transfer-Encoding": "7bit", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "Add a guide about writing IPAs.\n\nSigned-off-by: Paul Elder <paul.elder@ideasonboard.com>\n\n---\n\nSo far it only covers stuff about the IPA interface...\n\nNew in v4\n---\n Documentation/guides/ipa.rst | 112 +++++++++++++++++++++++++++++++++++\n Documentation/index.rst | 1 +\n Documentation/meson.build | 1 +\n 3 files changed, 114 insertions(+)\n create mode 100644 Documentation/guides/ipa.rst", "diff": "diff --git a/Documentation/guides/ipa.rst b/Documentation/guides/ipa.rst\nnew file mode 100644\nindex 00000000..4b270eb7\n--- /dev/null\n+++ b/Documentation/guides/ipa.rst\n@@ -0,0 +1,112 @@\n+.. SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+IPA Writers Guide\n+=================\n+\n+IPA are Image Processing Algorithm modules. They provide functionality that\n+the pipeline handler can use for image processing.\n+\n+The IPA interface and protocol\n+------------------------------\n+\n+The IPA interface defines the interface between the pipeline handler and the\n+IPA. Specifically, it defines the functions that the IPA exposes that the\n+pipeline handler can call, and the Signals that the pipeline handler can\n+connect to to receive data from the IPA asyncrhonously. In addition, it\n+contains any custom data structures that the pipeline handler and IPA may\n+pass to each other.\n+\n+The IPA protocol refers to the agreement between the pipeline handler and the\n+IPA regarding the expected response(s) from the IPA for given calls to the IPA.\n+This protocol doesn't need to be declared anywhere in code, but it would be\n+useful to document it, as there may be different IPAs for some pipeline handler.\n+\n+The IPA interface must be defined in a mojom file. The interface includes the\n+functions that the pipeline handler can call from the IPA, Signals in the\n+pipeline handler that the IPA can emit, and any data structures that are to\n+be passed between the pipeline handler and the IPA. All IPA of a given pipeline\n+handler use the same IPA interface. The IPA interface definition is thus\n+likely to be written by the pipeline handler author, based on how they imagine\n+the pipeline handler will interact with the IPA.\n+\n+Any custom structs that the IPA interfaces use must be defined in in a file\n+named {pipeline_name}.mojom under include/libcamera/ipa/ using the mojo\n+mojo interface definition language.\n+\n+It is recommended to use namespacing, to avoid potential collisions with\n+libcamera types. Use mojom's module directive for this.\n+\n+The Main IPA interface\n+----------------------\n+\n+The IPA interface is split in two parts, the Main IPA interface, which\n+describes the functions that the pipeline handler can call from the IPA,\n+and the Event IPA interface, which describes the Signals in the pipeline\n+handler that the IPA can emit. Both must be defined. This section focuses\n+on the Main IPA interface.\n+\n+The main interface must be named as IPA{pipeline_name}Interface.\n+\n+At minimum, the following three functions must be present (and implemented):\n+- init(IPASettings settings) => (int32 ret);\n+- start() => (int32 ret);\n+- stop();\n+\n+All three of these functions are synchronous.\n+\n+All input parameters will become const references, except for arithmetic types,\n+which will be passed by value. Output parameters will become pointers, unless\n+there is only one primitive output parameter, in which case it will become a\n+a regular return value.\n+\n+const is not allowed inside of arrays and maps. mojo arrays will become C++\n+std::vector<>.\n+\n+By default, all methods defined in the main interface are synchronous. This\n+means that in the case of IPC (ie. isolated IPA), the function call will not\n+return until the return value or output parameters are ready. To specify an\n+asynchronous function, the [async] attribute can be used. Asynchronous\n+methods must not have any return value or output parameters, since in the\n+case of IPC the call needs to return immediately.\n+\n+It is also possible that the IPA will not be run in isolation. In this case,\n+the IPA thread will not exist until start() is called. This means that in the\n+case of no isolation, asynchronous calls cannot be made before start(). Since\n+the IPA interface must be the same regardless of isolation, the same\n+restriction applies to the case of isolation, and any function that will be\n+called before start() must be synchronous.\n+\n+In addition, any call made after start() and before stop() must be\n+asynchronous. The motivation for this is to avoid damaging real time\n+performance of the pipeline handler. If the pipeline handler wants some data\n+from the IPA, the IPA should return the data asynchronously via an event\n+(see \"The Event IPA interface\").\n+\n+In addition the following must be defined in {pipeline_name}.h in the\n+libcamera namespace:\n+\n+static ControlInfoMap {pipeline_name}::controls;\n+\n+It may be empty. This will be the default ControlInfoMap used when\n+serializing and deserializing any ControlLists if it is not specified\n+in the ControlList.\n+\n+\n+The Event IPA interface\n+-----------------------\n+\n+The event IPA interface describes the Signals in the pipeline handler that the\n+IPA can emit. It must be defined. If there are no event functions, then it may\n+be empty. These emissions are meant to notify the pipeline handler of some\n+event, such as reqeust data is ready, and *must not* be used to drive the\n+camera pipeline from the IPA.\n+\n+The event interface must be named as IPA{pipeline_name}EventInterface.\n+\n+Methods defined in the event interface are implictly asynchronous.\n+They thus can't return any value. Specifying the [async] tag is not\n+necessary.\n+\n+Methods defined in the event interface will become Signals in the IPA\n+interface. The IPA can emit signals, while the pipeline handler can connect\n+slots to them.\ndiff --git a/Documentation/index.rst b/Documentation/index.rst\nindex ff697d4f..8bc8922e 100644\n--- a/Documentation/index.rst\n+++ b/Documentation/index.rst\n@@ -16,4 +16,5 @@\n Developer Guide <guides/introduction>\n Application Writer's Guide <guides/application-developer>\n Pipeline Handler Writer's Guide <guides/pipeline-handler>\n+ IPA Writer's guide <guides/ipa>\n Tracing guide <guides/tracing>\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 59107151..17f3b9d7 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -52,6 +52,7 @@ if sphinx.found()\n 'docs.rst',\n 'index.rst',\n 'guides/introduction.rst',\n+ 'guides/ipa.rst',\n 'guides/application-developer.rst',\n 'guides/pipeline-handler.rst',\n 'guides/tracing.rst',\n", "prefixes": [ "libcamera-devel", "v4", "36/37" ] }