Documentation/driver-api/media/camera-sensor.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 .. _media_writing_camera_sensor_drivers:
   4
   5 Writing camera sensor drivers
   6 =============================
   7
   8 This document covers the in-kernel APIs only. For the best practices on
   9 userspace API implementation in camera sensor drivers, please see
  10 :ref:`media_using_camera_sensor_drivers`.
  11
  12 CSI-2 and parallel (BT.601 and BT.656) busses
  13 ---------------------------------------------
  14
  15 Please see :ref:`transmitter-receiver`.
  16
  17 Handling clocks
  18 ---------------
  19
  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
  24 firmware. **No other frequencies should be used in any circumstances.**
  25
  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
  30 user.
  31
  32 ACPI
  33 ~~~~
  34
  35 Read the ``clock-frequency`` _DSD property to denote the frequency. The driver
  36 can rely on this frequency being used.
  37
  38 Devicetree
  39 ~~~~~~~~~~
  40
  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
  46 ``clk_get_rate()``.
  47
  48 This approach has the drawback that there's no guarantee that the frequency
  49 hasn't been modified directly or indirectly by another driver, or supported by
  50 the board's clock tree to begin with. Changes to the Common Clock Framework API
  51 are required to ensure reliability.
  52
  53 Power management
  54 ----------------
  55
  56 Camera sensors are used in conjunction with other devices to form a camera
  57 pipeline. They must obey the rules listed herein to ensure coherent power
  58 management over the pipeline.
  59
  60 Camera sensor drivers are responsible for controlling the power state of the
  61 device they otherwise control as well. They shall use runtime PM to manage
  62 power states. Runtime PM shall be enabled at probe time and disabled at remove
  63 time. Drivers should enable runtime PM autosuspend.
  64
  65 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
  66 system resources required to power the sensor up and down. For drivers that
  67 don't use any of those resources (such as drivers that support ACPI systems
  68 only), the runtime PM handlers may be left unimplemented.
  69
  70 In general, the device shall be powered on at least when its registers are
  71 being 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
  74 streaming. They may power the device up at probe time (for example to read
  75 identification registers), but should not keep it powered unconditionally after
  76 probe.
  77
  78 At system suspend time, the whole camera pipeline must stop streaming, and
  79 restart when the system is resumed. This requires coordination between the
  80 camera sensor and the rest of the camera pipeline. Bridge drivers are
  81 responsible for this coordination, and instruct camera sensors to stop and
  82 restart streaming by calling the appropriate subdev operations
  83 (``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera
  84 sensor drivers shall therefore **not** keep track of the streaming state to
  85 stop streaming in the PM suspend handler and restart it in the resume handler.
  86 Drivers should in general not implement the system PM handlers.
  87
  88 Camera sensor drivers shall **not** implement the subdev ``.s_power()``
  89 operation, as it is deprecated. While this operation is implemented in some
  90 existing drivers as they predate the deprecation, new drivers shall use runtime
  91 PM instead. If you feel you need to begin calling ``.s_power()`` from an ISP or
  92 a bridge driver, instead add runtime PM support to the sensor driver you are
  93 using and drop its ``.s_power()`` handler.
  94
  95 Please also see :ref:`examples <media-camera-sensor-examples>`.
  96
  97 Control framework
  98 ~~~~~~~~~~~~~~~~~
  99
 100 ``v4l2_ctrl_handler_setup()`` function may not be used in the device's runtime
 101 PM ``runtime_resume`` callback, as it has no way to figure out the power state
 102 of the device. This is because the power state of the device is only changed
 103 after the power state transition has taken place. The ``s_ctrl`` callback can be
 104 used 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
 108 The function returns a non-zero value if it succeeded getting the power count or
 109 runtime PM was disabled, in either of which cases the driver may proceed to
 110 access the device.
 111
 112 Rotation, orientation and flipping
 113 ----------------------------------
 114
 115 Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation
 116 information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to
 117 register the appropriate controls.
 118
 119 .. _media-camera-sensor-examples:
 120
 121 Example drivers
 122 ---------------
 123
 124 Features implemented by sensor drivers vary, and depending on the set of
 125 supported features and other qualities, particular sensor drivers better serve
 126 the 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)