Documentation/video4linux/soc-camera.txt

   1                         Soc-Camera Subsystem
   2                         ====================
   3
   4 Terminology
   5 -----------
   6
   7 The following terms are used in this document:
   8  - camera / camera device / camera sensor - a video-camera sensor chip, capable
   9    of connecting to a variety of systems and interfaces, typically uses i2c for
  10    control and configuration, and a parallel or a serial bus for data.
  11  - camera host - an interface, to which a camera is connected. Typically a
  12    specialised interface, present on many SoCs, e.g., PXA27x and PXA3xx, SuperH,
  13    AVR32, i.MX27, i.MX31.
  14  - camera host bus - a connection between a camera host and a camera. Can be
  15    parallel or serial, consists of data and control lines, e.g., clock, vertical
  16    and horizontal synchronization signals.
  17
  18 Purpose of the soc-camera subsystem
  19 -----------------------------------
  20
  21 The soc-camera subsystem provides a unified API between camera host drivers and
  22 camera sensor drivers. It implements a V4L2 interface to the user, currently
  23 only the mmap method is supported.
  24
  25 This subsystem has been written to connect drivers for System-on-Chip (SoC)
  26 video capture interfaces with drivers for CMOS camera sensor chips to enable
  27 the reuse of sensor drivers with various hosts. The subsystem has been designed
  28 to support multiple camera host interfaces and multiple cameras per interface,
  29 although most applications have only one camera sensor.
  30
  31 Existing drivers
  32 ----------------
  33
  34 As of 2.6.27-rc4 there are two host drivers in the mainline: pxa_camera.c for
  35 PXA27x SoCs and sh_mobile_ceu_camera.c for SuperH SoCs, and four sensor drivers:
  36 mt9m001.c, mt9m111.c, mt9v022.c and a generic soc_camera_platform.c driver. This
  37 list is not supposed to be updated, look for more examples in your tree.
  38
  39 Camera host API
  40 ---------------
  41
  42 A host camera driver is registered using the
  43
  44 soc_camera_host_register(struct soc_camera_host *);
  45
  46 function. The host object can be initialized as follows:
  47
  48 static struct soc_camera_host pxa_soc_camera_host = {
  49         .drv_name       = PXA_CAM_DRV_NAME,
  50         .ops            = &pxa_soc_camera_host_ops,
  51 };
  52
  53 All camera host methods are passed in a struct soc_camera_host_ops:
  54
  55 static struct soc_camera_host_ops pxa_soc_camera_host_ops = {
  56         .owner          = THIS_MODULE,
  57         .add            = pxa_camera_add_device,
  58         .remove         = pxa_camera_remove_device,
  59         .suspend        = pxa_camera_suspend,
  60         .resume         = pxa_camera_resume,
  61         .set_fmt_cap    = pxa_camera_set_fmt_cap,
  62         .try_fmt_cap    = pxa_camera_try_fmt_cap,
  63         .init_videobuf  = pxa_camera_init_videobuf,
  64         .reqbufs        = pxa_camera_reqbufs,
  65         .poll           = pxa_camera_poll,
  66         .querycap       = pxa_camera_querycap,
  67         .try_bus_param  = pxa_camera_try_bus_param,
  68         .set_bus_param  = pxa_camera_set_bus_param,
  69 };
  70
  71 .add and .remove methods are called when a sensor is attached to or detached
  72 from the host, apart from performing host-internal tasks they shall also call
  73 sensor driver's .init and .release methods respectively. .suspend and .resume
  74 methods implement host's power-management functionality and its their
  75 responsibility to call respective sensor's methods. .try_bus_param and
  76 .set_bus_param are used to negotiate physical connection parameters between the
  77 host and the sensor. .init_videobuf is called by soc-camera core when a
  78 video-device is opened, further video-buffer management is implemented completely
  79 by the specific camera host driver. The rest of the methods are called from
  80 respective V4L2 operations.
  81
  82 Camera API
  83 ----------
  84
  85 Sensor drivers can use struct soc_camera_link, typically provided by the
  86 platform, and used to specify to which camera host bus the sensor is connected,
  87 and arbitrarily provide platform .power and .reset methods for the camera.
  88 soc_camera_device_register() and soc_camera_device_unregister() functions are
  89 used to add a sensor driver to or remove one from the system. The registration
  90 function takes a pointer to struct soc_camera_device as the only parameter.
  91 This struct can be initialized as follows:
  92
  93         /* link to driver operations */
  94         icd->ops        = &mt9m001_ops;
  95         /* link to the underlying physical (e.g., i2c) device */
  96         icd->control    = &client->dev;
  97         /* window geometry */
  98         icd->x_min      = 20;
  99         icd->y_min      = 12;
 100         icd->x_current  = 20;
 101         icd->y_current  = 12;
 102         icd->width_min  = 48;
 103         icd->width_max  = 1280;
 104         icd->height_min = 32;
 105         icd->height_max = 1024;
 106         icd->y_skip_top = 1;
 107         /* camera bus ID, typically obtained from platform data */
 108         icd->iface      = icl->bus_id;
 109
 110 struct soc_camera_ops provides .probe and .remove methods, which are called by
 111 the soc-camera core, when a camera is matched against or removed from a camera
 112 host bus, .init, .release, .suspend, and .resume are called from the camera host
 113 driver as discussed above. Other members of this struct provide respective V4L2
 114 functionality.
 115
 116 struct soc_camera_device also links to an array of struct soc_camera_data_format,
 117 listing pixel formats, supported by the camera.
 118
 119 VIDIOC_S_CROP and VIDIOC_S_FMT behaviour
 120 ----------------------------------------
 121
 122 Above user ioctls modify image geometry as follows:
 123
 124 VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor
 125 pixel. Changing sensor window sizes preserves any scaling factors, therefore
 126 user window sizes change as well.
 127
 128 VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as
 129 much as possible by modifying scaling factors. If the sensor window cannot be
 130 preserved precisely, it may be changed too.
 131
 132 In soc-camera there are two locations, where scaling and cropping can taks
 133 place: in the camera driver and in the host driver. User ioctls are first passed
 134 to the host driver, which then generally passes them down to the camera driver.
 135 It is more efficient to perform scaling and cropping in the camera driver to
 136 save camera bus bandwidth and maximise the framerate. However, if the camera
 137 driver failed to set the required parameters with sufficient precision, the host
 138 driver may decide to also use its own scaling and cropping to fulfill the user's
 139 request.
 140
 141 Camera drivers are interfaced to the soc-camera core and to host drivers over
 142 the v4l2-subdev API, which is completely functional, it doesn't pass any data.
 143 Therefore all camera drivers shall reply to .g_fmt() requests with their current
 144 output geometry. This is necessary to correctly configure the camera bus.
 145 .s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling
 146 factors have to be maintained by camera drivers internally. According to the
 147 V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we
 148 rely on camera drivers implementing .cropcap(). If the camera driver does not
 149 support cropping, it may choose to not implement .s_crop(), but to enable
 150 cropping support by the camera host driver at least the .g_crop method must be
 151 implemented.
 152
 153 User window geometry is kept in .user_width and .user_height fields in struct
 154 soc_camera_device and used by the soc-camera core and host drivers. The core
 155 updates these fields upon successful completion of a .s_fmt() call, but if these
 156 fields change elsewhere, e.g., during .s_crop() processing, the host driver is
 157 responsible for updating them.
 158
 159 --
 160 Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>