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