Documentation/media/v4l-drivers/soc-camera.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 The Soc-Camera Drivers
   4 ======================
   5
   6 Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
   7
   8 Terminology
   9 -----------
  10
  11 The following terms are used in this document:
  12  - camera / camera device / camera sensor - a video-camera sensor chip, capable
  13    of connecting to a variety of systems and interfaces, typically uses i2c for
  14    control and configuration, and a parallel or a serial bus for data.
  15  - camera host - an interface, to which a camera is connected. Typically a
  16    specialised interface, present on many SoCs, e.g. PXA27x and PXA3xx, SuperH,
  17    i.MX27, i.MX31.
  18  - camera host bus - a connection between a camera host and a camera. Can be
  19    parallel or serial, consists of data and control lines, e.g. clock, vertical
  20    and horizontal synchronization signals.
  21
  22 Purpose of the soc-camera subsystem
  23 -----------------------------------
  24
  25 The soc-camera subsystem initially provided a unified API between camera host
  26 drivers and camera sensor drivers. Later the soc-camera sensor API has been
  27 replaced with the V4L2 standard subdev API. This also made camera driver re-use
  28 with non-soc-camera hosts possible. The camera host API to the soc-camera core
  29 has been preserved.
  30
  31 Soc-camera implements a V4L2 interface to the user, currently only the "mmap"
  32 method is supported by host drivers. However, the soc-camera core also provides
  33 support for the "read" method.
  34
  35 The subsystem has been designed to support multiple camera host interfaces and
  36 multiple cameras per interface, although most applications have only one camera
  37 sensor.
  38
  39 Existing drivers
  40 ----------------
  41
  42 As of 3.7 there are seven host drivers in the mainline: atmel-isi.c,
  43 mx1_camera.c (broken, scheduled for removal), mx2_camera.c, mx3_camera.c,
  44 omap1_camera.c, pxa_camera.c, sh_mobile_ceu_camera.c, and multiple sensor
  45 drivers under drivers/media/i2c/soc_camera/.
  46
  47 Camera host API
  48 ---------------
  49
  50 A host camera driver is registered using the
  51
  52 .. code-block:: none
  53
  54         soc_camera_host_register(struct soc_camera_host *);
  55
  56 function. The host object can be initialized as follows:
  57
  58 .. code-block:: none
  59
  60         struct soc_camera_host  *ici;
  61         ici->drv_name           = DRV_NAME;
  62         ici->ops                = &camera_host_ops;
  63         ici->priv               = pcdev;
  64         ici->v4l2_dev.dev       = &pdev->dev;
  65         ici->nr                 = pdev->id;
  66
  67 All camera host methods are passed in a struct soc_camera_host_ops:
  68
  69 .. code-block:: none
  70
  71         static struct soc_camera_host_ops camera_host_ops = {
  72                 .owner          = THIS_MODULE,
  73                 .add            = camera_add_device,
  74                 .remove         = camera_remove_device,
  75                 .set_fmt        = camera_set_fmt_cap,
  76                 .try_fmt        = camera_try_fmt_cap,
  77                 .init_videobuf2 = camera_init_videobuf2,
  78                 .poll           = camera_poll,
  79                 .querycap       = camera_querycap,
  80                 .set_bus_param  = camera_set_bus_param,
  81                 /* The rest of host operations are optional */
  82         };
  83
  84 .add and .remove methods are called when a sensor is attached to or detached
  85 from the host. .set_bus_param is used to configure physical connection
  86 parameters between the host and the sensor. .init_videobuf2 is called by
  87 soc-camera core when a video-device is opened, the host driver would typically
  88 call vb2_queue_init() in this method. Further video-buffer management is
  89 implemented completely by the specific camera host driver. If the host driver
  90 supports non-standard pixel format conversion, it should implement a
  91 .get_formats and, possibly, a .put_formats operations. See below for more
  92 details about format conversion. The rest of the methods are called from
  93 respective V4L2 operations.
  94
  95 Camera API
  96 ----------
  97
  98 Sensor drivers can use struct soc_camera_link, typically provided by the
  99 platform, and used to specify to which camera host bus the sensor is connected,
 100 and optionally provide platform .power and .reset methods for the camera. This
 101 struct is provided to the camera driver via the I2C client device platform data
 102 and can be obtained, using the soc_camera_i2c_to_link() macro. Care should be
 103 taken, when using soc_camera_vdev_to_subdev() and when accessing struct
 104 soc_camera_device, using v4l2_get_subdev_hostdata(): both only work, when
 105 running on an soc-camera host. The actual camera driver operation is implemented
 106 using the V4L2 subdev API. Additionally soc-camera camera drivers can use
 107 auxiliary soc-camera helper functions like soc_camera_power_on() and
 108 soc_camera_power_off(), which switch regulators, provided by the platform and call
 109 board-specific power switching methods. soc_camera_apply_board_flags() takes
 110 camera bus configuration capability flags and applies any board transformations,
 111 e.g. signal polarity inversion. soc_mbus_get_fmtdesc() can be used to obtain a
 112 pixel format descriptor, corresponding to a certain media-bus pixel format code.
 113 soc_camera_limit_side() can be used to restrict beginning and length of a frame
 114 side, based on camera capabilities.
 115
 116 VIDIOC_S_CROP and VIDIOC_S_FMT behaviour
 117 ----------------------------------------
 118
 119 Above user ioctls modify image geometry as follows:
 120
 121 VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor
 122 pixel. Changing sensor window sizes preserves any scaling factors, therefore
 123 user window sizes change as well.
 124
 125 VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as
 126 much as possible by modifying scaling factors. If the sensor window cannot be
 127 preserved precisely, it may be changed too.
 128
 129 In soc-camera there are two locations, where scaling and cropping can take
 130 place: in the camera driver and in the host driver. User ioctls are first passed
 131 to the host driver, which then generally passes them down to the camera driver.
 132 It is more efficient to perform scaling and cropping in the camera driver to
 133 save camera bus bandwidth and maximise the framerate. However, if the camera
 134 driver failed to set the required parameters with sufficient precision, the host
 135 driver may decide to also use its own scaling and cropping to fulfill the user's
 136 request.
 137
 138 Camera drivers are interfaced to the soc-camera core and to host drivers over
 139 the v4l2-subdev API, which is completely functional, it doesn't pass any data.
 140 Therefore all camera drivers shall reply to .g_fmt() requests with their current
 141 output geometry. This is necessary to correctly configure the camera bus.
 142 .s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling
 143 factors have to be maintained by camera drivers internally. According to the
 144 V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we
 145 rely on camera drivers implementing .cropcap(). If the camera driver does not
 146 support cropping, it may choose to not implement .s_crop(), but to enable
 147 cropping support by the camera host driver at least the .g_crop method must be
 148 implemented.
 149
 150 User window geometry is kept in .user_width and .user_height fields in struct
 151 soc_camera_device and used by the soc-camera core and host drivers. The core
 152 updates these fields upon successful completion of a .s_fmt() call, but if these
 153 fields change elsewhere, e.g. during .s_crop() processing, the host driver is
 154 responsible for updating them.
 155
 156 Format conversion
 157 -----------------
 158
 159 V4L2 distinguishes between pixel formats, as they are stored in memory, and as
 160 they are transferred over a media bus. Soc-camera provides support to
 161 conveniently manage these formats. A table of standard transformations is
 162 maintained by soc-camera core, which describes, what FOURCC pixel format will
 163 be obtained, if a media-bus pixel format is stored in memory according to
 164 certain rules. E.g. if MEDIA_BUS_FMT_YUYV8_2X8 data is sampled with 8 bits per
 165 sample and stored in memory in the little-endian order with no gaps between
 166 bytes, data in memory will represent the V4L2_PIX_FMT_YUYV FOURCC format. These
 167 standard transformations will be used by soc-camera or by camera host drivers to
 168 configure camera drivers to produce the FOURCC format, requested by the user,
 169 using the VIDIOC_S_FMT ioctl(). Apart from those standard format conversions,
 170 host drivers can also provide their own conversion rules by implementing a
 171 .get_formats and, if required, a .put_formats methods.