Linux Core DSS WB User's Guide

Introduction

This page gives a basic description of DSS Write-Back hardware, the Linux kernel drivers (omapwb, omapwb-m2m and omapwb-cap) and various TI boards that use DSS Write-Back. The technical reference manual (TRM) for the SoC in question, and the board documentation give more detailed descriptions.

Release Applicable

This page applies to TI's v4.4 kernel. Although mem-2-mem support also applies to TI's v4.1 kernel.

Supported Devices

The DSS Write-Back IP is only available on the following TI SoCs or SoC families:

• OMAP4
• OMAP5
• AM5x
• DRA7x

Hardware Architecture

As described in Linux Core DSS User's Guide the DISPC has, from a high level view, a number of overlays and overlay managers.

WB is an overlay which can be sourced by one of the other overlays (mem-2-mem case) or by one of the overlay managers (capture/composition case).

An overview of the DSS hardware. The arrows show how overlays/pipelines are connected to overlay managers, which are further connected to encoders, which finally create an encoded pixel stream for display on to LCD or TV. The different colors of the blocks show the new sub-blocks added in subsequent DSS revisions

Write-Back Use Cases

Write-Back is basically used to take pixel data being presented to an overlay or overlay manager and write it back to DDR.

The following use cases are being considered:

1. Mem-2-Mem conversion

   Mem-2-Mem is used when we want to apply some level of conversion to source video image.

   A conversion can be any of the following: pixel format change and scaling up or down.

2. Capture

   Capture is used when we want to grab the output of an overlay manager currently connected to an active display.

   The same level of conversion can be applied here.

3. Composition

   Composition is used when we want to grab the output of an overlay manager even if it is not currently connected to an active display.

   The same level of conversion can be applied here.

Note that one of the hardware plane (VIDx/GFX) will get consumed in addition to the WB plane by Mem-2-Mem conversion driver. This is because WB pipeline module inside DSS controller has write only port to the DMA engine. Input to WB pipeline is either from VIDx/GFX pipeline output or the output from one of the Overlay manager.

Mem-2-Mem conversion

With Composition driver, number of hardware planes that gets acquired by the driver will depend upon the number of planes getting fed to the overlay manager.

Driver Architecture

The DSS WB driver is an optional component of the omapdrm driver located in the directory drivers/gpu/drm/omapdrm/ in the kernel tree.
The DSS WB driver is implemented as a set of DRM/V4L2 hybrid drivers.

From this point forward we will be using the DRM terminologies.

omapwb

omapwb is internally divided into smaller drivers for each of the identified use cases.

1. omapwb-m2m

   Handles frame conversion including pixel format and scaling.

   The driver automatically selects an unused plane as the source (it will typically try VID3 plane and search backward from there until it finds an unused plane).

   Default video node: /dev/video10

2. omapwb-cap

   Handles frame capture including pixel format and scaling.

   The driver will captures the frames that are being presented to a specified active CRTC.

   A crtc is selected using the V4L2 input selection API.

   Default video node: /dev/video11

3. omapwb-comp (not implemented yet)

   Handles frame composition including pixel format and scaling.

   The driver will grab the frames that are being presented to a specified CRTC.

   Here the main difference between capture and composition is that the CRTC does not need to be active or connected to a display.

   Default video node: tbd

DSS WB is a single hardware resource, which means that the above uses cases (i.e. video nodes) can only be used one at a time. For example if a user application has successfully opened /dev/video10 then concurrent attempts to open /dev/video11 would fails with an -EBUSY error until /dev/video10 is released/closed.

Driver Features

Note: this is not a comprehensive list of features supported/not supported.

Supported Features

• Pixel formats (valid for either input or output)
  • NV12
  • YUYV
  • UYVY
  • XR24

• Scaling
  • Up-sampling: up to 8x
  • Down-sampling: down to 1/4 (1/2 for NV12)

• V4L2 multi-planar buffers and interface

Unsupported Features/Limitations

• Composition use case is not currently available.
• Scaling is currently not available for the capture uses case.

  The capture resolution is forced to match the chosen CRTC.

• Capture on a currently disabled/inactive CRTC will cause capture to stall until the crtc is awaken.

Driver Configuration

Kernel Configuration Options

omapwb shows up as an option under omapdrm.

omapwb can be found under "Device Drivers/Graphics support" in the kernel menuconfig. You need to enable DRM (CONFIG_DRM) and then enable omapdrm (CONFIG_DRM_OMAP) before you can enable omapwb (CONFIG_DRM_OMAP_WB).

Driver Usage

Loading omapwb

As omapwb is included in omapdrm. There is no need to load anything else.

Using omapwb

When omapwb is enabled, the mem-2-mem device will appear (by default) as /dev/video10 and the capture device as /dev/video11. Standard V4L2 user space applications can be used with either device node as long as the capability of the application matches.

• omapwb-m2m example

  Use WB to convert a 800x480 YUYV video stream file into a 400x240 XR24 video stream.

v4l2-ctl -d /dev/video10 --set-fmt-video-out=width=800,height=480,pixelformat=YUYV --stream-from=input-test-800x480-yuyv.yuv --set-fmt-video=width=400,height=240,pixelformat=XR24 --stream-to=output_test_400x240_bgra.yuv --stream-mmap=6 --stream-out-mmap=6 --stream-count=10 --stream-poll

• omapwb-cap example

  Capture frames presented to CRTC#1 and save them as a YUYV video stream.

yavta -i1 -c60 -fYUYV -Fvout_800x480_yuyv.yuv -s800x480 /dev/video11

The kms++ library also contains two test applications under utils/ for both supported use cases. These are more geared toward functional test.
kms++ can be found from:

https://github.com/tomba/kmsxx

v4l2-ctl can be found from:

https://git.linuxtv.org/v4l-utils.git

yavta can be found from:

http://git.ideasonboard.org/yavta.git

Debugging

As omapwb-m2m and omapwb-cap drivers are based on the V4L2 framework, framework level tracing can be enable as follows:

• echo 3 >/sys/class/video4linux/video10/dev_debug

  This allows V4L2 ioctl calls to be logged.

• echo 3 > /sys/module/videobuf2_core/parameters/debug

  This allows VB2 buffers operation to be logged.

In addition omapwb also has specific debug log which can be enabled as follows:

• echo 1 > /sys/module/omapdrm/parameters/wbdebug

If you need to inspect the main DSS register the main omapdrm driver provides access to those through debugfs entries.
(See Linux Core DSS User's Guide for details).

TI Board Specific Information

None at this time.