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