Documentation/media/v4l-drivers/fimc.rst

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