libcamera: camera_lens: Add a new class to model a camera lens

The CameraLens class abstracts camera lens and provides helper
functions to ease interactions with them.

Signed-off-by: Han-Lin Chen <hanlinchen@chromium.org>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Umang Jain <umang.jain@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

src/libcamera/camera_lens.cpp

@@ -0,0 +1,142 @@
+/* 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 <libcamera/base/utils.h>
+
+#include "libcamera/internal/v4l2_subdevice.h"
+
+/**
+ * \file camera_lens.h
+ * \brief A camera lens controller
+ */
+
+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.
+ */
+
+/**
+ * \brief Construct a CameraLens
+ * \param[in] entity The media entity backing the camera lens controller
+ *
+ * Once constructed the instance must be initialized with init().
+ */
+CameraLens::CameraLens(const MediaEntity *entity)
+	: entity_(entity)
+{
+}
+
+/**
+ * \brief Destroy a CameraLens
+ */
+CameraLens::~CameraLens() = default;
+
+/**
+ * \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<V4L2Subdevice>(entity_);
+	int ret = subdev_->open();
+	if (ret < 0)
+		return ret;
+
+	ret = validateLensDriver();
+	if (ret)
+		return ret;
+
+	model_ = subdev_->model();
+	return 0;
+}
+
+/**
+ * \brief This function sets the focal point of the lens to a specific position.
+ * \param[in] position The focal point of the lens
+ *
+ * This function sets the value of focal point of the lens as in \a position.
+ *
+ * \return 0 on success or -EINVAL otherwise
+ */
+int CameraLens::setFocusPostion(int32_t position)
+{
+	ControlList lensCtrls(subdev_->controls());
+	lensCtrls.set(V4L2_CID_FOCUS_ABSOLUTE, static_cast<int32_t>(position));
+
+	if (subdev_->setControls(&lensCtrls))
+		return -EINVAL;
+
+	return 0;
+}
+
+int CameraLens::validateLensDriver()
+{
+	int ret = 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";
+			ret = -EINVAL;
+		}
+	}
+
+	if (ret) {
+		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 ret;
+	}
+
+	return ret;
+}
+
+/**
+ * \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
+ */
+
+std::string CameraLens::logPrefix() const
+{
+	return "'" + entity_->name() + "'";
+}
+
+} /* namespace libcamera */

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',