{"id":14417,"url":"https://patchwork.libcamera.org/api/patches/14417/?format=json","web_url":"https://patchwork.libcamera.org/patch/14417/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20211029115917.2467936-3-hanlinchen@chromium.org>","date":"2021-10-29T11:59:16","name":"[libcamera-devel,v2,3/4] libcamera: camera_lens: Add a new class to model a camera lens","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"d3baafa26d803ee6fdd9d3dacb3efdcccfd744c2","submitter":{"id":98,"url":"https://patchwork.libcamera.org/api/people/98/?format=json","name":"Hanlin Chen","email":"hanlinchen@chromium.org"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/14417/mbox/","series":[{"id":2680,"url":"https://patchwork.libcamera.org/api/series/2680/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=2680","date":"2021-10-29T11:59:14","name":"[libcamera-devel,v2,1/4] ipa: ipu3: Extend ipu3 ipa interface for sensor and lens controls","version":2,"mbox":"https://patchwork.libcamera.org/series/2680/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/14417/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/14417/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 0D621BDB1C\n\tfor <parsemail@patchwork.libcamera.org>;\n\tFri, 29 Oct 2021 11:59:37 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id BF877600BF;\n\tFri, 29 Oct 2021 13:59:36 +0200 (CEST)","from mail-pl1-x644.google.com (mail-pl1-x644.google.com\n\t[IPv6:2607:f8b0:4864:20::644])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 053C5600B8\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 29 Oct 2021 13:59:35 +0200 (CEST)","by mail-pl1-x644.google.com with SMTP id n18so6684817plc.2\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 29 Oct 2021 04:59:34 -0700 (PDT)","from localhost ([2401:fa00:1:10:35fe:d53b:684:b538])\n\tby smtp.gmail.com with UTF8SMTPSA id\n\tpj12sm5899656pjb.19.2021.10.29.04.59.31\n\t(version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);\n\tFri, 29 Oct 2021 04:59:32 -0700 (PDT)"],"Authentication-Results":"lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=chromium.org header.i=@chromium.org\n\theader.b=\"dE4PJvvp\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org;\n\ts=google; \n\th=from:to:cc:subject:date:message-id:in-reply-to:references\n\t:mime-version:content-transfer-encoding;\n\tbh=RShkMnw06HwHBhacFLM8plrYrT3Ge6TITOvE4FuF+lc=;\n\tb=dE4PJvvpOwncNQRkUxVSg6acoqxGpv4iXK24q7HAHhlbszYCzM0u5leUKxK0UjX8MV\n\t1LfImkmH41nZ0qhEHQyF/tT+H5ggHyDEaKV9S/maJ251KaqPdwnrU7fXCe4uWvqUwvQW\n\tTEWOnoTxdo2zZ2dQrPV3SZlfy5M5Xw17xhXdY=","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20210112;\n\th=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to\n\t:references:mime-version:content-transfer-encoding;\n\tbh=RShkMnw06HwHBhacFLM8plrYrT3Ge6TITOvE4FuF+lc=;\n\tb=LCP7OZrJSejnLFn7GSQW/HlDPuxvd1bVusWE22dkh/Hn5k5DfQJuJTMIc0vJm9Vlsq\n\tlckMveCM91+Cib0zixMSLeRDJ++v+pgjKzTd6EOGahs3vD8XdLmBFpJtw5oMXlpcf6O9\n\tgdGDY3yNWcwR/BD9frtJ6qtiPyU4+uFJuSLDUeGAXzDDSkrYGeqjk3RWngYWvlZ+ICSD\n\ty25HMQ97SJd0KcLjkE4e2Xa25mp+RpgUhmtvrjgSr3jVx2U/ptGra1A6fQvDVSGNe6EH\n\tpeYs5UNJL0VHxZkdhPT5NxIy/ngtqKrhWd+XJSaa/m06b+TCUF9/kstwBcrlWnaxJPfc\n\tthpg==","X-Gm-Message-State":"AOAM531Hp2uIlqHpKChstjD2Og81/a8fteHikB1y5AoM1X9VSEICd09P\n\tD4EI8v4e1esiytOAWGREcxJkon2du7YUHtmU","X-Google-Smtp-Source":"ABdhPJyRxXoZj6lxVc9m7XZUpanscxFCxs8Dr46RDak+lSJsaEsM7ovZxiT9zR1zH6iVqjzI1TetmQ==","X-Received":"by 2002:a17:90a:a609:: with SMTP id\n\tc9mr19776182pjq.134.1635508772741; \n\tFri, 29 Oct 2021 04:59:32 -0700 (PDT)","From":"Han-Lin Chen <hanlinchen@chromium.org>","To":"libcamera-devel@lists.libcamera.org","Date":"Fri, 29 Oct 2021 19:59:16 +0800","Message-Id":"<20211029115917.2467936-3-hanlinchen@chromium.org>","X-Mailer":"git-send-email 2.33.1.1089.g2158813163f-goog","In-Reply-To":"<20211029115917.2467936-1-hanlinchen@chromium.org>","References":"<20211029115917.2467936-1-hanlinchen@chromium.org>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH v2 3/4] libcamera: camera_lens: Add a new\n\tclass to model a camera lens","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>","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>"},"content":"The CameraLens class abstracts camera lens and provides helper\nfunctions to ease interactions with them.\n\nSigned-off-by: Han-Lin Chen <hanlinchen@chromium.org>\n---\n Documentation/index.rst                    |   1 +\n Documentation/lens_driver_requirements.rst |  28 +++\n Documentation/meson.build                  |   1 +\n include/libcamera/internal/camera_lens.h   |  60 +++++\n src/libcamera/camera_lens.cpp              | 261 +++++++++++++++++++++\n src/libcamera/meson.build                  |   1 +\n 6 files changed, 352 insertions(+)\n create mode 100644 Documentation/lens_driver_requirements.rst\n create mode 100644 include/libcamera/internal/camera_lens.h\n create mode 100644 src/libcamera/camera_lens.cpp","diff":"diff --git a/Documentation/index.rst b/Documentation/index.rst\nindex 1f4fc485..0ee10044 100644\n--- a/Documentation/index.rst\n+++ b/Documentation/index.rst\n@@ -21,3 +21,4 @@\n    Tracing guide <guides/tracing>\n    Environment variables <environment_variables>\n    Sensor driver requirements <sensor_driver_requirements>\n+   Lens driver requirements <lens_driver_requirements>\ndiff --git a/Documentation/lens_driver_requirements.rst b/Documentation/lens_driver_requirements.rst\nnew file mode 100644\nindex 00000000..afc300cf\n--- /dev/null\n+++ b/Documentation/lens_driver_requirements.rst\n@@ -0,0 +1,28 @@\n+.. SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+.. _lens-driver-requirements:\n+\n+Lens Driver Requirements\n+========================\n+\n+libcamera handles lens devices in the CameraLens class and defines\n+a consistent interface through its API towards other library components.\n+\n+The CameraLens class uses the V4L2 subdev kernel API to interface with the\n+camera lens through one or multiple sub-devices exposed in userspace by\n+the lens driver.\n+\n+In order for libcamera to be fully operational and provide all the required\n+information to interface with the camera lens to applications and pipeline\n+handlers, a set of mandatory features the driver has to support has been defined.\n+\n+Mandatory Requirements\n+----------------------\n+\n+The lens driver is assumed to be fully compliant with the V4L2 specification.\n+\n+The lens driver shall support the following V4L2 controls:\n+\n+* `V4L2_CID_FOCUS_ABSOLUTE`_\n+\n+.. _V4L2_CID_FOCUS_ABSOLUTE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-camera.html\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex df36a808..6a1ef164 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -61,6 +61,7 @@ if sphinx.found()\n         'guides/pipeline-handler.rst',\n         'guides/tracing.rst',\n         'index.rst',\n+        'lens_driver_requirements.rst',\n         'sensor_driver_requirements.rst',\n        '../README.rst',\n     ]\ndiff --git a/include/libcamera/internal/camera_lens.h b/include/libcamera/internal/camera_lens.h\nnew file mode 100644\nindex 00000000..c558ea4f\n--- /dev/null\n+++ b/include/libcamera/internal/camera_lens.h\n@@ -0,0 +1,60 @@\n+/* SPDX-License-Identifier: LGPL-2.1-or-later */\n+/*\n+ * Copyright (C) 2021, Google Inc.\n+ *\n+ * camera_lens.h - A camera lens\n+ */\n+#ifndef __LIBCAMERA_INTERNAL_CAMERA_LENS_H__\n+#define __LIBCAMERA_INTERNAL_CAMERA_LENS_H__\n+\n+#include <libcamera/base/class.h>\n+#include <libcamera/base/log.h>\n+\n+#include <libcamera/controls.h>\n+#include \"libcamera/internal/v4l2_subdevice.h\"\n+\n+namespace libcamera {\n+\n+class MediaEntity;\n+\n+class CameraLens : protected Loggable\n+{\n+public:\n+\texplicit CameraLens(const MediaEntity *entity);\n+\t~CameraLens();\n+\n+\tint init();\n+\n+\tconst std::string &model() const { return model_; }\n+\tconst MediaEntity *entity() const { return entity_; }\n+\n+\tconst ControlInfoMap &controls() const;\n+\tControlList getControls(const std::vector<uint32_t> &ids);\n+\tint setControls(ControlList *ctrls);\n+\n+\tV4L2Subdevice *device() { return subdev_.get(); }\n+\n+\tconst ControlList &properties() const { return properties_; }\n+\n+protected:\n+\tstd::string logPrefix() const override;\n+\n+private:\n+\tLIBCAMERA_DISABLE_COPY(CameraLens)\n+\n+\tint generateId();\n+\tint validateLensDriver();\n+\tint initProperties();\n+\n+\tconst MediaEntity *entity_;\n+\tstd::unique_ptr<V4L2Subdevice> subdev_;\n+\n+\tstd::string model_;\n+\tstd::string id_;\n+\n+\tControlList properties_;\n+};\n+\n+} /* namespace libcamera */\n+\n+#endif /* __LIBCAMERA_INTERNAL_CAMERA_LENS_H__ */\ndiff --git a/src/libcamera/camera_lens.cpp b/src/libcamera/camera_lens.cpp\nnew file mode 100644\nindex 00000000..8529737c\n--- /dev/null\n+++ b/src/libcamera/camera_lens.cpp\n@@ -0,0 +1,261 @@\n+/* SPDX-License-Identifier: LGPL-2.1-or-later */\n+/*\n+ * Copyright (C) 2021, Google Inc.\n+ *\n+ * camera_lens.cpp - A camera lens\n+ */\n+\n+#include \"libcamera/internal/camera_lens.h\"\n+#include \"libcamera/internal/media_device.h\"\n+\n+#include <regex>\n+\n+#include <libcamera/property_ids.h>\n+\n+#include \"libcamera/internal/sysfs.h\"\n+\n+/**\n+ * \\file camera_lens.h\n+ * \\brief A camera lens\n+ */\n+\n+namespace libcamera {\n+\n+LOG_DEFINE_CATEGORY(CameraLens)\n+\n+/**\n+ * \\class CameraLens\n+ * \\brief A camera lens based on V4L2 subdevices\n+ *\n+ * The CameraLens class eases handling of lens for pipeline handlers by\n+ * hiding the details of the V4L2 subdevice kernel API and caching lens\n+ * information.\n+ *\n+ * The implementation is currently limited to lens that expose a single V4L2\n+ * subdevice. It will be extended to support more complex devices as the needs\n+ * arise.\n+ */\n+\n+/**\n+ * \\brief Construct a CameraLens\n+ * \\param[in] entity The media entity backing the camera lens\n+ *\n+ * Once constructed the instance must be initialized with init().\n+ */\n+CameraLens::CameraLens(const MediaEntity *entity)\n+\t: entity_(entity),\n+\t  properties_(properties::properties)\n+{\n+}\n+\n+/**\n+ * \\brief Destroy a CameraLens\n+ */\n+CameraLens::~CameraLens()\n+{\n+}\n+\n+/**\n+ * \\brief Initialize the camera lens instance\n+ *\n+ * This function performs the initialisation steps of the CameraLens that may\n+ * fail. It shall be called once and only once after constructing the instance.\n+ *\n+ * \\return 0 on success or a negative error code otherwise\n+ */\n+int CameraLens::init()\n+{\n+\tif (entity_->function() != MEDIA_ENT_F_LENS) {\n+\t\tLOG(CameraLens, Error)\n+\t\t\t<< \"Invalid lens function \"\n+\t\t\t<< utils::hex(entity_->function());\n+\t\treturn -EINVAL;\n+\t}\n+\n+\t/* Create and open the subdev. */\n+\tsubdev_ = std::make_unique<V4L2Subdevice>(entity_);\n+\tint ret = subdev_->open();\n+\tif (ret < 0)\n+\t\treturn ret;\n+\n+\tret = validateLensDriver();\n+\tif (ret)\n+\t\treturn ret;\n+\n+\tret = initProperties();\n+\tif (ret)\n+\t\treturn ret;\n+\n+\treturn 0;\n+}\n+\n+int CameraLens::validateLensDriver()\n+{\n+\tint err = 0;\n+\tstatic constexpr uint32_t mandatoryControls[] = {\n+\t\tV4L2_CID_FOCUS_ABSOLUTE\n+\t};\n+\n+\tconst ControlInfoMap &controls = subdev_->controls();\n+\tfor (uint32_t ctrl : mandatoryControls) {\n+\t\tif (!controls.count(ctrl)) {\n+\t\t\tLOG(CameraLens, Error)\n+\t\t\t\t<< \"Mandatory V4L2 control \" << utils::hex(ctrl)\n+\t\t\t\t<< \" not available\";\n+\t\t\terr = -EINVAL;\n+\t\t}\n+\t}\n+\n+\tif (err) {\n+\t\tLOG(CameraLens, Error)\n+\t\t\t<< \"The lens kernel driver needs to be fixed\";\n+\t\tLOG(CameraLens, Error)\n+\t\t\t<< \"See Documentation/lens_driver_requirements.rst in\n+\t\t\t<< \" the libcamera sources for more information\";\n+\t\treturn err;\n+\t}\n+\n+\treturn 0;\n+}\n+\n+int CameraLens::initProperties()\n+{\n+\t/*\n+\t * Extract the camera lens model name from the media entity name.\n+\t *\n+\t * There is no standardized naming scheme for lens entities in the\n+\t * Linux kernel at the moment.\n+\t *\n+\t * - The most common rule, used by I2C lens, associates the model\n+\t *   name with the I2C bus number and address (e.g. 'dw9714 8-000c').\n+\t *\n+\t * Other schemes probably exist. As a best effort heuristic, use the\n+\t * part of the entity name before the first space if the name contains\n+\t * an I2C address, and use the full entity name otherwise.\n+\t */\n+\tstd::string entityName = entity_->name();\n+\tstd::regex i2cRegex{ \" [0-9]+-[0-9a-f]{4}\" };\n+\tstd::smatch match;\n+\n+\tif (std::regex_search(entityName, match, i2cRegex))\n+\t\tmodel_ = entityName.substr(0, entityName.find(' '));\n+\telse\n+\t\tmodel_ = entityName;\n+\n+\tproperties_.set(properties::Model, utils::toAscii(model_));\n+\n+\treturn 0;\n+}\n+\n+/**\n+ * \\fn CameraLens::model()\n+ * \\brief Retrieve the lens model name\n+ *\n+ * The lens model name is a free-formed string that uniquely identifies the\n+ * lens model.\n+ *\n+ * \\return The lens model name\n+ */\n+\n+/**\n+ * \\fn CameraLens::id()\n+ * \\brief Retrieve the lens ID\n+ *\n+ * The lens ID is a free-form string that uniquely identifies the lens in\n+ * the system.\n+ *\n+ * \\return The lens ID\n+ */\n+\n+/**\n+ * \\fn CameraLens::entity()\n+ * \\brief Retrieve the lens media entity\n+ * \\return The lens media entity\n+ */\n+\n+/**\n+ * \\brief Retrieve the supported V4L2 controls and their information\n+ *\n+ * Control information is updated automatically to reflect the current lens\n+ * configuration when the setFormat() function is called, without invalidating\n+ * any iterator on the ControlInfoMap.\n+ *\n+ * \\return A map of the V4L2 controls supported by the lens\n+ */\n+const ControlInfoMap &CameraLens::controls() const\n+{\n+\treturn subdev_->controls();\n+}\n+\n+/**\n+ * \\brief Read V4L2 controls from the lens\n+ * \\param[in] ids The list of controls to read, specified by their ID\n+ *\n+ * This function reads the value of all controls contained in \\a ids, and\n+ * returns their values as a ControlList. The control identifiers are defined by\n+ * the V4L2 specification (V4L2_CID_*).\n+ *\n+ * If any control in \\a ids is not supported by the device, is disabled (i.e.\n+ * has the V4L2_CTRL_FLAG_DISABLED flag set), or if any other error occurs\n+ * during validation of the requested controls, no control is read and this\n+ * function returns an empty control list.\n+ *\n+ * \\sa V4L2Device::getControls()\n+ *\n+ * \\return The control values in a ControlList on success, or an empty list on\n+ * error\n+ */\n+ControlList CameraLens::getControls(const std::vector<uint32_t> &ids)\n+{\n+\treturn subdev_->getControls(ids);\n+}\n+\n+/**\n+ * \\brief Write V4L2 controls to the lens\n+ * \\param[in] ctrls The list of controls to write\n+ *\n+ * This function writes the value of all controls contained in \\a ctrls, and\n+ * stores the values actually applied to the device in the corresponding \\a\n+ * ctrls entry. The control identifiers are defined by the V4L2 specification\n+ * (V4L2_CID_*).\n+ *\n+ * If any control in \\a ctrls is not supported by the device, is disabled (i.e.\n+ * has the V4L2_CTRL_FLAG_DISABLED flag set), is read-only, or if any other\n+ * error occurs during validation of the requested controls, no control is\n+ * written and this function returns -EINVAL.\n+ *\n+ * If an error occurs while writing the controls, the index of the first\n+ * control that couldn't be written is returned. All controls below that index\n+ * are written and their values are updated in \\a ctrls, while all other\n+ * controls are not written and their values are not changed.\n+ *\n+ * \\sa V4L2Device::setControls()\n+ *\n+ * \\return 0 on success or an error code otherwise\n+ * \\retval -EINVAL One of the control is not supported or not accessible\n+ * \\retval i The index of the control that failed\n+ */\n+int CameraLens::setControls(ControlList *ctrls)\n+{\n+\treturn subdev_->setControls(ctrls);\n+}\n+\n+/**\n+ * \\fn CameraLens::device()\n+ * \\brief Retrieve the camera lens device\n+ * \\todo Remove this function by integrating DelayedControl with CameraLens\n+ * \\return The camera lens device\n+ */\n+\n+/**\n+ * \\fn CameraLens::properties()\n+ * \\brief Retrieve the camera lens properties\n+ * \\return The list of camera lens properties\n+ */\n+\n+std::string CameraLens::logPrefix() const\n+{\n+\treturn \"'\" + entity_->name() + \"'\";\n+}\n+\n+} /* namespace libcamera */\ndiff --git a/src/libcamera/meson.build b/src/libcamera/meson.build\nindex 6727a777..3bee8fee 100644\n--- a/src/libcamera/meson.build\n+++ b/src/libcamera/meson.build\n@@ -5,6 +5,7 @@ libcamera_sources = files([\n     'byte_stream_buffer.cpp',\n     'camera.cpp',\n     'camera_controls.cpp',\n+    'camera_lens.cpp',\n     'camera_manager.cpp',\n     'camera_sensor.cpp',\n     'camera_sensor_properties.cpp',\n","prefixes":["libcamera-devel","v2","3/4"]}