[libcamera-devel,v6,1/6] libcamera: Add V4L2Controls

1504 diff mbox series

Add libcamera V4L2 control support, implemented using the V4L2 Extended
Control APIs. This patch defines the types used to create and manage
controls.

Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
 src/libcamera/include/v4l2_controls.h |  79 ++++++++
 src/libcamera/meson.build             |   1 +
 src/libcamera/v4l2_controls.cpp       | 281 ++++++++++++++++++++++++++
 3 files changed, 361 insertions(+)
 create mode 100644 src/libcamera/include/v4l2_controls.h
 create mode 100644 src/libcamera/v4l2_controls.cpp

Hi Jacopo,

Thank you for the patch.

On Mon, Jun 24, 2019 at 04:28:54PM +0200, Jacopo Mondi wrote:
> Add libcamera V4L2 control support, implemented using the V4L2 Extended
> Control APIs. This patch defines the types used to create and manage
> controls.
> 
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  src/libcamera/include/v4l2_controls.h |  79 ++++++++
>  src/libcamera/meson.build             |   1 +
>  src/libcamera/v4l2_controls.cpp       | 281 ++++++++++++++++++++++++++
>  3 files changed, 361 insertions(+)
>  create mode 100644 src/libcamera/include/v4l2_controls.h
>  create mode 100644 src/libcamera/v4l2_controls.cpp
> 
> diff --git a/src/libcamera/include/v4l2_controls.h b/src/libcamera/include/v4l2_controls.h
> new file mode 100644
> index 000000000000..aad4ef14ed31
> --- /dev/null
> +++ b/src/libcamera/include/v4l2_controls.h
> @@ -0,0 +1,79 @@
> +/* SPDX-License-Identifier: LGPL-2.1-or-later */
> +/*
> + * Copyright (C) 2019, Google Inc.
> + *
> + * v4l2_controls.h - V4L2 Controls Support
> + */
> +
> +#ifndef __LIBCAMERA_V4L2_CONTROLS_H__
> +#define __LIBCAMERA_V4L2_CONTROLS_H__
> +
> +#include <string>
> +#include <vector>
> +
> +#include <stdint.h>
> +
> +#include <linux/v4l2-controls.h>
> +#include <linux/videodev2.h>
> +
> +namespace libcamera {
> +
> +class V4L2ControlInfo
> +{
> +public:
> +	V4L2ControlInfo(const struct v4l2_query_ext_ctrl &ctrl);
> +
> +	unsigned int id() const { return id_; }
> +	unsigned int type() const { return type_; }
> +	size_t size() const { return size_; }
> +	const std::string &name() const { return name_; }
> +
> +private:
> +	unsigned int id_;
> +	unsigned int type_;
> +	size_t size_;
> +	std::string name_;
> +};
> +
> +class V4L2Control
> +{
> +public:
> +	V4L2Control(unsigned int id, int value = 0)
> +		: id_(id), value_(value) {}
> +
> +	int64_t value() const { return value_; }
> +	void setValue(int64_t value) { value_ = value; }
> +
> +	unsigned int id() const { return id_; }
> +
> +private:
> +	unsigned int id_;
> +	int64_t value_;
> +};
> +
> +class V4L2ControlList
> +{
> +public:
> +	using iterator = std::vector<V4L2Control>::iterator;
> +	using const_iterator = std::vector<V4L2Control>::const_iterator;
> +
> +	iterator begin() { return controls_.begin(); }
> +	const_iterator begin() const { return controls_.begin(); }
> +	iterator end() { return controls_.end(); }
> +	const_iterator end() const { return controls_.end(); }
> +
> +	bool empty() const { return controls_.empty(); }
> +	std::size_t size() const { return controls_.size(); }
> +
> +	void clear() { controls_.clear(); }
> +	int add(unsigned int id, int64_t value = 0);
> +
> +	V4L2Control *getControl(unsigned int id);
> +
> +private:
> +	std::vector<V4L2Control> controls_;
> +};
> +
> +} /* namespace libcamera */
> +
> +#endif /* __LIBCAMERA_V4L2_CONTROLS_H__ */
> diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
> index f26ad5b2dc57..985aa7e8ab0e 100644
> --- a/src/libcamera/meson.build
> +++ b/src/libcamera/meson.build
> @@ -23,6 +23,7 @@ libcamera_sources = files([
>      'stream.cpp',
>      'timer.cpp',
>      'utils.cpp',
> +    'v4l2_controls.cpp',
>      'v4l2_device.cpp',
>      'v4l2_subdevice.cpp',
>      'v4l2_videodevice.cpp',
> diff --git a/src/libcamera/v4l2_controls.cpp b/src/libcamera/v4l2_controls.cpp
> new file mode 100644
> index 000000000000..ac932d855dd6
> --- /dev/null
> +++ b/src/libcamera/v4l2_controls.cpp
> @@ -0,0 +1,281 @@
> +/* SPDX-License-Identifier: LGPL-2.1-or-later */
> +/*
> + * Copyright (C) 2019, Google Inc.
> + *
> + * v4l2_controls.cpp - V4L2 Controls Support
> + */
> +
> +#include "v4l2_controls.h"
> +
> +/**
> + * \file v4l2_controls.h
> + * \brief Support for V4L2 Controls using the V4L2 Extended Controls APIs
> + *
> + * The V4L2 Control API allows application to inspect and modify sets of
> + * configurable parameters on the video device or subdevice of interest. The
> + * nature of the parameters an application could modify using the control
> + * framework depends on what the driver implements support for, and on the
> + * characteristics of the underlying hardware platform. Generally controls are
> + * used to modify user visible settings, such as the image brightness and
> + * exposure time, or non-standard parameters which cannot be controlled through
> + * the V4L2 format negotiation API.
> + *
> + * Controls are identified by a numerical ID, defined by the V4L2 kernel headers
> + * and have an associated type. Each control has a value, which is the data that
> + * can be modified with V4L2Device::setControls() or retrieved with
> + * V4L2Device::getControls().
> + *
> + * The control's type along with the control's flags define the type of the
> + * control's value content. Controls can transport a single data value stored in
> + * variable inside the control, or they might as well deal with more complex
> + * data types, such as arrays of matrices, stored in a contiguous memory
> + * locations associated with the control and called 'the payload'. Such controls
> + * are called 'compound controls' and are currently not supported by the
> + * libcamera V4L2 control framework.
> + *
> + * libcamera implements support for controls using the V4L2 Extended Control
> + * API, which allows future handling of controls with payloads of arbitrary
> + * sizes.
> + *
> + * The libcamera V4L2 Controls framework operates on lists of controls, wrapped
> + * by the V4L2ControlList class, to match the V4L2 extended controls API. The
> + * interface to set and get control is implemented by the V4L2Device class, and
> + * this file only provides the data type definitions.
> + *
> + * \todo Add support for compound controls
> + */
> +
> +namespace libcamera {
> +
> +/**
> + * \class V4L2ControlInfo
> + * \brief Information on a V4L2 control
> + *
> + * The V4L2ControlInfo class represents all the information related to a V4L2
> + * control, such as its ID, its type, its user-readable name and the expected
> + * size of its value data.
> + *
> + * V4L2ControlInfo instances are created by inspecting the fieldS of a struct
> + * v4l2_query_ext_ctrl structure, after it has been filled by the device driver
> + * as a consequence of a VIDIOC_QUERY_EXT_CTRL ioctl call.
> + *
> + * This class does not contain the control value, but only static information on
> + * the control, which shall be cached by the caller at initialisation time or
> + * the first time the control information is accessed.
> + */
> +
> +/**
> + * \brief Construct a V4L2ControlInfo from a struct v4l2_query_ext_ctrl
> + * \param ctrl The struct v4l2_query_ext_ctrl as returned by the kernel
> + */
> +V4L2ControlInfo::V4L2ControlInfo(const struct v4l2_query_ext_ctrl &ctrl)
> +{
> +	id_ = ctrl.id;
> +	type_ = ctrl.type;
> +	name_ = static_cast<const char *>(ctrl.name);
> +	size_ = ctrl.elem_size * ctrl.elems;
> +}
> +
> +/**
> + * \fn V4L2ControlInfo::id()
> + * \brief Retrieve the control ID
> + * \return The V4L2 control ID
> + */
> +
> +/**
> + * \fn V4L2ControlInfo::type()
> + * \brief Retrieve the control type as defined by V4L2_CTRL_TYPE_*
> + * \return The V4L2 control type
> + */
> +
> +/**
> + * \fn V4L2ControlInfo::size()
> + * \brief Retrieve the control value data size (in bytes)
> + * \return The V4L2 control value data size
> + */
> +
> +/**
> + * \fn V4L2ControlInfo::name()
> + * \brief Retrieve the control user readable name
> + * \return The V4L2 control user readable name
> + */
> +
> +/**
> + * \class V4L2Control
> + * \brief A V4L2 control value
> + *
> + * The V4L2Control class represent the value of a V4L2 control. The class
> + * stores values that have been read from or will be applied to a V4L2 device.
> + *
> + * The value stored in the class instances does not reflect what is actually
> + * applied to the hardware but is a pure software cache optionally initialized
> + * at control creation time and modified by a control read or write operation.
> + *
> + * The write and read controls the V4L2Control class instances are not meant
> + * to be directly used but are instead intended to be grouped in
> + * V4L2ControlList instances, which are then passed as parameters to
> + * V4L2Device::setControls() and V4L2Device::getControls() operations.
> + */
> +
> +/**
> + * \fn V4L2Control::V4L2Control
> + * \brief Construct a V4L2 control with \a id and \a value
> + * \param id The V4L2 control ID
> + * \param value The control value
> + */
> +
> +/**
> + * \fn V4L2Control::value()
> + * \brief Retrieve the value of the control
> + *
> + * This method returns the cached control value, initially set by
> + * V4L2ControlList::add() and then updated when the controls are read or
> + * written with V4L2Device::getControls() and V4L2Device::setControls().
> + *
> + * \return The V4L2 control value
> + */
> +
> +/**
> + * \fn V4L2Control::setValue()
> + * \brief Set the value of the control
> + * \param value The new V4L2 control value
> + *
> + * This method stores the control value, which will be applied to the
> + * device when calling V4L2Device::setControls().
> + */
> +
> +/**
> + * \fn V4L2Control::id()
> + * \brief Retrieve the control ID this instance refers to
> + * \return The V4L2Control ID
> + */
> +
> +/**
> + * \class V4L2ControlList
> + * \brief Container of V4L2Control instances
> + *
> + * The V4L2ControlList class works as a container for a list of V4L2Control
> + * instances. The class provides operations to add a new control to the list,
> + * get back a control value, and reset the list of controls it contains.
> + *
> + * In order to set and get controls, user of the libcamera V4L2 control
> + * framework should operate on instances of the V4L2ControlList class, and use
> + * them as argument for the V4L2Device::setControls() and
> + * V4L2Device::getControls() operations, which write and read a list of
> + * controls to or from a V4L2 device (a video device or a subdevice).
> + *
> + * Controls are added to a V4L2ControlList instance with the add() method, with
> + * or without a value.
> + *
> + * To write controls to a device, the controls of interest shall be added with
> + * an initial value by calling V4L2ControlList::add(unsigned int id, int64_t
> + * value) to prepare for a write operation. Once the values of all controls of
> + * interest have been added, the V4L2ControlList instance is passed to the
> + * V4L2Device::setControls(), which sets the controls on the device.
> + *
> + * To read controls from a device, the desired controls are added with
> + * V4L2ControlList::add(unsigned int id) to prepare for a read operation. The
> + * V4L2ControlList instance is then passed to V4L2Device::getControls(), which
> + * reads the controls from the device and updates the values stored in
> + * V4L2ControlList.
> + *
> + * V4L2ControlList instances can be reset to remove all controls they contain
> + * and prepare to be re-used for a new control write/read sequence.
> + */
> +
> +/**
> + * \typedef V4L2ControlList::iterator
> + * \brief Iterator on the V4L2 controls contained in the instance
> + */
> +
> +/**
> + * \typedef V4L2ControlList::const_iterator
> + * \brief Const iterator on the V4L2 controls contained in the instance
> + */
> +
> +/**
> + * \fn iterator V4L2ControlList::begin()
> + * \brief Retrieve an iterator to the first V4L2Control in the instance
> + * \return An iterator to the first V4L2 control
> + */
> +
> +/**
> + * \fn const_iterator V4L2ControlList::begin() const
> + * \brief Retrieve a constant iterator to the first V4L2Control in the instance
> + * \return A constant iterator to the first V4L2 control
> + */
> +
> +/**
> + * \fn iterator V4L2ControlList::end()
> + * \brief Retrieve an iterator pointing to the past-the-end V4L2Control in the
> + * instance
> + * \return An iterator to the element following the last V4L2 control in the
> + * instance
> + */
> +
> +/**
> + * \fn const_iterator V4L2ControlList::end() const
> + * \brief Retrieve a constant iterator pointing to the past-the-end V4L2Control
> + * in the instance
> + * \return A constant iterator to the element following the last V4L2 control
> + * in the instance
> + */
> +
> +/**
> + * \fn V4L2ControlList::empty()
> + * \brief Verify if the instance does not contain any control
> + * \return True if the instance does not contain any control, false otherwise
> + */
> +
> +/**
> + * \fn V4L2ControlList::size()
> + * \brief Retrieve the number on controls in the instance
> + * \return The number of V4L2Control stored in the instance
> + */
> +
> +/**
> + * \fn V4L2ControlList::clear()
> + * \brief Remove all controls in the instance
> + */
> +
> +/**
> + * \brief Add control with \a id and optional \a value to the instance
> + * \param id The V4L2 control ID (V4L2_CID_*)
> + * \param value The V4L2 control value
> + *
> + * This methods add a new V4L2 control to the V4L2ControlList. The newly

s/methods add/method adds/

> + * inserted control should be unique (no other control with \a id should be
> + * part of the V4L2 control list) otherwise a negative error code is returned.
> + *
> + * \return 0 on success or a negative error code otherwise
> + * \retval -EBUSY A control with \a id already exists
> + */
> +int V4L2ControlList::add(unsigned int id, int64_t value)
> +{
> +	for (const V4L2Control &ctrl : controls_) {
> +		if (ctrl.id() == id)
> +			return -EBUSY;
> +	}

This makes adding controls a O(n^2) operation :-/ What it be better to
just say that adding two controls with the same ID leads to undefined
results ?

> +
> +	controls_.emplace_back(id, value);
> +
> +	return 0;
> +}
> +
> +/**
> + * \brief Get a pointer the control with \a id
> + * \param id The V4L2 control ID (V4L2_CID_xx)
> + * \return A pointer to the V4L2Control with \a id or nullptr if the
> + * control ID is not part of this instance.
> + */
> +V4L2Control *V4L2ControlList::getControl(unsigned int id)
> +{
> +	for (V4L2Control &ctrl : controls_) {
> +		if (ctrl.id() == id)
> +			return &ctrl;
> +	}
> +
> +	return nullptr;
> +}
> +
> +} /* namespace libcamera */