Documentation/admin-guide/media/fimc.rst

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