Distribution Guide Device drivers V4L2 output driver

V4L2 output driver

A V4L2 output driver is available for STi5528, STm8000 and STb7100 SoCs. This driver supports the streaming video buffer interface of a V4L2 output device, which allows decoded video in YCrCb 422R and STMicroelectronics' private YCrCb formats to be presented in real-time on a dedicated hardware video plane. It also allows graphics buffers (DVD sub-picture, for example) to be streamed in the same way as video onto a separate graphics plane (distinct from the framebuffer and video).

Please refer to the V4L2 API documentation for more information on V4L2 programming.

Installing the video output module

Before loading the video output module the generic "Video For Linux" support (CONFIG_VIDEO_DEV) must be enabled in the kernel. This option can be found in the Linux Kernel Configuration screen (see Kernel configuration); enter:

Device Drivers ---> Multimedia devices ---> Video For Linux

Note: The framebuffer module must already have been loaded.

The video output module is called stmvout-<socname>.ko, where <socname> is either sti5528, stm8000 or stb7100, depending on the target platform. If the driver sources have been built and installed on the target, using the instructions given in Framebuffer driver, the module will be found in /lib/modules/<kernel_version_string>/stm/ in the target file system.

For example, to install the module on an STm8000, enter the commands:

target# cd /lib/modules/2.6.11/stm
target# insmod stmvout-stm8000.ko

Devices and planes

The supported hardware all provide a number of display planes which, when enabled, are digitally mixed together using global and per-pixel alpha transparency.

The video output driver can utilize two types of these hardware display planes to present real-time streaming video or graphics. Firstly "video" planes display 422 or 420 YUV video, which can be resized and positioned anywhere on the screen. However the pixel formats they use are not those typically found in PC applications; the only standard format they support is V4L2_PIX_FMT_UYVY. Secondly "graphics" planes (known as GDPs) can display a number of standard RGB formats as well as V4L2_PIX_FMT_UYVY. The buffer formats supported can be listed using the VIDIOC_ENUM_FMT ioctl.

The driver registers a device for each plane it supports. By default, V4L will assign unique, incrementing, minor device numbers starting at zero for each device registered. Traditionally these have a corresponding device file named /dev/video<num>, where <num> is the minor number, for example /dev/video0. The V4L major device number is 81, so the device file can be created using:

target# mknod /dev/video0 c 81 0

Previous versions of the driver, registered devices with the minor number starting at 50. If required, this behavior can be maintained using the video_nr parameter, for example:

target# insmod stmvout-stm8000.ko video_nr=50

Table 5: Registered hardware planes shows the planes registered (using the name given in the chip datasheets) on each supported device.

These planes all appear below the framebuffer plane, so to see them the framebuffer must either have per-pixel alpha transparency or have a global transparency value set.

On the STb7100, VID1 is only supported on the main HD display pipeline and VID2 on the auxiliary display pipeline. A device will only be available if the framebuffer has started a display on the necessary pipeline (depending on the build configuration option CONFIG_STG_HD=y being set). Simultaneous use of both pipelines is not supported by the framebuffer or video output implementations. This means that GDP2 is only available on the STb7100 main HD display pipeline. When the framebuffer is configured for the auxiliary display, GDP2 is allocated to the framebuffer and therefore cannot be used by the video output driver.

Video buffers

Video is displayed using memory buffers obtained using the V4L2 VIDIOC_REQBUFS ioctl. On both the STm8000 and STi5528, this memory is obtained using the bigphysarea kernel interface, in the same manner as the framebuffer memory. This means that the amount of memory reserved for bigphysarea on the kernel boot command line must be sufficient to allocate the total number of video buffers required, in addition to the framebuffer and any other drivers using this memory pool. When requesting buffers, the type field must be set to V4L2_BUF_TYPE_OUTPUT and the memory field to V4L2_MEMORY_MMAP.

Limitations

The V4L2 ioctls that enumerate and set the display standard are deliberately limited to report only the current display mode, as set by the framebuffer driver. Unlike the devices V4L2 was originally designed for, STMicroelectronics' devices combine graphics and video on the same display using integrated hardware. Therefore the decision was taken that only one interface (the framebuffer) to control the display mode would be supported.

Streaming I/O with userspace pointers (using V4L2_MEMORY_USERPTR) is not supported as the display hardware requires a single physically contiguous memory region per buffer.

Currently, there is no comprehensive support for the enumeration and control of the different display output configurations possible on STMicroelectronics' SoCs. By default, the video planes are connected to the main TV output mixer on the device; the video content is mixed with the framebuffer content and the final display is routed to the RGB (TV SCART) and CVBS video DACs.

Both interlaced and progressive buffer content is supported, in both interlaced and progressive display modes. However, only V4L2_FIELD_ANY, V4L2_FIELD_NONE and V4L2_FIELD_INTERLACED are valid options when setting the buffer format. In interlaced display modes, progressive content is displayed on both fields; conversely on a progressive display, each field of an interlaced buffer is upsampled to the full display size and displayed on two consecutive frames. The latter behavior is only supported if the plane supports resizing; if it does not then the VIDIOC_S_FMT ioctl will change the field type to V4L2_FIELD_NONE. Applications should check the returned buffer format structure after calling VIDIOC_S_FMT to determine if they can work with the driver settings.

Specifying a buffer timestamp other than 0 will be ignored by the driver. Buffers are displayed in real-time based on the current video standard. The timestamp is correctly modified by the driver with the system time when the buffer is put onto the display; this can be used by the application when the buffer is dequeued using VIDIOC_DQBUF.

STMicroelectronics specific extensions

V4L2 does not include a way of specifying a subrectangle of a buffer to be displayed. This is inconvenient when the width of buffers must be rounded up, for instance to accommodate STMicroelectronics' macro block video buffer formats, or to implement features such as pan and scan. To support this, if the type field is set to V4L2_BUF_TYPE_PRIVATE, the VIDIOC_S_CROP interface will respond by setting a cropping rectangle on the source buffer. The size and location of the destination rectangle on the screen is specified using VIDIOC_S_CROP with the type field set to V4L2_BUF_TYPE_OUTPUT; this is the standard API behavior.

The video planes support two STMicroelectronics specific buffer formats, which are typically used when decoding MPEG video with the on-chip hardware MPEG2 decoder. The FOURCC defines for these formats can be found in the header file linux/stmvout.h in the /usr/include directory on the target.

Controls

The V4L2 output driver supports the following controls, which can be listed, queried and set in the standard V4L2 method (see API documentation for details).