driver-api/media/camera-sensor.rst

1 .. SPDX-License-Identifier: GPL-2.0
8 This document covers the in-kernel APIs only. For the best practices on
12 CSI-2, parallel and BT.656 buses
13 --------------------------------
15 Please see :ref:`transmitter-receiver`.
18 ---------------
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
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
35 Read the ``clock-frequency`` _DSD property to denote the frequency. The driver
36 can rely on this frequency being used.
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
48 This approach has the drawback that there's no guarantee that the frequency
50 the board's clock tree to begin with. Changes to the Common Clock Framework API
54 ----------------
64 :ref:`async sub-device registration <media-registering-async-subdevs>`.
67 system resources required to power the sensor up and down. For drivers that
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
87 Drivers should in general not implement the system PM handlers.
96 Please also see :ref:`examples <media-camera-sensor-examples>`.
109 The function returns a non-zero value if it succeeded getting the power count or
114 ----------------------------------
117 information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to
120 .. _media-camera-sensor-examples:
123 ---------------
129 .. flat-table:: Example sensor drivers
130     :header-rows: 0
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)