8.Writing camera sensor drivers¶
This document covers the in-kernel APIs only. For the best practices onuserspace API implementation in camera sensor drivers, please seeUsing camera sensor drivers.
8.1.CSI-2, parallel and BT.656 buses¶
Please seePixel data transmitter and receiver drivers.
8.2.Handling clocks¶
Camera sensors have an internal clock tree including a PLL and a number ofdivisors. The clock tree is generally configured by the driver based on a fewinput parameters that are specific to the hardware: the external clock frequencyand the link frequency. The two parameters generally are obtained from systemfirmware.No other frequencies should be used in any circumstances.
The reason why the clock frequencies are so important is that the clock signalscome out of the SoC, and in many cases a specific frequency is designed to beused in the system. Using another frequency may cause harmful effectselsewhere. Therefore only the pre-determined frequencies are configurable by theuser.
The external clock frequency shall be retrieved by obtaining the external clockusing thedevm_v4l2_sensor_clk_get() helper function, and then getting itsfrequency withclk_get_rate(). Usage of the helper function guaranteescorrect behaviour regardless of whether the sensor is integrated in a DT-basedor ACPI-based system.
8.2.1.ACPI¶
ACPI-based systems typically don’t register the sensor external clock with thekernel, but specify the external clock frequency in theclock-frequency_DSD property. Thedevm_v4l2_sensor_clk_get() helper creates and returns afixed clock set at that rate.
8.2.2.Devicetree¶
Devicetree-based systems declare the sensor external clock in the device treeand reference it from the sensor node. The preferred way to select the externalclock frequency is to use theassigned-clocks,assigned-clock-parentsandassigned-clock-rates properties in the sensor node to set the clockrate. See theclock device tree bindingsfor more information. Thedevm_v4l2_sensor_clk_get() helper retrieves andreturns that clock.
This approach has the drawback that there’s no guarantee that the frequencyhasn’t been modified directly or indirectly by another driver, or supported bythe board’s clock tree to begin with. Changes to the Common Clock Framework APIare required to ensure reliability.
8.3.Power management¶
Camera sensors are used in conjunction with other devices to form a camerapipeline. They must obey the rules listed herein to ensure coherent powermanagement over the pipeline.
Camera sensor drivers are responsible for controlling the power state of thedevice they otherwise control as well. They shall use runtime PM to managepower states. Runtime PM shall be enabled at probe time and disabled at removetime. Drivers should enable runtime PM autosuspend. Also seeasync sub-device registration.
The runtime PM handlers shall handle clocks, regulators, GPIOs, and othersystem resources required to power the sensor up and down. For drivers thatdon’t use any of those resources (such as drivers that support ACPI systemsonly), the runtime PM handlers may be left unimplemented.
In general, the device shall be powered on at least when its registers arebeing accessed and when it is streaming. Drivers should usepm_runtime_resume_and_get() when starting streaming andpm_runtime_put() orpm_runtime_put_autosuspend() when stoppingstreaming. They may power the device up at probe time (for example to readidentification registers), but should not keep it powered unconditionally afterprobe.
At system suspend time, the whole camera pipeline must stop streaming, andrestart when the system is resumed. This requires coordination between thecamera sensor and the rest of the camera pipeline. Bridge drivers areresponsible for this coordination, and instruct camera sensors to stop andrestart streaming by calling the appropriate subdev operations(.enable_streams() or.disable_streams()). Camera sensor drivers shallthereforenot keep track of the streaming state to stop streaming in the PMsuspend handler and restart it in the resume handler. Drivers should in generalnot implement the system PM handlers.
Camera sensor drivers shallnot implement the subdev.s_power()operation, as it is deprecated. While this operation is implemented in someexisting drivers as they predate the deprecation, new drivers shall use runtimePM instead. If you feel you need to begin calling.s_power() from an ISP ora bridge driver, instead add runtime PM support to the sensor driver you areusing and drop its.s_power() handler.
Please also seeexamples.
8.3.1.Control framework¶
v4l2_ctrl_handler_setup() function may not be used in the device’s runtimePMruntime_resume callback, as it has no way to figure out the power stateof the device. This is because the power state of the device is only changedafter the power state transition has taken place. Thes_ctrl callback can beused to obtain device’s power state after the power state transition:
The function returns a non-zero value if it succeeded getting the power count orruntime PM was disabled, in either of which cases the driver may proceed toaccess the device.
8.4.Rotation, orientation and flipping¶
Usev4l2_fwnode_device_parse() to obtain rotation and orientationinformation from system firmware andv4l2_ctrl_new_fwnode_properties() toregister the appropriate controls.
8.5.Example drivers¶
Features implemented by sensor drivers vary, and depending on the set ofsupported features and other qualities, particular sensor drivers better servethe purpose of an example. The following drivers are known to be good examples:
Driver name | File(s) | Driver type | Example topic |
CCS |
| Freely configurable | Power management (ACPI and DT), UAPI |
imx219 |
| Register list based | Power management (DT), UAPI, mode selection |
imx319 |
| Register list based | Power management (ACPI and DT) |