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