149 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3.. _media_writing_camera_sensor_drivers:4 5Writing camera sensor drivers6=============================7 8This document covers the in-kernel APIs only. For the best practices on9userspace API implementation in camera sensor drivers, please see10:ref:`media_using_camera_sensor_drivers`.11 12CSI-2, parallel and BT.656 buses13--------------------------------14 15Please see :ref:`transmitter-receiver`.16 17Handling clocks18---------------19 20Camera sensors have an internal clock tree including a PLL and a number of21divisors. The clock tree is generally configured by the driver based on a few22input parameters that are specific to the hardware: the external clock frequency23and the link frequency. The two parameters generally are obtained from system24firmware. **No other frequencies should be used in any circumstances.**25 26The reason why the clock frequencies are so important is that the clock signals27come out of the SoC, and in many cases a specific frequency is designed to be28used in the system. Using another frequency may cause harmful effects29elsewhere. Therefore only the pre-determined frequencies are configurable by the30user.31 32ACPI33~~~~34 35Read the ``clock-frequency`` _DSD property to denote the frequency. The driver36can rely on this frequency being used.37 38Devicetree39~~~~~~~~~~40 41The preferred way to achieve this is using ``assigned-clocks``,42``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See the43`clock device tree bindings44<https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml>`_45for more information. The driver then gets the frequency using46``clk_get_rate()``.47 48This approach has the drawback that there's no guarantee that the frequency49hasn't been modified directly or indirectly by another driver, or supported by50the board's clock tree to begin with. Changes to the Common Clock Framework API51are required to ensure reliability.52 53Power management54----------------55 56Camera sensors are used in conjunction with other devices to form a camera57pipeline. They must obey the rules listed herein to ensure coherent power58management over the pipeline.59 60Camera sensor drivers are responsible for controlling the power state of the61device they otherwise control as well. They shall use runtime PM to manage62power states. Runtime PM shall be enabled at probe time and disabled at remove63time. Drivers should enable runtime PM autosuspend. Also see64:ref:`async sub-device registration <media-registering-async-subdevs>`.65 66The runtime PM handlers shall handle clocks, regulators, GPIOs, and other67system resources required to power the sensor up and down. For drivers that68don't use any of those resources (such as drivers that support ACPI systems69only), the runtime PM handlers may be left unimplemented.70 71In general, the device shall be powered on at least when its registers are72being accessed and when it is streaming. Drivers should use73``pm_runtime_resume_and_get()`` when starting streaming and74``pm_runtime_put()`` or ``pm_runtime_put_autosuspend()`` when stopping75streaming. They may power the device up at probe time (for example to read76identification registers), but should not keep it powered unconditionally after77probe.78 79At system suspend time, the whole camera pipeline must stop streaming, and80restart when the system is resumed. This requires coordination between the81camera sensor and the rest of the camera pipeline. Bridge drivers are82responsible for this coordination, and instruct camera sensors to stop and83restart streaming by calling the appropriate subdev operations84(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera85sensor drivers shall therefore **not** keep track of the streaming state to86stop 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 some91existing drivers as they predate the deprecation, new drivers shall use runtime92PM instead. If you feel you need to begin calling ``.s_power()`` from an ISP or93a bridge driver, instead add runtime PM support to the sensor driver you are94using and drop its ``.s_power()`` handler.95 96Please also see :ref:`examples <media-camera-sensor-examples>`.97 98Control framework99~~~~~~~~~~~~~~~~~100 101``v4l2_ctrl_handler_setup()`` function may not be used in the device's runtime102PM ``runtime_resume`` callback, as it has no way to figure out the power state103of the device. This is because the power state of the device is only changed104after the power state transition has taken place. The ``s_ctrl`` callback can be105used 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 or110runtime PM was disabled, in either of which cases the driver may proceed to111access the device.112 113Rotation, orientation and flipping114----------------------------------115 116Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation117information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to118register the appropriate controls.119 120.. _media-camera-sensor-examples:121 122Example drivers123---------------124 125Features implemented by sensor drivers vary, and depending on the set of126supported features and other qualities, particular sensor drivers better serve127the purpose of an example. The following drivers are known to be good examples:128 129.. flat-table:: Example sensor drivers130 :header-rows: 0131 :widths: 1 1 1 2132 133 * - Driver name134 - File(s)135 - Driver type136 - Example topic137 * - CCS138 - ``drivers/media/i2c/ccs/``139 - Freely configurable140 - Power management (ACPI and DT), UAPI141 * - imx219142 - ``drivers/media/i2c/imx219.c``143 - Register list based144 - Power management (DT), UAPI, mode selection145 * - imx319146 - ``drivers/media/i2c/imx319.c``147 - Register list based148 - Power management (ACPI and DT)149