1Samsung S5P/EXYNOS4 FIMC driver
  2
  3Copyright (C) 2012 - 2013 Samsung Electronics Co., Ltd.
  4---------------------------------------------------------------------------
  5
  6The FIMC (Fully Interactive Mobile Camera) device available in Samsung
  7SoC Application Processors is an integrated camera host interface, color
  8space converter, image resizer and rotator.  It's also capable of capturing
  9data from LCD controller (FIMD) through the SoC internal writeback data
 10path.  There are multiple FIMC instances in the SoCs (up to 4), having
 11slightly different capabilities, like pixel alignment constraints, rotator
 12availability, LCD writeback support, etc. The driver is located at
 13drivers/media/platform/exynos4-is directory.
 14
 151. Supported SoCs
 16=================
 17
 18S5PC100 (mem-to-mem only), S5PV210, EXYNOS4210
 19
 202. 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
 31Not currently supported:
 32 - LCD writeback input
 33 - per frame clock gating (mem-to-mem)
 34
 353. Files partitioning
 36=====================
 37
 38- media device driver
 39  drivers/media/platform/exynos4-is/media-dev.[ch]
 40
 41 - camera capture video device driver
 42  drivers/media/platform/exynos4-is/fimc-capture.c
 43
 44 - MIPI-CSI2 receiver subdev
 45  drivers/media/platform/exynos4-is/mipi-csis.[ch]
 46
 47 - video post-processor (mem-to-mem)
 48  drivers/media/platform/exynos4-is/fimc-core.c
 49
 50 - common files
 51  drivers/media/platform/exynos4-is/fimc-core.h
 52  drivers/media/platform/exynos4-is/fimc-reg.h
 53  drivers/media/platform/exynos4-is/regs-fimc.h
 54
 554. User space interfaces
 56========================
 57
 584.1. Media device interface
 59
 60The driver supports Media Controller API as defined at
 61https://linuxtv.org/downloads/v4l-dvb-apis/media_common.html
 62The media device driver name is "SAMSUNG S5P FIMC".
 63
 64The purpose of this interface is to allow changing assignment of FIMC instances
 65to the SoC peripheral camera input at runtime and optionally to control internal
 66connections of the MIPI-CSIS device(s) to the FIMC entities.
 67
 68The media device interface allows to configure the SoC for capturing image
 69data from the sensor through more than one FIMC instance (e.g. for simultaneous
 70viewfinder and still capture setup).
 71Reconfiguration is done by enabling/disabling media links created by the driver
 72during initialization. The internal device topology can be easily discovered
 73through media entity and links enumeration.
 74
 754.2. Memory-to-memory video node
 76
 77V4L2 memory-to-memory interface at /dev/video? device node.  This is standalone
 78video device, it has no media pads. However please note the mem-to-mem and
 79capture video node operation on same FIMC instance is not allowed.  The driver
 80detects such cases but the applications should prevent them to avoid an
 81undefined behaviour.
 82
 834.3. Capture video node
 84
 85The driver supports V4L2 Video Capture Interface as defined at:
 86https://linuxtv.org/downloads/v4l-dvb-apis/devices.html
 87
 88At the capture and mem-to-mem video nodes only the multi-planar API is
 89supported. For more details see:
 90https://linuxtv.org/downloads/v4l-dvb-apis/planar-apis.html
 91
 924.4. Camera capture subdevs
 93
 94Each FIMC instance exports a sub-device node (/dev/v4l-subdev?), a sub-device
 95node is also created per each available and enabled at the platform level
 96MIPI-CSI receiver device (currently up to two).
 97
 984.5. sysfs
 99
100In order to enable more precise camera pipeline control through the sub-device
101API the driver creates a sysfs entry associated with "s5p-fimc-md" platform
102device. The entry path is: /sys/platform/devices/s5p-fimc-md/subdev_conf_mode.
103
104In typical use case there could be a following capture pipeline configuration:
105sensor subdev -> mipi-csi subdev -> fimc subdev -> video node
106
107When we configure these devices through sub-device API at user space, the
108configuration flow must be from left to right, and the video node is
109configured as last one.
110When we don't use sub-device user space API the whole configuration of all
111devices belonging to the pipeline is done at the video node driver.
112The sysfs entry allows to instruct the capture node driver not to configure
113the sub-devices (format, crop), to avoid resetting the subdevs' configuration
114when the last configuration steps at the video node is performed.
115
116For full sub-device control support (subdevs configured at user space before
117starting streaming):
118# echo "sub-dev" > /sys/platform/devices/s5p-fimc-md/subdev_conf_mode
119
120For V4L2 video node control only (subdevs configured internally by the host
121driver):
122# echo "vid-dev" > /sys/platform/devices/s5p-fimc-md/subdev_conf_mode
123This is a default option.
124
1255. Device mapping to video and subdev device nodes
126==================================================
127
128There are associated two video device nodes with each device instance in
129hardware - video capture and mem-to-mem and additionally a subdev node for
130more precise FIMC capture subsystem control. In addition a separate v4l2
131sub-device node is created per each MIPI-CSIS device.
132
133How to find out which /dev/video? or /dev/v4l-subdev? is assigned to which
134device?
135
136You 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
140or retrieve the information from /dev/media? with help of the media-ctl tool:
141# media-ctl -p
142
1437. Build
144========
145
146If the driver is built as a loadable kernel module (CONFIG_VIDEO_SAMSUNG_S5P_FIMC=m)
147two modules are created (in addition to the core v4l2 modules): s5p-fimc.ko and
148optional s5p-csis.ko (MIPI-CSI receiver subdev).