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