| .. SPDX-License-Identifier: GPL-2.0 |
| |
| .. _media_using_camera_sensor_drivers: |
| |
| Using camera sensor drivers |
| =========================== |
| |
| This section describes common practices for how the V4L2 sub-device interface is |
| used to control the camera sensor drivers. |
| |
| You may also find :ref:`media_writing_camera_sensor_drivers` useful. |
| |
| Frame size |
| ---------- |
| |
| There are two distinct ways to configure the frame size produced by camera |
| sensors. |
| |
| Freely configurable camera sensor drivers |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Freely configurable camera sensor drivers expose the device's internal |
| processing pipeline as one or more sub-devices with different cropping and |
| scaling configurations. The output size of the device is the result of a series |
| of cropping and scaling operations from the device's pixel array's size. |
| |
| An example of such a driver is the CCS driver. |
| |
| Register list based drivers |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Register list based drivers generally, instead of able to configure the device |
| they control based on user requests, are limited to a number of preset |
| configurations that combine a number of different parameters that on hardware |
| level are independent. How a driver picks such configuration is based on the |
| format set on a source pad at the end of the device's internal pipeline. |
| |
| Most sensor drivers are implemented this way. |
| |
| Frame interval configuration |
| ---------------------------- |
| |
| There are two different methods for obtaining possibilities for different frame |
| intervals as well as configuring the frame interval. Which one to implement |
| depends on the type of the device. |
| |
| Raw camera sensors |
| ~~~~~~~~~~~~~~~~~~ |
| |
| Instead of a high level parameter such as frame interval, the frame interval is |
| a result of the configuration of a number of camera sensor implementation |
| specific parameters. Luckily, these parameters tend to be the same for more or |
| less all modern raw camera sensors. |
| |
| The frame interval is calculated using the following equation:: |
| |
| frame interval = (analogue crop width + horizontal blanking) * |
| (analogue crop height + vertical blanking) / pixel rate |
| |
| The formula is bus independent and is applicable for raw timing parameters on |
| large variety of devices beyond camera sensors. Devices that have no analogue |
| crop, use the full source image size, i.e. pixel array size. |
| |
| Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and |
| ``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control |
| is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in |
| the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same |
| sub-device. The unit of that control is pixels per second. |
| |
| Register list based drivers need to implement read-only sub-device nodes for the |
| purpose. Devices that are not register list based need these to configure the |
| device's internal processing pipeline. |
| |
| The first entity in the linear pipeline is the pixel array. The pixel array may |
| be followed by other entities that are there to allow configuring binning, |
| skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION |
| <VIDIOC_SUBDEV_G_SELECTION>`. |
| |
| USB cameras etc. devices |
| ~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| USB video class hardware, as well as many cameras offering a similar higher |
| level interface natively, generally use the concept of frame interval (or frame |
| rate) on device level in firmware or hardware. This means lower level controls |
| implemented by raw cameras may not be used on uAPI (or even kAPI) to control the |
| frame interval on these devices. |
| |
| Rotation, orientation and flipping |
| ---------------------------------- |
| |
| Some systems have the camera sensor mounted upside down compared to its natural |
| mounting rotation. In such cases, drivers shall expose the information to |
| userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION |
| <v4l2-camera-sensor-rotation>` control. |
| |
| Sensor drivers shall also report the sensor's mounting orientation with the |
| :ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`. |
| |
| Sensor drivers that have any vertical or horizontal flips embedded in the |
| register programming sequences shall initialize the :ref:`V4L2_CID_HFLIP |
| <v4l2-cid-hflip>` and :ref:`V4L2_CID_VFLIP <v4l2-cid-vflip>` controls with the |
| values programmed by the register sequences. The default values of these |
| controls shall be 0 (disabled). Especially these controls shall not be inverted, |
| independently of the sensor's mounting rotation. |
