Documentation/media/v4l-drivers/ipu3.rst

   1 .. include:: <isonum.txt>
   2
   3 ===============================================================
   4 Intel Image Processing Unit 3 (IPU3) Imaging Unit (ImgU) driver
   5 ===============================================================
   6
   7 Copyright |copy| 2018 Intel Corporation
   8
   9 Introduction
  10 ============
  11
  12 This file documents the Intel IPU3 (3rd generation Image Processing Unit)
  13 Imaging Unit drivers located under drivers/media/pci/intel/ipu3 (CIO2) as well
  14 as under drivers/staging/media/ipu3 (ImgU).
  15
  16 The Intel IPU3 found in certain Kaby Lake (as well as certain Sky Lake)
  17 platforms (U/Y processor lines) is made up of two parts namely the Imaging Unit
  18 (ImgU) and the CIO2 device (MIPI CSI2 receiver).
  19
  20 The CIO2 device receives the raw Bayer data from the sensors and outputs the
  21 frames in a format that is specific to the IPU3 (for consumption by the IPU3
  22 ImgU). The CIO2 driver is available as drivers/media/pci/intel/ipu3/ipu3-cio2*
  23 and is enabled through the CONFIG_VIDEO_IPU3_CIO2 config option.
  24
  25 The Imaging Unit (ImgU) is responsible for processing images captured
  26 by the IPU3 CIO2 device. The ImgU driver sources can be found under
  27 drivers/staging/media/ipu3 directory. The driver is enabled through the
  28 CONFIG_VIDEO_IPU3_IMGU config option.
  29
  30 The two driver modules are named ipu3_csi2 and ipu3_imgu, respectively.
  31
  32 The drivers has been tested on Kaby Lake platforms (U/Y processor lines).
  33
  34 Both of the drivers implement V4L2, Media Controller and V4L2 sub-device
  35 interfaces. The IPU3 CIO2 driver supports camera sensors connected to the CIO2
  36 MIPI CSI-2 interfaces through V4L2 sub-device sensor drivers.
  37
  38 CIO2
  39 ====
  40
  41 The CIO2 is represented as a single V4L2 subdev, which provides a V4L2 subdev
  42 interface to the user space. There is a video node for each CSI-2 receiver,
  43 with a single media controller interface for the entire device.
  44
  45 The CIO2 contains four independent capture channel, each with its own MIPI CSI-2
  46 receiver and DMA engine. Each channel is modelled as a V4L2 sub-device exposed
  47 to userspace as a V4L2 sub-device node and has two pads:
  48
  49 .. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|
  50
  51 .. flat-table::
  52
  53     * - pad
  54       - direction
  55       - purpose
  56
  57     * - 0
  58       - sink
  59       - MIPI CSI-2 input, connected to the sensor subdev
  60
  61     * - 1
  62       - source
  63       - Raw video capture, connected to the V4L2 video interface
  64
  65 The V4L2 video interfaces model the DMA engines. They are exposed to userspace
  66 as V4L2 video device nodes.
  67
  68 Capturing frames in raw Bayer format
  69 ------------------------------------
  70
  71 CIO2 MIPI CSI2 receiver is used to capture frames (in packed raw Bayer format)
  72 from the raw sensors connected to the CSI2 ports. The captured frames are used
  73 as input to the ImgU driver.
  74
  75 Image processing using IPU3 ImgU requires tools such as raw2pnm [#f1]_, and
  76 yavta [#f2]_ due to the following unique requirements and / or features specific
  77 to IPU3.
  78
  79 -- The IPU3 CSI2 receiver outputs the captured frames from the sensor in packed
  80 raw Bayer format that is specific to IPU3.
  81
  82 -- Multiple video nodes have to be operated simultaneously.
  83
  84 Let us take the example of ov5670 sensor connected to CSI2 port 0, for a
  85 2592x1944 image capture.
  86
  87 Using the media contorller APIs, the ov5670 sensor is configured to send
  88 frames in packed raw Bayer format to IPU3 CSI2 receiver.
  89
  90 # This example assumes /dev/media0 as the CIO2 media device
  91
  92 export MDEV=/dev/media0
  93
  94 # and that ov5670 sensor is connected to i2c bus 10 with address 0x36
  95
  96 export SDEV=$(media-ctl -d $MDEV -e "ov5670 10-0036")
  97
  98 # Establish the link for the media devices using media-ctl [#f3]_
  99 media-ctl -d $MDEV -l "ov5670:0 -> ipu3-csi2 0:0[1]"
 100
 101 # Set the format for the media devices
 102 media-ctl -d $MDEV -V "ov5670:0 [fmt:SGRBG10/2592x1944]"
 103
 104 media-ctl -d $MDEV -V "ipu3-csi2 0:0 [fmt:SGRBG10/2592x1944]"
 105
 106 media-ctl -d $MDEV -V "ipu3-csi2 0:1 [fmt:SGRBG10/2592x1944]"
 107
 108 Once the media pipeline is configured, desired sensor specific settings
 109 (such as exposure and gain settings) can be set, using the yavta tool.
 110
 111 e.g
 112
 113 yavta -w 0x009e0903 444 $SDEV
 114
 115 yavta -w 0x009e0913 1024 $SDEV
 116
 117 yavta -w 0x009e0911 2046 $SDEV
 118
 119 Once the desired sensor settings are set, frame captures can be done as below.
 120
 121 e.g
 122
 123 yavta --data-prefix -u -c10 -n5 -I -s2592x1944 --file=/tmp/frame-#.bin \
 124       -f IPU3_SGRBG10 $(media-ctl -d $MDEV -e "ipu3-cio2 0")
 125
 126 With the above command, 10 frames are captured at 2592x1944 resolution, with
 127 sGRBG10 format and output as IPU3_SGRBG10 format.
 128
 129 The captured frames are available as /tmp/frame-#.bin files.
 130
 131 ImgU
 132 ====
 133
 134 The ImgU is represented as two V4L2 subdevs, each of which provides a V4L2
 135 subdev interface to the user space.
 136
 137 Each V4L2 subdev represents a pipe, which can support a maximum of 2 streams.
 138 This helps to support advanced camera features like Continuous View Finder (CVF)
 139 and Snapshot During Video(SDV).
 140
 141 The ImgU contains two independent pipes, each modelled as a V4L2 sub-device
 142 exposed to userspace as a V4L2 sub-device node.
 143
 144 Each pipe has two sink pads and three source pads for the following purpose:
 145
 146 .. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|
 147
 148 .. flat-table::
 149
 150     * - pad
 151       - direction
 152       - purpose
 153
 154     * - 0
 155       - sink
 156       - Input raw video stream
 157
 158     * - 1
 159       - sink
 160       - Processing parameters
 161
 162     * - 2
 163       - source
 164       - Output processed video stream
 165
 166     * - 3
 167       - source
 168       - Output viewfinder video stream
 169
 170     * - 4
 171       - source
 172       - 3A statistics
 173
 174 Each pad is connected to a corresponding V4L2 video interface, exposed to
 175 userspace as a V4L2 video device node.
 176
 177 Device operation
 178 ----------------
 179
 180 With ImgU, once the input video node ("ipu3-imgu 0/1":0, in
 181 <entity>:<pad-number> format) is queued with buffer (in packed raw Bayer
 182 format), ImgU starts processing the buffer and produces the video output in YUV
 183 format and statistics output on respective output nodes. The driver is expected
 184 to have buffers ready for all of parameter, output and statistics nodes, when
 185 input video node is queued with buffer.
 186
 187 At a minimum, all of input, main output, 3A statistics and viewfinder
 188 video nodes should be enabled for IPU3 to start image processing.
 189
 190 Each ImgU V4L2 subdev has the following set of video nodes.
 191
 192 input, output and viewfinder video nodes
 193 ----------------------------------------
 194
 195 The frames (in packed raw Bayer format specific to the IPU3) received by the
 196 input video node is processed by the IPU3 Imaging Unit and are output to 2 video
 197 nodes, with each targeting a different purpose (main output and viewfinder
 198 output).
 199
 200 Details onand the Bayer format specific to the IPU3 can be found in
 201 :ref:`v4l2-pix-fmt-ipu3-sbggr10`.
 202
 203 The driver supports V4L2 Video Capture Interface as defined at :ref:`devices`.
 204
 205 Only the multi-planar API is supported. More details can be found at
 206 :ref:`planar-apis`.
 207
 208 Parameters video node
 209 ---------------------
 210
 211 The parameters video node receives the ImgU algorithm parameters that are used
 212 to configure how the ImgU algorithms process the image.
 213
 214 Details on processing parameters specific to the IPU3 can be found in
 215 :ref:`v4l2-meta-fmt-params`.
 216
 217 3A statistics video node
 218 ------------------------
 219
 220 3A statistics video node is used by the ImgU driver to output the 3A (auto
 221 focus, auto exposure and auto white balance) statistics for the frames that are
 222 being processed by the ImgU to user space applications. User space applications
 223 can use this statistics data to compute the desired algorithm parameters for
 224 the ImgU.
 225
 226 Configuring the Intel IPU3
 227 ==========================
 228
 229 The IPU3 ImgU pipelines can be configured using the Media Controller, defined at
 230 :ref:`media_controller`.
 231
 232 Firmware binary selection
 233 -------------------------
 234
 235 The firmware binary is selected using the V4L2_CID_INTEL_IPU3_MODE, currently
 236 defined in drivers/staging/media/ipu3/include/intel-ipu3.h . "VIDEO" and "STILL"
 237 modes are available.
 238
 239 Processing the image in raw Bayer format
 240 ----------------------------------------
 241
 242 Configuring ImgU V4L2 subdev for image processing
 243 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 244
 245 The ImgU V4L2 subdevs have to be configured with media controller APIs to have
 246 all the video nodes setup correctly.
 247
 248 Let us take "ipu3-imgu 0" subdev as an example.
 249
 250 media-ctl -d $MDEV -r
 251
 252 media-ctl -d $MDEV -l "ipu3-imgu 0 input":0 -> "ipu3-imgu 0":0[1]
 253
 254 media-ctl -d $MDEV -l "ipu3-imgu 0":2 -> "ipu3-imgu 0 output":0[1]
 255
 256 media-ctl -d $MDEV -l "ipu3-imgu 0":3 -> "ipu3-imgu 0 viewfinder":0[1]
 257
 258 media-ctl -d $MDEV -l "ipu3-imgu 0":4 -> "ipu3-imgu 0 3a stat":0[1]
 259
 260 Also the pipe mode of the corresponding V4L2 subdev should be set as desired
 261 (e.g 0 for video mode or 1 for still mode) through the control id 0x009819a1 as
 262 below.
 263
 264 yavta -w "0x009819A1 1" /dev/v4l-subdev7
 265
 266 RAW Bayer frames go through the following ImgU pipeline HW blocks to have the
 267 processed image output to the DDR memory.
 268
 269 RAW Bayer frame -> Input Feeder -> Bayer Down Scaling (BDS) -> Geometric
 270 Distortion Correction (GDC) -> DDR
 271
 272 The ImgU V4L2 subdev has to be configured with the supported resolutions in all
 273 the above HW blocks, for a given input resolution.
 274
 275 For a given supported resolution for an input frame, the Input Feeder, Bayer
 276 Down Scaling and GDC blocks should be configured with the supported resolutions.
 277 This information can be obtained by looking at the following IPU3 ImgU
 278 configuration table.
 279
 280 https://chromium.googlesource.com/chromiumos/overlays/board-overlays/+/master
 281
 282 Under baseboard-poppy/media-libs/cros-camera-hal-configs-poppy/files/gcss
 283 directory, graph_settings_ov5670.xml can be used as an example.
 284
 285 The following steps prepare the ImgU pipeline for the image processing.
 286
 287 1. The ImgU V4L2 subdev data format should be set by using the
 288 VIDIOC_SUBDEV_S_FMT on pad 0, using the GDC width and height obtained above.
 289
 290 2. The ImgU V4L2 subdev cropping should be set by using the
 291 VIDIOC_SUBDEV_S_SELECTION on pad 0, with V4L2_SEL_TGT_CROP as the target,
 292 using the input feeder height and width.
 293
 294 3. The ImgU V4L2 subdev composing should be set by using the
 295 VIDIOC_SUBDEV_S_SELECTION on pad 0, with V4L2_SEL_TGT_COMPOSE as the target,
 296 using the BDS height and width.
 297
 298 For the ov5670 example, for an input frame with a resolution of 2592x1944
 299 (which is input to the ImgU subdev pad 0), the corresponding resolutions
 300 for input feeder, BDS and GDC are 2592x1944, 2592x1944 and 2560x1920
 301 respectively.
 302
 303 Once this is done, the received raw Bayer frames can be input to the ImgU
 304 V4L2 subdev as below, using the open source application v4l2n [#f1]_.
 305
 306 For an image captured with 2592x1944 [#f4]_ resolution, with desired output
 307 resolution as 2560x1920 and viewfinder resolution as 2560x1920, the following
 308 v4l2n command can be used. This helps process the raw Bayer frames and produces
 309 the desired results for the main output image and the viewfinder output, in NV12
 310 format.
 311
 312 v4l2n --pipe=4 --load=/tmp/frame-#.bin --open=/dev/video4
 313 --fmt=type:VIDEO_OUTPUT_MPLANE,width=2592,height=1944,pixelformat=0X47337069
 314 --reqbufs=type:VIDEO_OUTPUT_MPLANE,count:1 --pipe=1 --output=/tmp/frames.out
 315 --open=/dev/video5
 316 --fmt=type:VIDEO_CAPTURE_MPLANE,width=2560,height=1920,pixelformat=NV12
 317 --reqbufs=type:VIDEO_CAPTURE_MPLANE,count:1 --pipe=2 --output=/tmp/frames.vf
 318 --open=/dev/video6
 319 --fmt=type:VIDEO_CAPTURE_MPLANE,width=2560,height=1920,pixelformat=NV12
 320 --reqbufs=type:VIDEO_CAPTURE_MPLANE,count:1 --pipe=3 --open=/dev/video7
 321 --output=/tmp/frames.3A --fmt=type:META_CAPTURE,?
 322 --reqbufs=count:1,type:META_CAPTURE --pipe=1,2,3,4 --stream=5
 323
 324 where /dev/video4, /dev/video5, /dev/video6 and /dev/video7 devices point to
 325 input, output, viewfinder and 3A statistics video nodes respectively.
 326
 327 Converting the raw Bayer image into YUV domain
 328 ----------------------------------------------
 329
 330 The processed images after the above step, can be converted to YUV domain
 331 as below.
 332
 333 Main output frames
 334 ~~~~~~~~~~~~~~~~~~
 335
 336 raw2pnm -x2560 -y1920 -fNV12 /tmp/frames.out /tmp/frames.out.ppm
 337
 338 where 2560x1920 is output resolution, NV12 is the video format, followed
 339 by input frame and output PNM file.
 340
 341 Viewfinder output frames
 342 ~~~~~~~~~~~~~~~~~~~~~~~~
 343
 344 raw2pnm -x2560 -y1920 -fNV12 /tmp/frames.vf /tmp/frames.vf.ppm
 345
 346 where 2560x1920 is output resolution, NV12 is the video format, followed
 347 by input frame and output PNM file.
 348
 349 Example user space code for IPU3
 350 ================================
 351
 352 User space code that configures and uses IPU3 is available here.
 353
 354 https://chromium.googlesource.com/chromiumos/platform/arc-camera/+/master/
 355
 356 The source can be located under hal/intel directory.
 357
 358 References
 359 ==========
 360
 361 .. [#f5] include/uapi/linux/intel-ipu3.h
 362
 363 .. [#f1] https://github.com/intel/nvt
 364
 365 .. [#f2] http://git.ideasonboard.org/yavta.git
 366
 367 .. [#f3] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
 368
 369 .. [#f4] ImgU limitation requires an additional 16x16 for all input resolutions