Documentation/video4linux/fimc.txt

   1 Samsung S5P/EXYNOS4 FIMC driver
   2
   3 Copyright (C) 2012 Samsung Electronics Co., Ltd.
   4 ---------------------------------------------------------------------------
   5
   6 The FIMC (Fully Interactive Mobile Camera) device available in Samsung
   7 SoC Application Processors is an integrated camera host interface, color
   8 space converter, image resizer and rotator.  It's also capable of capturing
   9 data from LCD controller (FIMD) through the SoC internal writeback data
  10 path.  There are multiple FIMC instances in the SoCs (up to 4), having
  11 slightly different capabilities, like pixel alignment constraints, rotator
  12 availability, LCD writeback support, etc. The driver is located at
  13 drivers/media/platform/s5p-fimc directory.
  14
  15 1. Supported SoCs
  16 =================
  17
  18 S5PC100 (mem-to-mem only), S5PV210, EXYNOS4210
  19
  20 2. Supported features
  21 =====================
  22
  23  - camera parallel interface capture (ITU-R.BT601/565);
  24  - camera serial interface capture (MIPI-CSI2);
  25  - memory-to-memory processing (color space conversion, scaling, mirror
  26    and rotation);
  27  - dynamic pipeline re-configuration at runtime (re-attachment of any FIMC
  28    instance to any parallel video input or any MIPI-CSI front-end);
  29  - runtime PM and system wide suspend/resume
  30
  31 Not currently supported:
  32  - LCD writeback input
  33  - per frame clock gating (mem-to-mem)
  34
  35 3. Files partitioning
  36 =====================
  37
  38 - media device driver
  39   drivers/media/platform/s5p-fimc/fimc-mdevice.[ch]
  40
  41  - camera capture video device driver
  42   drivers/media/platform/s5p-fimc/fimc-capture.c
  43
  44  - MIPI-CSI2 receiver subdev
  45   drivers/media/platform/s5p-fimc/mipi-csis.[ch]
  46
  47  - video post-processor (mem-to-mem)
  48   drivers/media/platform/s5p-fimc/fimc-core.c
  49
  50  - common files
  51   drivers/media/platform/s5p-fimc/fimc-core.h
  52   drivers/media/platform/s5p-fimc/fimc-reg.h
  53   drivers/media/platform/s5p-fimc/regs-fimc.h
  54
  55 4. User space interfaces
  56 ========================
  57
  58 4.1. Media device interface
  59
  60 The driver supports Media Controller API as defined at
  61 http://linuxtv.org/downloads/v4l-dvb-apis/media_common.html
  62 The media device driver name is "SAMSUNG S5P FIMC".
  63
  64 The purpose of this interface is to allow changing assignment of FIMC instances
  65 to the SoC peripheral camera input at runtime and optionally to control internal
  66 connections of the MIPI-CSIS device(s) to the FIMC entities.
  67
  68 The media device interface allows to configure the SoC for capturing image
  69 data from the sensor through more than one FIMC instance (e.g. for simultaneous
  70 viewfinder and still capture setup).
  71 Reconfiguration is done by enabling/disabling media links created by the driver
  72 during initialization. The internal device topology can be easily discovered
  73 through media entity and links enumeration.
  74
  75 4.2. Memory-to-memory video node
  76
  77 V4L2 memory-to-memory interface at /dev/video? device node.  This is standalone
  78 video device, it has no media pads. However please note the mem-to-mem and
  79 capture video node operation on same FIMC instance is not allowed.  The driver
  80 detects such cases but the applications should prevent them to avoid an
  81 undefined behaviour.
  82
  83 4.3. Capture video node
  84
  85 The driver supports V4L2 Video Capture Interface as defined at:
  86 http://linuxtv.org/downloads/v4l-dvb-apis/devices.html
  87
  88 At the capture and mem-to-mem video nodes only the multi-planar API is
  89 supported. For more details see:
  90 http://linuxtv.org/downloads/v4l-dvb-apis/planar-apis.html
  91
  92 4.4. Camera capture subdevs
  93
  94 Each FIMC instance exports a sub-device node (/dev/v4l-subdev?), a sub-device
  95 node is also created per each available and enabled at the platform level
  96 MIPI-CSI receiver device (currently up to two).
  97
  98 4.5. sysfs
  99
 100 In order to enable more precise camera pipeline control through the sub-device
 101 API the driver creates a sysfs entry associated with "s5p-fimc-md" platform
 102 device. The entry path is: /sys/platform/devices/s5p-fimc-md/subdev_conf_mode.
 103
 104 In typical use case there could be a following capture pipeline configuration:
 105 sensor subdev -> mipi-csi subdev -> fimc subdev -> video node
 106
 107 When we configure these devices through sub-device API at user space, the
 108 configuration flow must be from left to right, and the video node is
 109 configured as last one.
 110 When we don't use sub-device user space API the whole configuration of all
 111 devices belonging to the pipeline is done at the video node driver.
 112 The sysfs entry allows to instruct the capture node driver not to configure
 113 the sub-devices (format, crop), to avoid resetting the subdevs' configuration
 114 when the last configuration steps at the video node is performed.
 115
 116 For full sub-device control support (subdevs configured at user space before
 117 starting streaming):
 118 # echo "sub-dev" > /sys/platform/devices/s5p-fimc-md/subdev_conf_mode
 119
 120 For V4L2 video node control only (subdevs configured internally by the host
 121 driver):
 122 # echo "vid-dev" > /sys/platform/devices/s5p-fimc-md/subdev_conf_mode
 123 This is a default option.
 124
 125 5. Device mapping to video and subdev device nodes
 126 ==================================================
 127
 128 There are associated two video device nodes with each device instance in
 129 hardware - video capture and mem-to-mem and additionally a subdev node for
 130 more precise FIMC capture subsystem control. In addition a separate v4l2
 131 sub-device node is created per each MIPI-CSIS device.
 132
 133 How to find out which /dev/video? or /dev/v4l-subdev? is assigned to which
 134 device?
 135
 136 You can either grep through the kernel log to find relevant information, i.e.
 137 # dmesg | grep -i fimc
 138 (note that udev, if present, might still have rearranged the video nodes),
 139
 140 or retrieve the information from /dev/media? with help of the media-ctl tool:
 141 # media-ctl -p
 142
 143 6. Platform support
 144 ===================
 145
 146 The machine code (plat-s5p and arch/arm/mach-*) must select following options
 147
 148 CONFIG_S5P_DEV_FIMC0       mandatory
 149 CONFIG_S5P_DEV_FIMC1  \
 150 CONFIG_S5P_DEV_FIMC2  |    optional
 151 CONFIG_S5P_DEV_FIMC3  |
 152 CONFIG_S5P_SETUP_FIMC /
 153 CONFIG_S5P_SETUP_MIPIPHY \
 154 CONFIG_S5P_DEV_CSIS0     | optional for MIPI-CSI interface
 155 CONFIG_S5P_DEV_CSIS1     /
 156
 157 Except that, relevant s5p_device_fimc? should be registered in the machine code
 158 in addition to a "s5p-fimc-md" platform device to which the media device driver
 159 is bound.  The "s5p-fimc-md" device instance is required even if only mem-to-mem
 160 operation is used.
 161
 162 The description of sensor(s) attached to FIMC/MIPI-CSIS camera inputs should be
 163 passed as the "s5p-fimc-md" device platform_data.  The platform data structure
 164 is defined in file include/media/s5p_fimc.h.
 165
 166 7. Build
 167 ========
 168
 169 This driver depends on following config options:
 170 PLAT_S5P,
 171 PM_RUNTIME,
 172 I2C,
 173 REGULATOR,
 174 VIDEO_V4L2_SUBDEV_API,
 175
 176 If the driver is built as a loadable kernel module (CONFIG_VIDEO_SAMSUNG_S5P_FIMC=m)
 177 two modules are created (in addition to the core v4l2 modules): s5p-fimc.ko and
 178 optional s5p-csis.ko (MIPI-CSI receiver subdev).