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, parallel and BT.656 buses 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. Also see 64:ref:`async sub-device registration <media-registering-async-subdevs>`. 65 66The runtime PM handlers shall handle clocks, regulators, GPIOs, and other 67system resources required to power the sensor up and down. For drivers that 68don't use any of those resources (such as drivers that support ACPI systems 69only), the runtime PM handlers may be left unimplemented. 70 71In general, the device shall be powered on at least when its registers are 72being 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 75streaming. They may power the device up at probe time (for example to read 76identification registers), but should not keep it powered unconditionally after 77probe. 78 79At system suspend time, the whole camera pipeline must stop streaming, and 80restart when the system is resumed. This requires coordination between the 81camera sensor and the rest of the camera pipeline. Bridge drivers are 82responsible for this coordination, and instruct camera sensors to stop and 83restart streaming by calling the appropriate subdev operations 84(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera 85sensor drivers shall therefore **not** keep track of the streaming state to 86stop streaming in the PM suspend handler and restart it in the resume handler. 87Drivers should in general not implement the system PM handlers. 88 89Camera sensor drivers shall **not** implement the subdev ``.s_power()`` 90operation, as it is deprecated. While this operation is implemented in some 91existing drivers as they predate the deprecation, new drivers shall use runtime 92PM instead. If you feel you need to begin calling ``.s_power()`` from an ISP or 93a bridge driver, instead add runtime PM support to the sensor driver you are 94using and drop its ``.s_power()`` handler. 95 96Please also see :ref:`examples <media-camera-sensor-examples>`. 97 98Control framework 99~~~~~~~~~~~~~~~~~ 100 101``v4l2_ctrl_handler_setup()`` function may not be used in the device's runtime 102PM ``runtime_resume`` callback, as it has no way to figure out the power state 103of the device. This is because the power state of the device is only changed 104after the power state transition has taken place. The ``s_ctrl`` callback can be 105used 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 109The function returns a non-zero value if it succeeded getting the power count or 110runtime PM was disabled, in either of which cases the driver may proceed to 111access the device. 112 113Rotation, orientation and flipping 114---------------------------------- 115 116Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation 117information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to 118register the appropriate controls. 119 120.. _media-camera-sensor-examples: 121 122Example drivers 123--------------- 124 125Features implemented by sensor drivers vary, and depending on the set of 126supported features and other qualities, particular sensor drivers better serve 127the 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) 149