Graphics and Video Drivers V4L2 Output Driver

Introduction

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

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

Installing the V4L2 modules

There are two modules required to start V4L2, videodev-SOCNAME.ko and stmvout-SOCNAME.ko, where SOCNAME is either stm8000 or sti5528 depending on the target platform. These modules can typically be found in:

/lib/modules/kernel version string/extras

in the target filesystem. For example, on the STm8000 the modules can be installed with the following commands:

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

This assumes that the ST framebuffer driver (which is currently required) has already been installed. Note that the inbuilt kernel V4L2 support must be disabled as this driver is currently based on an earlier V4L2 framework implementation. In the current release V4L compatibility is not supported.

The driver registers a device for each video plane it supports, the following entries should be added to /dev if they are not already present.

target# mknod /dev/vout0 c 81 50
target# mknod /dev/vout1 c 81 51
target# mknod /dev/vout2 c 81 52

The STm8000 has a single video plane, represented by /dev/vout0 and a graphics plane by /dev/vout1. The STi5528 has two video planes (/dev/vout0 and /dev/vout1) and a graphics plane (/dev/vout2). These planes all appear below the framebuffer plane; hence, to see them the framebuffer must either have per-pixel alpha transparency or have a global transparency value set. Video and graphics planes support different buffer formats which can be enumerated using the VIDIOC_ENUM_FMT IOCTL.

Video Buffers

Video is displayed in 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. Hence the amount of memory reserved for bigphysarea on the kernel boot command line must be sufficient to allocate the 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 just report the current display mode, as set by the framebuffer driver. Unlike the devices V4L2 was originally designed for, ST devices combine graphics and video onto the same display using integrated hardware. Hence the decision was taken to only support one interface (the framebuffer) to control the display mode.

Streaming I/O with userspace pointers (i.e. 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 ST 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 behaviour 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.

The VIDIOC_DQBUF call will always return EAGAIN if no buffer is available for de-queuing, regardless of the flags used to open the device. However poll() can be used to wait for buffers to be available, using the POLLIN event.

The semantics of VIDIOC_REQBUFS and VIDIOC_S_FMT after allocated buffers have been memory mapped to userspace are not correct. Currently it is necessary to close the V4L2 device handle and then open it again, if a change to the buffer format or number of buffers allocated is required.

ST Specific Extensions

V4L2 does not specify a way of specifying a sub-rectangle of a buffer to be displayed. This is inconvenient when the width of buffers must be rounded up, for instance to accomodate ST's macro block video buffer formats, or if you want to implement features such as pan and scan. In order to support this the VIDIOC_S_CROP interface will respond, if the type field is set to V4L2_BUF_TYPE_PRIVATE, 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 behaviour.

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/media/video/stmvout.h, in the supplied SRPM.

Controls

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