From patchwork Thu Nov 11 10:49:57 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hanlin Chen X-Patchwork-Id: 14553 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id B5C93BDB1C for ; Thu, 11 Nov 2021 10:50:06 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 65B0A6036F; Thu, 11 Nov 2021 11:50:06 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="KKWiTjDN"; dkim-atps=neutral Received: from mail-pj1-x102a.google.com (mail-pj1-x102a.google.com [IPv6:2607:f8b0:4864:20::102a]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 85B896032C for ; Thu, 11 Nov 2021 11:50:05 +0100 (CET) Received: by mail-pj1-x102a.google.com with SMTP id p18-20020a17090ad31200b001a78bb52876so4110070pju.3 for ; Thu, 11 Nov 2021 02:50:05 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=ROJNiBc2iFMi52VCUP8u3Lf6VbIIQpPhjn9nRLoy+ck=; b=KKWiTjDNmJULYQbmiEkDlaRA+wU5AhRc58v2YNx9+a+s4Bc4CDaGIowfwaKES18kTF vgNJIPQhhkzMJmdSerw2hq6DCmvZ1wEbYeRbJQ3HYcR5Mb9x7DRFdKaS1fOkKKvycco7 hGmXGM4cfAX5NYoFdfmXKlRPTtLqI6QAoUbtc= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=ROJNiBc2iFMi52VCUP8u3Lf6VbIIQpPhjn9nRLoy+ck=; b=WOQvJTsUjtv9HokVsk2lEFKqGgG/dLHnCGCrj6IzEF4d6YPNgN7T8luyd89lyDSkcX 9LqwXaD931Ou+MTiUqObZSfmR3pqiUb6U6FLM/7Banu4OTSTHPVyMnb/BavS1KrCZPqQ cAaSdodP2WLdvg9N7timcM8Hkjna/XKO3ZVM3RkroAUjkWkhfGeDGWLK4/Zl8OQSyzQl r/EjDPTQItWu+r9Qiwr6CSfZluWdYtBovleUzI5DsWd65frf6/fW/LqLsBkK0Yfv1tjj yoN7egafQiZx7e7hVd0ZdldaSXteNKp/hiNQ9dVqngC9LaILg5wX/CuqQIM48qcpxJDh JM2w== X-Gm-Message-State: AOAM530B4kejajlY3yXXRa7khYuiTIieY+LvffFYruiqhfEnhlAtE/ZW pmMsIoZIevMLpoXX1DgylQv0TBBSwmTWdQ== X-Google-Smtp-Source: ABdhPJw6j6JeQmhqMp584K5+Kw4HAhMZQe5b+5wOZs6ii3ssnHd/xS2heWOPlk7VbDsDk5kjj4iU3Q== X-Received: by 2002:a17:902:8e87:b0:143:759c:6a2d with SMTP id bg7-20020a1709028e8700b00143759c6a2dmr6902263plb.59.1636627803764; Thu, 11 Nov 2021 02:50:03 -0800 (PST) Received: from localhost ([2401:fa00:1:10:3925:da9c:3049:be7a]) by smtp.gmail.com with UTF8SMTPSA id a3sm2966872pfv.5.2021.11.11.02.50.02 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 11 Nov 2021 02:50:03 -0800 (PST) From: Han-Lin Chen To: libcamera-devel@lists.libcamera.org Date: Thu, 11 Nov 2021 18:49:57 +0800 Message-Id: <20211111104958.312070-2-hanlinchen@chromium.org> X-Mailer: git-send-email 2.34.0.rc1.387.gb447b232ab-goog In-Reply-To: <20211111104958.312070-1-hanlinchen@chromium.org> References: <20211111104958.312070-1-hanlinchen@chromium.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v3 2/3] libcamera: camera_lens: Add a new class to model a camera lens X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The CameraLens class abstracts camera lens and provides helper functions to ease interactions with them. Signed-off-by: Han-Lin Chen Reviewed-by: Kieran Bingham --- Documentation/index.rst | 1 + Documentation/lens_driver_requirements.rst | 28 +++ Documentation/meson.build | 1 + include/libcamera/internal/camera_lens.h | 60 +++++ include/libcamera/internal/meson.build | 1 + src/libcamera/camera_lens.cpp | 253 +++++++++++++++++++++ src/libcamera/meson.build | 1 + 7 files changed, 345 insertions(+) create mode 100644 Documentation/lens_driver_requirements.rst create mode 100644 include/libcamera/internal/camera_lens.h create mode 100644 src/libcamera/camera_lens.cpp diff --git a/Documentation/index.rst b/Documentation/index.rst index 1f4fc485..0ee10044 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -21,3 +21,4 @@ Tracing guide Environment variables Sensor driver requirements + Lens driver requirements diff --git a/Documentation/lens_driver_requirements.rst b/Documentation/lens_driver_requirements.rst new file mode 100644 index 00000000..afc300cf --- /dev/null +++ b/Documentation/lens_driver_requirements.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. _lens-driver-requirements: + +Lens Driver Requirements +======================== + +libcamera handles lens devices in the CameraLens class and defines +a consistent interface through its API towards other library components. + +The CameraLens class uses the V4L2 subdev kernel API to interface with the +camera lens through one or multiple sub-devices exposed in userspace by +the lens driver. + +In order for libcamera to be fully operational and provide all the required +information to interface with the camera lens to applications and pipeline +handlers, a set of mandatory features the driver has to support has been defined. + +Mandatory Requirements +---------------------- + +The lens driver is assumed to be fully compliant with the V4L2 specification. + +The lens driver shall support the following V4L2 controls: + +* `V4L2_CID_FOCUS_ABSOLUTE`_ + +.. _V4L2_CID_FOCUS_ABSOLUTE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-camera.html diff --git a/Documentation/meson.build b/Documentation/meson.build index 4c972675..33af82aa 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -66,6 +66,7 @@ if sphinx.found() 'guides/pipeline-handler.rst', 'guides/tracing.rst', 'index.rst', + 'lens_driver_requirements.rst', 'sensor_driver_requirements.rst', '../README.rst', ] diff --git a/include/libcamera/internal/camera_lens.h b/include/libcamera/internal/camera_lens.h new file mode 100644 index 00000000..fba5d1fa --- /dev/null +++ b/include/libcamera/internal/camera_lens.h @@ -0,0 +1,60 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2021, Google Inc. + * + * camera_lens.h - A camera lens + */ +#ifndef __LIBCAMERA_INTERNAL_CAMERA_LENS_H__ +#define __LIBCAMERA_INTERNAL_CAMERA_LENS_H__ + +#include +#include + +#include +#include "libcamera/internal/v4l2_subdevice.h" + +namespace libcamera { + +class MediaEntity; + +class CameraLens : protected Loggable +{ +public: + explicit CameraLens(const MediaEntity *entity); + ~CameraLens() = default; + + int init(); + + const std::string &model() const { return model_; } + const MediaEntity *entity() const { return entity_; } + + const ControlInfoMap &controls() const; + ControlList getControls(const std::vector &ids); + int setControls(ControlList *ctrls); + + V4L2Subdevice *device() { return subdev_.get(); } + + const ControlList &properties() const { return properties_; } + +protected: + std::string logPrefix() const override; + +private: + LIBCAMERA_DISABLE_COPY(CameraLens) + + int generateId(); + int validateLensDriver(); + int initProperties(); + + const MediaEntity *entity_; + std::unique_ptr subdev_; + + std::string model_; + std::string id_; + + ControlList properties_; +}; + +} /* namespace libcamera */ + +#endif /* __LIBCAMERA_INTERNAL_CAMERA_LENS_H__ */ diff --git a/include/libcamera/internal/meson.build b/include/libcamera/internal/meson.build index 665fd6de..a96bbb95 100644 --- a/include/libcamera/internal/meson.build +++ b/include/libcamera/internal/meson.build @@ -14,6 +14,7 @@ libcamera_internal_headers = files([ 'byte_stream_buffer.h', 'camera.h', 'camera_controls.h', + 'camera_lens.h', 'camera_sensor.h', 'camera_sensor_properties.h', 'control_serializer.h', diff --git a/src/libcamera/camera_lens.cpp b/src/libcamera/camera_lens.cpp new file mode 100644 index 00000000..944f807e --- /dev/null +++ b/src/libcamera/camera_lens.cpp @@ -0,0 +1,253 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2021, Google Inc. + * + * camera_lens.cpp - A camera lens + */ + +#include "libcamera/internal/camera_lens.h" + +#include +#include + +#include "libcamera/internal/media_device.h" +#include "libcamera/internal/sysfs.h" + +/** + * \file camera_lens.h + * \brief A camera lens + */ + +namespace libcamera { + +LOG_DEFINE_CATEGORY(CameraLens) + +/** + * \class CameraLens + * \brief A camera lens based on V4L2 subdevices + * + * The CameraLens class eases handling of lens for pipeline handlers by + * hiding the details of the V4L2 subdevice kernel API and caching lens + * information. + * + * The implementation is currently limited to lens that expose a single V4L2 + * subdevice. It will be extended to support more complex devices as the needs + * arise. + */ + +/** + * \brief Construct a CameraLens + * \param[in] entity The media entity backing the camera lens + * + * Once constructed the instance must be initialized with init(). + */ +CameraLens::CameraLens(const MediaEntity *entity) + : entity_(entity), + properties_(properties::properties) +{ +} + +/** + * \brief Initialize the camera lens instance + * + * This function performs the initialisation steps of the CameraLens that may + * fail. It shall be called once and only once after constructing the instance. + * + * \return 0 on success or a negative error code otherwise + */ +int CameraLens::init() +{ + if (entity_->function() != MEDIA_ENT_F_LENS) { + LOG(CameraLens, Error) + << "Invalid lens function " + << utils::hex(entity_->function()); + return -EINVAL; + } + + /* Create and open the subdev. */ + subdev_ = std::make_unique(entity_); + int ret = subdev_->open(); + if (ret < 0) + return ret; + + ret = validateLensDriver(); + if (ret) + return ret; + + ret = initProperties(); + if (ret) + return ret; + + return 0; +} + +int CameraLens::validateLensDriver() +{ + int err = 0; + static constexpr uint32_t mandatoryControls[] = { + V4L2_CID_FOCUS_ABSOLUTE + }; + + const ControlInfoMap &controls = subdev_->controls(); + for (uint32_t ctrl : mandatoryControls) { + if (!controls.count(ctrl)) { + LOG(CameraLens, Error) + << "Mandatory V4L2 control " << utils::hex(ctrl) + << " not available"; + err = -EINVAL; + } + } + + if (err) { + LOG(CameraLens, Error) + << "The lens kernel driver needs to be fixed"; + LOG(CameraLens, Error) + << "See Documentation/lens_driver_requirements.rst in" + << " the libcamera sources for more information"; + return err; + } + + return 0; +} + +int CameraLens::initProperties() +{ + /* + * Extract the camera lens model name from the media entity name. + * + * There is no standardized naming scheme for lens entities in the + * Linux kernel at the moment. + * + * - The most common rule, used by I2C lens, associates the model + * name with the I2C bus number and address (e.g. 'dw9714 8-000c'). + * + * Other schemes probably exist. As a best effort heuristic, use the + * part of the entity name before the first space if the name contains + * an I2C address, and use the full entity name otherwise. + */ + std::string entityName = entity_->name(); + std::regex i2cRegex{ " [0-9]+-[0-9a-f]{4}" }; + std::smatch match; + + if (std::regex_search(entityName, match, i2cRegex)) + model_ = entityName.substr(0, entityName.find(' ')); + else + model_ = entityName; + + properties_.set(properties::Model, utils::toAscii(model_)); + + return 0; +} + +/** + * \fn CameraLens::model() + * \brief Retrieve the lens model name + * + * The lens model name is a free-formed string that uniquely identifies the + * lens model. + * + * \return The lens model name + */ + +/** + * \fn CameraLens::id() + * \brief Retrieve the lens ID + * + * The lens ID is a free-form string that uniquely identifies the lens in + * the system. + * + * \return The lens ID + */ + +/** + * \fn CameraLens::entity() + * \brief Retrieve the lens media entity + * \return The lens media entity + */ + +/** + * \brief Retrieve the supported V4L2 controls and their information + * + * Control information is updated automatically to reflect the current lens + * configuration when the setFormat() function is called, without invalidating + * any iterator on the ControlInfoMap. + * + * \return A map of the V4L2 controls supported by the lens + */ +const ControlInfoMap &CameraLens::controls() const +{ + return subdev_->controls(); +} + +/** + * \brief Read V4L2 controls from the lens + * \param[in] ids The list of controls to read, specified by their ID + * + * This function reads the value of all controls contained in \a ids, and + * returns their values as a ControlList. The control identifiers are defined by + * the V4L2 specification (V4L2_CID_*). + * + * If any control in \a ids is not supported by the device, is disabled (i.e. + * has the V4L2_CTRL_FLAG_DISABLED flag set), or if any other error occurs + * during validation of the requested controls, no control is read and this + * function returns an empty control list. + * + * \sa V4L2Device::getControls() + * + * \return The control values in a ControlList on success, or an empty list on + * error + */ +ControlList CameraLens::getControls(const std::vector &ids) +{ + return subdev_->getControls(ids); +} + +/** + * \brief Write V4L2 controls to the lens + * \param[in] ctrls The list of controls to write + * + * This function writes the value of all controls contained in \a ctrls, and + * stores the values actually applied to the device in the corresponding \a + * ctrls entry. The control identifiers are defined by the V4L2 specification + * (V4L2_CID_*). + * + * If any control in \a ctrls is not supported by the device, is disabled (i.e. + * has the V4L2_CTRL_FLAG_DISABLED flag set), is read-only, or if any other + * error occurs during validation of the requested controls, no control is + * written and this function returns -EINVAL. + * + * If an error occurs while writing the controls, the index of the first + * control that couldn't be written is returned. All controls below that index + * are written and their values are updated in \a ctrls, while all other + * controls are not written and their values are not changed. + * + * \sa V4L2Device::setControls() + * + * \return 0 on success or an error code otherwise + * \retval -EINVAL One of the control is not supported or not accessible + * \retval i The index of the control that failed + */ +int CameraLens::setControls(ControlList *ctrls) +{ + return subdev_->setControls(ctrls); +} + +/** + * \fn CameraLens::device() + * \brief Retrieve the camera lens device + * \todo Remove this function by integrating DelayedControl with CameraLens + * \return The camera lens device + */ + +/** + * \fn CameraLens::properties() + * \brief Retrieve the camera lens properties + * \return The list of camera lens properties + */ + +std::string CameraLens::logPrefix() const +{ + return "'" + entity_->name() + "'"; +} + +} /* namespace libcamera */ diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 6727a777..3bee8fee 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -5,6 +5,7 @@ libcamera_sources = files([ 'byte_stream_buffer.cpp', 'camera.cpp', 'camera_controls.cpp', + 'camera_lens.cpp', 'camera_manager.cpp', 'camera_sensor.cpp', 'camera_sensor_properties.cpp',