Media Controller

Modern System-on-Chip (SoC) devices support a wide range of functionality in the way of internal hardware blocks which has resulted in a variety of ways to interconnect functions within the SoC that alter the V4L device content.

The Media Controller kernel API has been designed to expose detailed information about media devices and capture devices to userspace in a way that allows them to be interconnected in dynamic and complex ways at runtime.

Media controller devices expose entities to the media controller framework. Each entity has one or more source pads and one or more sink pads. You use the media controller kernel API (ie via media-ctl) to query entities, link source pads to sink pads, and set formats of pads.

Note that the IMX6 media controller driver was added to Linux in the 4.13 kernel. This page applies to Linux 4.13 and beyond. If you are using a kernel earlier than that for the Ventana IMX6 based boards (such as the Gateworks 3.14 kernel) you will need to use the Yocto GStreamer pages:

• Yocto/gstreamer
• Yocto/gstreamer/compositing
• Yocto/gstreamer/latency
• Yocto/gstreamer/multimedia
• Yocto/gstreamer/streaming
• Yocto/gstreamer/video

media-ctl (v4l-utils package)

The media-ctl application from the v4l-utils package is a userspace application that uses the Linux Media Controller API to configure pipelines.

media-ctl has no manpage but looking at source:

• --device <dev> (/dev/media0 default)
• --entity <name> print the device name associated with given entity
• --set-v4l2 <v4l2> comma sep list of formats to setup
• --get-v4l2 <pad> print active format on a given pad
• --set-dv <pad> configure DV timings on a given pad
• --interactive modify links interactively
• --links <linux> comma sep list of link descriptors to setup
• --known-mbus-fmts list known formats and their numeric values
• --print-topology print device topology
• --reset reset all links to inactive

The best way to visualize what hardware components are avaialble to interconnect is to use print the topology and convert it to a graphic image:

media-ctl --print-topology
media-ctl --print-dot > graph.dot
dot -Tpng graph.dot > graph.png

• dashed lines show possible connections; use these to determine the possibilities
• solid lines show active connections
• green boxes show media entities
• yellow boxes show video4linux endpoints

For example the following is the graph for a GW5404:

You can find graphs for the Video capture devices present on Various gateworks boards at ​http://dev.gateworks.com/docs/linux/media/:

• ​GW5510
• ​GW5514
• ​GW540x

Use media-ctl --links to link an entity source pad to an entity sink pad:

media-ctl --links "<entitya>:<srcpadn> -> <entityb>:<sinkpadn>[<flags>]

• flags: 0=inactive 1=active

The basic configuration steps for a hardware media pipeline are:

• reset all links with media-ctl --reset
• configure links with media-ctl --links
• configure pad formats with media-ctl --set-v4l2
• configure subdev properties with v4l2-ctl
• capture frames on the /dev/video* device

IMX6 Media Capture

The ​IMX media controller documentation in the Linux kernel is likely the best documentation to explain what's in the SoC and what each component can do:

The Freescale i.MX5/6 contains an Image Processing Unit (IPU), which handles the flow of image frames to and from capture devices and display devices.

For image capture, the IPU contains the following internal subunits:

• Image DMA Controller (IDMAC)
• Camera Serial Interface (CSI)
• Image Converter (IC)
• Sensor Multi-FIFO Controller (SMFC)
• Image Rotator (IRT)
• Video De-Interlacing or Combining Block (VDIC)

The IDMAC is the DMA controller for transfer of image frames to and from memory. Various dedicated DMA channels exist for both video capture and display paths. During transfer, the IDMAC is also capable of vertical image flip, 8x8 block transfer (see IRT description), pixel component re-ordering (for example UYVY to YUYV) within the same colorspace, and packed <--> planar conversion. The IDMAC can also perform a simple de-interlacing by interweaving even and odd lines during transfer (without motion compensation which requires the VDIC).

The CSI is the backend capture unit that interfaces directly with camera sensors over Parallel, BT.656/1120, and MIPI CSI-2 busses.

The IC handles color-space conversion, resizing (downscaling and upscaling), horizontal flip, and 90/270 degree rotation operations.

There are three independent "tasks" within the IC that can carry out conversions concurrently: pre-process encoding, pre-process viewfinder, and post-processing. Within each task, conversions are split into three sections: downsizing section, main section (upsizing, flip, colorspace conversion, and graphics plane combining), and rotation section.

The IPU time-shares the IC task operations. The time-slice granularity is one burst of eight pixels in the downsizing section, one image line in the main processing section, one image frame in the rotation section.

The SMFC is composed of four independent FIFOs that each can transfer captured frames from sensors directly to memory concurrently via four IDMAC channels.

The IRT carries out 90 and 270 degree image rotation operations. The rotation operation is carried out on 8x8 pixel blocks at a time. This operation is supported by the IDMAC which handles the 8x8 block transfer along with block reordering, in coordination with vertical flip.

The VDIC handles the conversion of interlaced video to progressive, with support for different motion compensation modes (low, medium, and high motion). The deinterlaced output frames from the VDIC can be sent to the IC pre-process viewfinder task for further conversions. The VDIC also contains a Combiner that combines two image planes, with alpha blending and color keying.

In addition to the IPU internal subunits, there are also two units outside the IPU that are also involved in video capture on i.MX:

• MIPI CSI-2 Receiver for camera sensors with the MIPI CSI-2 bus interface. This is a Synopsys DesignWare core.
• Two video multiplexers for selecting among multiple sensor inputs to send to a CSI.

These entities will differ depending on the processor: IMX6D/Q have two IPU's and IMX6S/DL has only one IPU therefore the number of entities and pads differ. Additionally certain entities will have fixed configuration based on device-tree endpoints. The adv7180 analog media controller driver also presents an entity as does the tda1997x HDMI receiver media controller driver.

References:

• ​Linux IMX Media Driver Documentation

Kernel Drivers

The following kernel drivers need to be enabled for IMX6 capture:

• CONFIG_MEDIA_CONTROLLER - for media controller drivers and framework
• CONFIG_VIDEO_V4L2_SUBDEV_API - for V4L2 subdev framework
• CONFIG_VIDEO_IMX_MEDIA - for IMX6 media controller
• CONFIG_VIDEO_MUX -
• CONFIG_VIDEO_ADV7180 - for Ventana Analog Video Capture

The kernel will display messages such as:

root@ventana:~# dmesg | grep media
[    0.343835] media: Linux media interface: v0.10
[    6.189587] imx-media: Registered subdev ipu2_csi1_mux
[    6.195114] imx-media: Registered subdev ipu1_csi0_mux
[    6.200928] imx-media: Registered subdev ipu1_vdic
[    6.206251] imx-media: Registered subdev ipu2_vdic
[    6.211493] imx-media: Registered subdev ipu1_ic_prp
[    6.216580] imx-media: Registered subdev ipu1_ic_prpenc
[    6.230109] imx-media: Registered subdev ipu1_ic_prpvf
[    6.242937] imx-media: Registered subdev ipu2_ic_prp
[    6.248023] imx-media: Registered subdev ipu2_ic_prpenc
[    6.261065] imx-media: Registered subdev ipu2_ic_prpvf
[    6.273972] imx-media: Registered subdev ipu1_csi0
[    6.292605] imx-media: Registered subdev ipu1_csi1
[    6.304263] imx-media: Registered subdev ipu2_csi0
[    6.315870] imx-media: Registered subdev ipu2_csi1
[    6.327352] imx-media: imx_media_create_link: ipu1_csi0:1 -> ipu1_ic_prp:0
[    6.334307] imx-media: imx_media_create_link: ipu1_csi0:1 -> ipu1_vdic:0
[    6.341128] imx-media: imx_media_create_link: ipu1_csi0_mux:2 -> ipu1_csi0:0
[    6.348200] imx-media: imx_media_create_link: ipu1_csi1:1 -> ipu1_ic_prp:0
[    6.355253] imx-media: imx_media_create_link: ipu1_csi1:1 -> ipu1_vdic:0
[    6.362026] imx-media: imx_media_create_link: ipu2_csi0:1 -> ipu2_ic_prp:0
[    6.368924] imx-media: imx_media_create_link: ipu2_csi0:1 -> ipu2_vdic:0
[    6.375717] imx-media: imx_media_create_link: ipu2_csi1:1 -> ipu2_ic_prp:0
[    6.382661] imx-media: imx_media_create_link: ipu2_csi1:1 -> ipu2_vdic:0
[    6.389419] imx-media: imx_media_create_link: ipu2_csi1_mux:2 -> ipu2_csi1:0
[    6.396529] imx-media: imx_media_create_link: ipu1_vdic:2 -> ipu1_ic_prp:0
[    6.403487] imx-media: imx_media_create_link: ipu1_ic_prp:1 -> ipu1_ic_prpenc:0
[    6.410858] imx-media: imx_media_create_link: ipu1_ic_prp:2 -> ipu1_ic_prpvf:0
[    6.418104] imx-media: imx_media_create_link: ipu2_vdic:2 -> ipu2_ic_prp:0
[    6.425095] imx-media: imx_media_create_link: ipu2_ic_prp:1 -> ipu2_ic_prpenc:0
[    6.432764] imx-media: imx_media_create_link: ipu2_ic_prp:2 -> ipu2_ic_prpvf:0

• /dev/media devices are acted on by media controller framework - even though imx-media driver registers subdevs the /dev/media device doesn't show up until the endpoint (adv7180, tda1997x) driver loads because that's the endpoint in devicetree (both endpoints have to exist before it shows up as available)

Media Controller Pipelines

Various pipelines of media controller entities are created by linking them together in a fashion that starts with a Linux v4l2 capture chip and ends with a Linux v4l2 capture node (ie /dev/video4).

The media pipelines you create will depend on:

• board model and CPU
• features and performance you are after

The Ventana baseboards have the following video capture capabilities:

• GW54xx:
  • CVBS (Analog) video capture (ADV7180)
  • HDMI (Digital) video capture (TDA1997X)
• GW551x:
  • HDMI (Digital) video capture (TDA1997X)
• GW51xx/GW52xx/GW53xx/GW553x:
  • CVBS (Analog) video capture (ADV7180)

The IPU and CSI port for each capture device depends not only on the board model but the IMX6 SoC variant as well.

The following table shows the IPU/CSI combination for each capture device per board and SoC:

Board	SoC	ADV7180 Analog CVBS	TDA1997x Digital HDMI
GW540x	IMX6Q	IPU2_CSI1	IPU1_CSI0
GW540x	IMX6DL	IPU1_CSI1	not supported
GW530x	IMX6Q	IPU2_CSI1	N/A
GW530x	IMX6DL	IPU1_CSI1	N/A
GW520x	IMX6Q	IPU2_CSI1	N/A
GW520x	IMX6DL	IPU1_CSI1	N/A
GW510x	IMX6Q/DL	IPU1_CSI0	N/A
GW551x	IMX6Q/DL	N/A	IPU1_CSI0

The pipelines you construct with media-ctl will differ depending on what you are trying to accomplish as different hardware blocks (translated to entities in the media controller graph) can perform different translations such as colorspace conversion, scaling, rotation, or de-interlacing. In some cases there are multiple ways to achieve a certain translation with different trade-offs.

The IMX6 media driver registers several entities that take advantage of the IMX6 hardware (See: ​Documentation/media/v4l-drivers/imx):

• ipu_csi_mux - IPU CSI Multiplexer: Multiplexes the parallel capture bus and the MIPI capture bus to the Camera Sensor Interface (CSI)
• ipu_csi - IPU Capture Sensor Interface (IDMAC) (latches parallel data on the bus, or de-serializes MIPI data from the bus). In addition to raw frame capture this supports:
  • cropping using the crop selection subdev API
  • fixed divide-by-two down-scaling independently in width and height using the compose selection subdev API
  • frame skipping specified by setting the frame intervals at the sink and source pads
  • simple de-interlacing without motion compensation (activated if the sink pad's field type is an interlaced type and the source pad field type is set to none)
  • pixel reordering within the same colorspace: ie: UYVY2X8 -> YUYV2X8
  • pixel plane conversion: YUV -> YUV420 (planar)
  • frame interval monitor: For decoders such as the adv718x which occasionally send corrupt fields during NTSC/PAL signal re-sync (too little or too many video lines) the IPU can trigger a mechanism to re-establish vertical sync by adding a dummy line every frame causing a rolling effect from image to image or even a permanent split image. This mechanism can be used to detect corrupt fields and send a V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR that can be caught to issue a restart to correct the rolling/split image. The ipu_csi subdev includes custom controls to configure this 'Frame Interval Monitor' or FIM. The V4L FIM controls are V4L2_CID_IMX_FIM_NUM_SKIP, V4L2_CID_IMX_FIM_ICAP_CHANNEL and V4L2_CID_IMX_FIM_ICAP_EDGE.
• ipu_vdic - Conversion of interlaced video to progressive with support for different motion compensation modes (low/med/high motion). The mode is specified with the V4L2_CID_DEINTERLACING_MODE menu control. This entity has a direct connection pad from the ipu_csi entity (in which only high motion mode can be used) but has an additional source pad that can be used with other output or mem2mem device nodes (where high, low, or medium motion mode can be used).
• ipu_ic_prp - IC pre-processing entity: acts as a router routing data between source and sink pads. This entity can source to either ipu_ic_prpenc or ipu_ic_prpvf if it is sinking from ipu1_vdic, or it can sink directly from ipu_csi and source both output pads at the same time.
• ipu_ic_prpenc - IC pre-processing encode entity provides:
  • color-space conversion
  • resizing (downscaling and upscaling)
  • horizontal and vertical flip, and 90/270 degree rotation using the standard V4L2 controls
  • simple de-interlace without motion compensation
  • pixel reordering
• ipu_ic_prpvf - IC pre-process viewfinder entity: This is identical to the ipu_ic_prpenc entity supporting:
  • color-space conversion
  • horizontal and vertical flip, and 90/270 degree rotation using the standard V4L2 controls
  • simple de-interlace without motion compensation (unless the ipu_vdic is included in the pipeline as the the de-interlacing has already been done by the vdic with motion compensation)
  • pixel reordering

Ignoring the input and output pad numbering, and the IPU and CSI indices the following pseudo pipelines are useful:

• raw capture of input resolution:

  sensor -> ipu_csi_mux -> ipu_csi -> ipu_csi capture
  

  • use tda19971 source for digital HDMI and adv7180 source for analog CVBS
  • use correct indices on ipu and csi above depending on board/soc/input (see above table)
  • the IDMAC can be used for simple de-interlacing of interlaced video from the source by specifying a format with 'field:seq-tb' on the ipu_csi_mux and ipu_csi entities.
• de-interlace via VDIC high motion compensation:

  sensor -> ipu_csi_mux -> ipu_csi -> ipu_vdic -> ipu_ic_prp -> ipu_ic_prpvf -> ipu_ic_prpvf capture
  

  • use tda19971 source for digital HDMI and adv7180 source for analog CVBS
  • use correct indices on ipu and csi above depending on board/soc/input (see above table)
  • specify 'field:interlaced' on the format for ipu_csi_mux, ipu_csi, ipu_vdic and 'field:none' on ipu_ic_prp and ipu2_ic_prpvf (because ipu_ic_prp is the entity that can deinterlace with the IDMAC)
• IC direct conversions:
  • uses preprocess encode entity to route frames directly from the CSI to the IC to carry out scaling up to 1024x1024 resolution, CSC, flipping, and image rotation:

    sensor -> ipu_csi_mux -> ipu_csi -> ipu_ic_prp -> ipu_ic_prpenc -> ipu_ic_prpenc capture
    

• Motion compensated de-interlace:
  • routes frames from the CSI direct to the VDIC for motion-compensated (high mode) de-interlacing, scaling up to 1024x1024, CSC, flip, and rotation:

    sensor -> ipu_csi_mux -> ipu_csi -> ipu_vdic -> ipu_ic_prp -> ipu_ic_prpvf -> ipu_ic_prpvf capture
    

Note that to aid in the configuration of and for backward compatibility with V4L2 applications that use controls the capture device interfaces inherit controls from the active entities in the current pipeline thus these controls can be accessed via the entity subdev or from the active capture device interface. For example the FIM controls are available from the ipu_csi subdevs or from the active capture device.