| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
.. _media_using_camera_sensor_drivers: |
| 4 |
|
| 5 |
Using camera sensor drivers |
| 6 |
=========================== |
| 7 |
|
| 8 |
This section describes common practices for how the V4L2 sub-device interface is |
| 9 |
used to control the camera sensor drivers. |
| 10 |
|
| 11 |
You may also find :ref:`media_writing_camera_sensor_drivers` useful. |
| 12 |
|
| 13 |
Sensor internal pipeline configuration |
| 14 |
-------------------------------------- |
| 15 |
|
| 16 |
Camera sensors have an internal processing pipeline including cropping and |
| 17 |
binning functionality. The sensor drivers belong to two distinct classes, freely |
| 18 |
configurable and register list-based drivers, depending on how the driver |
| 19 |
configures this functionality. |
| 20 |
|
| 21 |
Freely configurable camera sensor drivers |
| 22 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 23 |
|
| 24 |
Freely configurable camera sensor drivers expose the device's internal |
| 25 |
processing pipeline as one or more sub-devices with different cropping and |
| 26 |
scaling configurations. The output size of the device is the result of a series |
| 27 |
of cropping and scaling operations from the device's pixel array's size. |
| 28 |
|
| 29 |
An example of such a driver is the CCS driver. |
| 30 |
|
| 31 |
Register list-based drivers |
| 32 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 33 |
|
| 34 |
Register list-based drivers generally, instead of able to configure the device |
| 35 |
they control based on user requests, are limited to a number of preset |
| 36 |
configurations that combine a number of different parameters that on hardware |
| 37 |
level are independent. How a driver picks such configuration is based on the |
| 38 |
format set on a source pad at the end of the device's internal pipeline. |
| 39 |
|
| 40 |
Most sensor drivers are implemented this way. |
| 41 |
|
| 42 |
Frame interval configuration |
| 43 |
---------------------------- |
| 44 |
|
| 45 |
There are two different methods for obtaining possibilities for different frame |
| 46 |
intervals as well as configuring the frame interval. Which one to implement |
| 47 |
depends on the type of the device. |
| 48 |
|
| 49 |
Raw camera sensors |
| 50 |
~~~~~~~~~~~~~~~~~~ |
| 51 |
|
| 52 |
Instead of a high level parameter such as frame interval, the frame interval is |
| 53 |
a result of the configuration of a number of camera sensor implementation |
| 54 |
specific parameters. Luckily, these parameters tend to be the same for more or |
| 55 |
less all modern raw camera sensors. |
| 56 |
|
| 57 |
The frame interval is calculated using the following equation:: |
| 58 |
|
| 59 |
frame interval = (analogue crop width + horizontal blanking) * |
| 60 |
(analogue crop height + vertical blanking) / pixel rate |
| 61 |
|
| 62 |
The formula is bus independent and is applicable for raw timing parameters on |
| 63 |
large variety of devices beyond camera sensors. Devices that have no analogue |
| 64 |
crop, use the full source image size, i.e. pixel array size. |
| 65 |
|
| 66 |
Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and |
| 67 |
``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control |
| 68 |
is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in |
| 69 |
the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same |
| 70 |
sub-device. The unit of that control is pixels per second. |
| 71 |
|
| 72 |
Register list-based drivers need to implement read-only sub-device nodes for the |
| 73 |
purpose. Devices that are not register list based need these to configure the |
| 74 |
device's internal processing pipeline. |
| 75 |
|
| 76 |
The first entity in the linear pipeline is the pixel array. The pixel array may |
| 77 |
be followed by other entities that are there to allow configuring binning, |
| 78 |
skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION |
| 79 |
<VIDIOC_SUBDEV_G_SELECTION>`. |
| 80 |
|
| 81 |
USB cameras etc. devices |
| 82 |
~~~~~~~~~~~~~~~~~~~~~~~~ |
| 83 |
|
| 84 |
USB video class hardware, as well as many cameras offering a similar higher |
| 85 |
level interface natively, generally use the concept of frame interval (or frame |
| 86 |
rate) on device level in firmware or hardware. This means lower level controls |
| 87 |
implemented by raw cameras may not be used on uAPI (or even kAPI) to control the |
| 88 |
frame interval on these devices. |
| 89 |
|
| 90 |
Rotation, orientation and flipping |
| 91 |
---------------------------------- |
| 92 |
|
| 93 |
Some systems have the camera sensor mounted upside down compared to its natural |
| 94 |
mounting rotation. In such cases, drivers shall expose the information to |
| 95 |
userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION |
| 96 |
<v4l2-camera-sensor-rotation>` control. |
| 97 |
|
| 98 |
Sensor drivers shall also report the sensor's mounting orientation with the |
| 99 |
:ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`. |
| 100 |
|
| 101 |
Sensor drivers that have any vertical or horizontal flips embedded in the |
| 102 |
register programming sequences shall initialize the :ref:`V4L2_CID_HFLIP |
| 103 |
<v4l2-cid-hflip>` and :ref:`V4L2_CID_VFLIP <v4l2-cid-vflip>` controls with the |
| 104 |
values programmed by the register sequences. The default values of these |
| 105 |
controls shall be 0 (disabled). Especially these controls shall not be inverted, |
| 106 |
independently of the sensor's mounting rotation. |