xref: /linux/Documentation/driver-api/media/camera-sensor.rst (revision 3df692169e8486fc3dd91fcd5ea81c27a0bac033)
1.. SPDX-License-Identifier: GPL-2.0
2
3.. _media_writing_camera_sensor_drivers:
4
5Writing camera sensor drivers
6=============================
7
8This document covers the in-kernel APIs only. For the best practices on
9userspace API implementation in camera sensor drivers, please see
10:ref:`media_using_camera_sensor_drivers`.
11
12CSI-2 and parallel (BT.601 and BT.656) busses
13---------------------------------------------
14
15Please see :ref:`transmitter-receiver`.
16
17Handling clocks
18---------------
19
20Camera sensors have an internal clock tree including a PLL and a number of
21divisors. The clock tree is generally configured by the driver based on a few
22input parameters that are specific to the hardware: the external clock frequency
23and the link frequency. The two parameters generally are obtained from system
24firmware. **No other frequencies should be used in any circumstances.**
25
26The reason why the clock frequencies are so important is that the clock signals
27come out of the SoC, and in many cases a specific frequency is designed to be
28used in the system. Using another frequency may cause harmful effects
29elsewhere. Therefore only the pre-determined frequencies are configurable by the
30user.
31
32ACPI
33~~~~
34
35Read the ``clock-frequency`` _DSD property to denote the frequency. The driver
36can rely on this frequency being used.
37
38Devicetree
39~~~~~~~~~~
40
41The preferred way to achieve this is using ``assigned-clocks``,
42``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See the
43`clock device tree bindings
44<https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml>`_
45for more information. The driver then gets the frequency using
46``clk_get_rate()``.
47
48This approach has the drawback that there's no guarantee that the frequency
49hasn't been modified directly or indirectly by another driver, or supported by
50the board's clock tree to begin with. Changes to the Common Clock Framework API
51are required to ensure reliability.
52
53Power management
54----------------
55
56Camera sensors are used in conjunction with other devices to form a camera
57pipeline. They must obey the rules listed herein to ensure coherent power
58management over the pipeline.
59
60Camera sensor drivers are responsible for controlling the power state of the
61device they otherwise control as well. They shall use runtime PM to manage
62power states. Runtime PM shall be enabled at probe time and disabled at remove
63time. Drivers should enable runtime PM autosuspend.
64
65The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
66system resources required to power the sensor up and down. For drivers that
67don't use any of those resources (such as drivers that support ACPI systems
68only), the runtime PM handlers may be left unimplemented.
69
70In general, the device shall be powered on at least when its registers are
71being accessed and when it is streaming. Drivers should use
72``pm_runtime_resume_and_get()`` when starting streaming and
73``pm_runtime_put()`` or ``pm_runtime_put_autosuspend()`` when stopping
74streaming. They may power the device up at probe time (for example to read
75identification registers), but should not keep it powered unconditionally after
76probe.
77
78At system suspend time, the whole camera pipeline must stop streaming, and
79restart when the system is resumed. This requires coordination between the
80camera sensor and the rest of the camera pipeline. Bridge drivers are
81responsible for this coordination, and instruct camera sensors to stop and
82restart streaming by calling the appropriate subdev operations
83(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera
84sensor drivers shall therefore **not** keep track of the streaming state to
85stop streaming in the PM suspend handler and restart it in the resume handler.
86Drivers should in general not implement the system PM handlers.
87
88Camera sensor drivers shall **not** implement the subdev ``.s_power()``
89operation, as it is deprecated. While this operation is implemented in some
90existing drivers as they predate the deprecation, new drivers shall use runtime
91PM instead. If you feel you need to begin calling ``.s_power()`` from an ISP or
92a bridge driver, instead add runtime PM support to the sensor driver you are
93using and drop its ``.s_power()`` handler.
94
95Please also see :ref:`examples <media-camera-sensor-examples>`.
96
97Control framework
98~~~~~~~~~~~~~~~~~
99
100``v4l2_ctrl_handler_setup()`` function may not be used in the device's runtime
101PM ``runtime_resume`` callback, as it has no way to figure out the power state
102of the device. This is because the power state of the device is only changed
103after the power state transition has taken place. The ``s_ctrl`` callback can be
104used to obtain device's power state after the power state transition:
105
106.. c:function:: int pm_runtime_get_if_in_use(struct device *dev);
107
108The function returns a non-zero value if it succeeded getting the power count or
109runtime PM was disabled, in either of which cases the driver may proceed to
110access the device.
111
112Rotation, orientation and flipping
113----------------------------------
114
115Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation
116information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to
117register the appropriate controls.
118
119.. _media-camera-sensor-examples:
120
121Example drivers
122---------------
123
124Features implemented by sensor drivers vary, and depending on the set of
125supported features and other qualities, particular sensor drivers better serve
126the purpose of an example. The following drivers are known to be good examples:
127
128.. flat-table:: Example sensor drivers
129    :header-rows: 0
130    :widths:      1 1 1 2
131
132    * - Driver name
133      - File(s)
134      - Driver type
135      - Example topic
136    * - CCS
137      - ``drivers/media/i2c/ccs/``
138      - Freely configurable
139      - Power management (ACPI and DT), UAPI
140    * - imx219
141      - ``drivers/media/i2c/imx219.c``
142      - Register list based
143      - Power management (DT), UAPI, mode selection
144    * - imx319
145      - ``drivers/media/i2c/imx319.c``
146      - Register list based
147      - Power management (ACPI and DT)
148