DM814X C6A814X AM387X VPSS Video Driver User Guide PSP 04.01.00.02

Video Driver

Introduction

Video Processing Sub-System hardware integrates theee graphics pipeline, five video pipelines, two capture ports and 4 video compositors. Video compositors are connected to four VENCs to support various output format and mode.

The primary functionality of the VPSS driver is to provide interfaces to user level applications and management of Video Processing Sub-System hardware.

This section defines and describes the usage of user level interfaces of VPSS Driver.

References

1. Video for Linux Two Home Page [http://linux.bytesex.org/v4l2/]
2. Video for Linux Two API Specification [[http://v4l2spec.bytesex.org/v4l2spec/v4l2.pdf]

Acronyms & Definitions

Display Driver: Acronyms

Acronym	Definition
V4L2	Video for Linux Two
VPSS	Vidoe Processing SubSystem
HDMI	Hight Definition Multimedia Interface
DVO	Digital Video Output
VENC	Video Encoder
NTSC	National Television System Committee
PAL	Phase Alternating Line
SDK	Software Development Kit

Display Port and VENC name

Display Port Name	Type	VENC Name	Port Num for Pin	Sysfs Name
HDMI/DVO1	Digital	HDMI	VOUT1	Display0
DVO2	Digital	DVO2	VOUT0	Display1
SD	Analog	SD	N/A	Display2

Hardware Overview

The video processing subsystem provides the functions to display a video frame from the memory frame buffer to external display device, such as LCD,TV; or capture a video frame from external camera to memory. The video processing subsystem integrates the following main elements

• Graphics processing modules
• Video Capture processing modules
• Video display processing modules
• Video Compositor modules

Features

The VPSS driver supports the following features:

• Supports various display mode on HDMI/DVO2 VENCs through sysfs
• Supports 3 Graphics pipelines throught fbdev interface
• Supported color formats on Graphics pipeline: RGB565, ARGB1555, RGBA5551, ARGB4444, RGBA4444, ARGB6666,RGBA6666,RGB888, ARGB8888 and RGBA8888, BMP 1/2/4/8.
• Configuration of Graphics parameters such as height and width of display graphics, position of the display graphics, bits-per-pixel etc.
• Supports setting up of Graphics pipeline and VENCs destination(HDMI, DVO2 or SDVENC) through syfs interface.
• Supports buffer management through memory mapped(mmaped).
• Supports global alpha blending on RGB format, pixel alpha blending on ARGB/RGBA format and palette alpha blending on BMP formats.
• Supports colorkeying on graphics pipelines through FBDev.
• Supports scaling on graphcis pilelines through FBDev
• Supports boundbox on graphcis pipelines through FBDev
• Supports display priority on graphics pipelines throug FBDev
• Support various Video PLL frequency (297MHz, 148.5MHz, 74.25MHz and 54MHz) through sysfs
• Support various VENC clock source through sysfs
• Support various output for VENC through sysfs.
• Support customized display timing configuraiton for HDMI/DVO2 VENCs through sysfs

Architecture

This chapter describes the Driver Architecture and Design concepts

Driver Architecture

TI81XX Video Processing hardware integrates three graphics pipeline, five video pipelines, 2 capture ports and 3 video compositors. Video compositors are connected to three VENCs to support various output format and mode.

The primary functionality of the VPSS driver is to provide interfaces to user level applications and management to video processing subsystem hardware.

This includes, but is not limited to:

• GUI rendering through the graphics pipeline.
• Connecting each of three graphics pipelines to four compositors so the display layer is presented on the selected output path.

Video Processing Subsystem Architecture

Software Design Interfaces

Above figure (Video Processing Subsystem Architecture) shows the major components that makes up the VPSS software sub-system

• M3 VPSS Firmware

This is a firmware running over processor Cotex M3 controlling the Video Processing subsystem hardware.

• Syslink Library

This is a funcional layer controlling the inter-processor communction between Cotex A8 and Cotex M3.

• VPSS FVID2 Library

This is a HAL/functional layer controlling the Firmware running over the M3. It exposes the number of APIs controlling the video compositors, VENCs, graphics/video pipelines to the user interface drivers like V4L2 and FBDEV. It translates the V4L2/Fbdev data structures and ioctl to FVID2 data structures and command, and call the Linux Syslink IPC notify function to pass FVID2 data structures and commands to Firmware running over the M3 processor.

• SYSFS interfaces

The SYSFS interfaces are mostly used as the control path for configuring the VPSS parameters which are common between FBDEV and V4L2 like the venc modes etc. It is also used for switching the output of the pipeline to different video compositors.

• Frame Buffer Driver

This driver is registered with the FBDEV subsystem, and is responsible for managing the graphics layer frame buffer. Driver creates /dev/fb0, /dev/fb1 and /dev/fb2 as the device nodes. Application can open these device nodes to open the driver and negotiate parameters with the driver through frame buffer ioctls. Application maps driver allocated buffers in the application memory space and fills them for the driver to display.

• Video Applications & V4L2 subsystem

Video applications (camera, camcorder, image viewer, etc.) use the standard V4L2 APIs to render static images and video to the video layers, or capture/preview camera images.

Usage

Opening and Closing of Driver

The device can be opened using open call from the application, with the device name and mode of operation as parameters. Application can open the driver only in blocking mode. Non-blocking mode of open is not supported.

• FBDEV Driver

The driver will expose three software channels (/dev/fb0, /dev/fb1, /dev/fb2) for the graphics pipeline.

<syntaxhighlight lang='c'> /* Open a graphics Display logical channel in blocking mode */ fd = open ("/dev/fb0", O_RDWR); if (fd == -1) {

   perror("failed to open display device\n");
   return -1;

}

/* ... */

/* Closing of channels */ close (fd); </syntaxhighlight>

Command Line arguments

Command Line Arguments

Argument	Description
vram	Total framebuffer memory reserverd for the Fbdev driver

Following example shows how to specify total framebuffer size as boot time argument

setenv bootargs console=ttyO0,115200n8 mem=128M noinitrd root=/dev/nfs nfsroot=nfs-server/home,nolock ip=dhcp vram=50M

FBDEV Driver

FBDEV driver supports set of command line argument for size of vram and debug option. These command line arguments can only be used as module arguments since FBDEV driver only supports module build.

Below is the list of arguments which Fbdev driver supports -

Fbdev Driver Command Line Arguments

Argument	Description
vram	VRAM allocated memory for a framebuffer, user can individually configure VRAM buffers for each plane/device node
debug	Enable Fbdev driver debug messaging

Following example shows how to specify size of framebuffer in module argument:

$ insmod ti81xxfb.ko vram=0:16M,1:16M,2:6M

Following example shows how to enable debug of Fbdev in module argument:

$ insmod ti81xxfb.ko debug=1

VPSS Driver'

VPSS driver supports set of command line arguments. These command line arguments can only be used as module arguments since VPSS driver only supports module build.

Below is the list of arguments which VPSS driver supports -

VPSS Driver Command Line Arguments

Argument	Description
clksrc	clock source for hdmi/dvo2 VENC. . hdmi:dclk/dclkdiv2/dclkdiff,dvo2:aclk/aclkdiv2/aclkdiff
debug	Enable VPSS Driver debug messaging
mode	Default video mode(1080p-60/1080p-30/1080i-60/720p-60/ntsc/pal) for specified VENC(hdmi, dvo2,sdvenc) if mode is not assigned during the boot time, driver uses the following mode: hdmi: 1080p-60, dvo2:1080p-60, sd:ntsc
tiedvencs	OR value of the VENCs(1:hdmi venc, 4:dvo2 venc, 8:sdvenc venc)
sbufaddr	Physical DDR address of the sharing buffer between Processor A8 and M3. This sharing buffer is used as payload to store FVID2 structurs communicated bewteen A8 and M3. The buffer must be non-cacheable DDR from Ducati side and should not be accessed by any other software components. This buffer should be predefined in the M3 Fimrware.
sbufsize	Size of the sharing buffer between processor A8 and M3.
timeout	timeout value(ms) to be set in driver to determine how long driver should wait the response from M3. If it is set to zero, driver waits infinitely. By default, this is set to 2000 ms

Following example shows how to specify HDMI VENC mode as module argument:

$ insmod vpss.ko mode=hdmi:1080p-60

Following example shows how to tie hdmi(1) venc and dvo2(4) venc together as module argument:

• NOTE: Application should make sure the tied vencs have the same timing. VPSS driver does not check for this.

$ insmod vpss.ko tiedvencs=5

Following example shows how to set up the sharing buffer address

• NOTE: If sbufaddr is not set, driver sets sharing buffer base address to 0x8DE00000. If this release is used on the DM814X Platform, it is responsibility of the application to set sbufaddr=0xCFE00000 when inserting the modules.

Sharing buffer Address

Platform	VPSS-M3 Firmware	Default Value
DM814X	ti814x_hdvpss.xem3	0xCFE00000
C6A814X	c6a814x_hdvpss.xem3	0x8DE00000

$insmod vpss.ko sbufaddr=0xCFE00000

Following example shows how to set up the sharing buffer size. This size can not be over 2MB.

• NOTE: If sbufsize is not set, driver sets buffer size equal to 2MB.

$insmod vpss.ko sbufsize=1024K

File:Ti814x venc clksrc.png

Video Processing Subsystem VENC Clock Source

Below is the list of arguments of clksrc supports

VPSS Driver Clock Source Arguments

Argument	Description
dclk	clk1x/dvo1_clk/dvo2_clk/vbi_clk_hd uses hd_venc_d_clk as clock source
dclkdiv2	clk1x/dvo1_clk/dvo2_clk/vbi_clk_hd used hd_venc_d_clk/2 as clock source
dclkdiff	clk1x uses hd_venc_d_clk/2 as clocksource, while dvo1_clk/dvo2_clk/vbi_clk_hd used hd_venc_d_clk as clock source
aclk	clk1x/dvo2_clk/vbi_clk_hd uses hd_venc_a_clk as clock source
aclkdiv2	clk1x/dvo2_clk/vbi_clk_hd uses hd_venc_a_clk/2 as clock source
aclkdiff	clk1x uses hd_vencc_a_clk/2 as clock source while dvo2_clk/vbi_clk_hd uses hd_venc_a_clk as clock source

Following example show how to choose a clock as the source clock of DVO2 VENC.

$ insmod vpss.ko clksrc=dvo2:aclk

Following example show how to enable debug of VPSS driver

$ insmod vpss.ko debug=1

Buffer Management

Memory requirement for V4L2 and FBDEV driver

Driver	FB0(dev/fb0)	FB1(dev/fb1)	FB2(dev/fb2)
Fbdev Driver	A single buffer of size 1920*1080*4*2 bytes, can be changed through bootargs	0 bytes if app does not assign size for this node through bootargs	0 bytes if app does not assign size for this node through bootargs

• FBDEV Driver

FBDEV driver supports only memory mapped buffers. Driver allocates one physically contiguous buffers for each node, which can support up to 1920x1080 resolution 32 bpp format. By default, driver only allocates the memory for FB0(dev/fb0) node. Application need set the memory size if accessing /dev/fb1 and /dev/fb2 when loading FBDev modules.

Set Frame Buffer size for FB Nodes

$ insmod ti81xxfb.ko vram=0:XXM,1:YYM,2:ZZM

Following steps are required to map buffers in application memory space.

Getting fix screen information
FBIOGET_FSCREENINFO ioctl is used to get the not-changing screen information like physical address of the buffer, size of the buffer, line length.

<syntaxhighlight lang='c'> /* Getting fix screen information */ struct fb_fix_screeninfo fix;

ret = ioctl(fd, FBIOGET_FSCREENINFO, &fix); if (ret < 0) {

   printf("FBIOGET_FSCREENINFO\n");
   close(fd);
   exit(0);

}

printf("Line length = %d\n", fix.line_length); printf("Physical Address = %x\n", fix.smem_start); printf("Buffer Length = %d\n", fix.smem_len); </syntaxhighlight>

Getting Variable screen information
FBIOGET_VSCREENINFO ioctl is used to get the variable screen information like resolution, bits per pixel etc...

<syntaxhighlight lang='c'> /* Getting fix screen information */ struct fb_var_screeninfo var;

if (ioctl(fd, FBIOGET_VSCREENINFO, &var) < 0) {

   printf("FBIOGET_VSCREENINFO\n");
   close(fd);
   exit(0);

}

printf("Resolution = %dx%d\n", var.xred, var.yres); printf("bites per pixel = %d\n", var.bpp); </syntaxhighlight>

Mapping Kernel space address to user space
Mapping the kernel buffer to the user space can be done via mmap system call. <syntaxhighlight lang='c'> /* addr hold the user space address */ unsigned int addr, buffersize;

/* Get the fix screen info */

/* Get the variable screen information */

buffersize = fix.line_length * var.yres; addr = mmap(NULL, buffersize, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); </syntaxhighlight>

Transparency Keying

The encoded pixel color value is compared to the application defined transparency color key(RGB888) based the LSB bits mask set by the application to determine whether the pixel is to be transparent or not. There are four types of the bit mask offered by the hardware: No Masking, whole pixel color value is compared to the transparency color key; Mask[0]: MSB[7:1] of the encoded pixel color value is compared to the corresponding 7 bits of transparency color key; MASK[1:0]: MSB[7:2] of the encoded pixel color value is compared to the corresponding bits of transparency color key; MAKS[2:0]: MSB[7:3] of the encoded pixel color value is compared to the corresponding bits of transparency color key.

User can enable/disable color key function, set color keying and mask type through Fbdev Driver private IOCTL interface.

• Using fbdev IOCTL

Enable Transparency Keying:

<syntaxhighlight lang='c'> struct ti81xxfb_region_params regp;

if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) { perror("TIFB_GET_PARAMS\n");

       close(fd);

exit(1); }

/* Enable the Transparency Keying */ regp.transen = TI81XXFB_FEATURE_ENABLE; if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {

   perror ("TIFB_SET_PARAMS.\n");
   close(fd);
   exit(1);

} </syntaxhighlight>

Disable Transparency Keying:

<syntaxhighlight lang='c'> struct ti81xxfb_region_params regp;

if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) { perror("TIFB_GET_PARAMS\n");

       close(fd);

exit(1); }

/* Disable the Transparency Keying */ regp.transen = TI81XXFB_FEATURE_DISABLE; if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {

   perror ("TIFB_SET_PARAMS.\n");
   close(fd);
   exit(1);

} </syntaxhighlight>

Set Transparency Keying Value(RGB888):

<syntaxhighlight lang='c'> struct ti81xxfb_region_params regp; u8 key_rgb888; /*RGB888 format*/

if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) { perror("TIFB_GET_PARAMS\n");

       close(fd);

exit(1); } /* Set the Transparency Keying */ regp.transcolor = key_rgb888; if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {

   perror ("TIFB_SET_PARAMS.\n");
   close(fd);
   exit(1);

} </syntaxhighlight>

Set Transparency Keying Mask Type:

<syntaxhighlight lang='c'> struct ti81xxfb_region_params regp; struct ti81xxfb_transparancy_type trans_type;

if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) { perror("TIFB_GET_PARAMS\n");

       close(fd);

exit(1); }

/* Set the Transparency Keying Mask type */ regp.transtype= trans_type; if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {

   perror ("TIFB_SET_PARAMS.\n");
   close(fd);
   exit(1);

} </syntaxhighlight>

Alpha Blending

Alpha blending is a process of blending a foreground color with a background color and producing a new blended color. New blended color depends on the transparency factor referred to as alpha factor of the foreground color. If the alpha factor is 100% then blended image will have only foreground color. If the alpha factor is 0% blended image will have only back ground color. Any value between 0 to 100% will blend the foreground and background color to produce new blended color depending upon the alpha factor.

Alpha blending with almost 50% transparency

Alpha blending with almost 100% transparency

Alpha blending with almost 0% transparency

Graphics pipelines of the VPSS are capable of supporting alpha blending. Three types of alpha blending is supported global, palette and pixel alpha blending. RGB formtas of graphics pipeline support global alpha blending, BMP formats of graphcis pipeline support palette alpha blending, ARGB and RGBA formats of graphics pipeline supports pixel based alpha blending. In which A represent the alpha value for each pixel. Thus, each pixel can have different alpha value. While global alpha is the constant alpha factor for the pipeline for all the pixels.

FBDev IOCTL

All three kind of blending are support through fbdev driver.

• Disable alpha blending

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
/*Disable Alpha Blending*/
regp.blendtype = TI81XXFB_BLENDING_NO;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
    perror ("TIFB_SET_PARAMS.\n");
    close(fd);
    exit(1);
}

• Global Alpha blending

User can configure global alpha value either through FBDEV ioctl.

Below programlisting shows how to set the global alpha value for graphics pipeline.

struct ti81xxfb_region_params  regp;
u8    alpha;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
/*Set Global Alpha Blending*/
regp.blendtype = TI81XXFB_BLENDING_GLOBAL;
regp.blendalpha = alpha;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
    perror ("TIFB_SET_PARAMS.\n");
    close(fd);
    exit(1);
}

• Pixel Based Alpha blending

FBDEV driver supports alpha blending through ARGB/RGBA pixel format

Below programlisting shows how to set the pxiel alpha value for graphics pipeline.

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
/*Set Pixel Alpha Blending*/
regp.blendtype = TI81XXFB_BLENDING_PIXEL;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
    perror ("TIFB_SET_PARAMS.\n");
    close(fd);
    exit(1);
}

• Palette Based Alpha blending

FBDEV driver supports alpha blending through CLUT data.

Below programlisting shows how to set the palette alpha value for graphics pipeline.

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
/*Set Palette Alpha Blending*/
regp.blendtype = TI81XXFB_BLENDING_PALETTE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
    perror ("TIFB_SET_PARAMS.\n");
    close(fd);
    exit(1);
}

Scaling

Graphics pipeline supports 0.25x-4x scaling with a step size of 0.01. The scalar has 5tap/8phase polyphase horizontal filter and 4taps/8phase polyphase vertical filter. Meanwhile, When the target display of the graphics pipeline conncted to is in a interlaced scan mode, graphics pipeline could also performs anti-flicker filtering using the including scalar. This can be achieved by seting scaling ratio 1.

Below show how to enable the scaling feature

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}

regp.scalaren = TI81XXFB_FEATURE_ENABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
	perror("TIFB_SET_PARAMS\n");
        close(fd);
	exit(1);
}

Below show how to disable the scaling feature

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
regp.scalaren = TI81XXFB_FEATURE_DISABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
	perror("TIFB_SET_PARAMS\n");
        close(fd);
	exit(1);
}

NOTE
When graphics scalar performs scaling up or down, it could output maximum 2 more lines/pixels than what it is configured. App should consider this into design to not out of the display frame boundary.
TIFB_SET_SCINFO ioctl must be called before enabling the scaling feature. See Section 5.1.3[1].

Stenciling

Graphics pipeline support a 1-bit for each pixel of a image that has "stenciling" feature enabled. This bit is used to force the alpha value of the pixel to ZERO in order to "mask"-off the pixel(such as transparent).

Below show how to enable the stenciling feature

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
regp.stencilingen = TI81XXFB_FEATURE_ENABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
	perror("TIFB_SET_PARAMS\n");
        close(fd);
	exit(1);
}

Below show how to disable the stenciling feature

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
regp.stencilingen = TI81XXFB_FEATURE_DISABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
	perror("TIFB_SET_PARAMS\n");
        close(fd);
	exit(1);
}

NOTE
TIFB_ALLOC and TIFB_SET_STENC ioctl must be called before enabling the scaling feature. See Section 5.1.3[2].

Bound Box Blending

Graphics pipleline supports overwriting alpha values of piels that make up a 1-pixel wide boundary box of a image with a semi-transparnt value(0x80,default) so the flickering around the edges can be minimized.

Below shows how to enable boundbox feature and change the bound box alpha value

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
regp.bbalpha = 0x40;
regp.bben = TI81XXFB_FEATURE_ENABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
	perror("TIFB_SET_PARAMS\n");
        close(fd);
	exit(1);
}

Below shows how to disable boundbox feature

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
regp.bben = TI81XXFB_FEATURE_DISABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
	perror("TIFB_SET_PARAMS\n");
        close(fd);
	exit(1);
}

Buffer Format

Buffer format describes the pixel format in the image. It also describes the memory organization of each color component within the pixel format. In all buffer formats, blue value is always stored in least significant bits, then green value and then red value. The alpha value stored is up to the RGBA or ARGB format.

FBDEV Driver

Graphics pipeline supports following buffer format: RGB565, ARGB1555, RGBA5551, ARGB4444,RGBA4444, ARGB6666, RGBA6666, RGB888, ARGB8888 and RGBA8888. Moreover graphics pipeline supports 1/2/4/8 BMP format. Buffer format can be changed in FBDEV driver by using bpp, red, green, ,blue and transparency fields of fb_vscreeninfo structure and ioctl FBIOPUT_VSCREENINFO. Application needs to specify bits per pixel and length and offset of red, green, blue and transparnecy component to let driver know the right pixel format.

Extra care must be taken by the application when dealing with 1/2/4 BMP format. Graphis pipeline support 8 different 1b BMP formats, 4 different 2b BMP formats and 2 different 4b BMP formats. By default, if bits_per_pixel was assigned to 1, TI81XXFB_BMP1_OFF0 format will be used by the driver. if bits_per_pixel was assigned to 2, TI81XXFB_BMP2_OFF0 will be used by the driver. If bits_per_pixel was assigend to 4, TI81XXFB_BMP1_L will be used by the driver. If default value is not meeting application's requirements, please use nonstd filed in the fb_vscreeninfo structure to set the right 1/2/4 BMP format. Do not forget to set nonstd to 0 when switching to different pixel format.

Following example shows how to ARGB666 bits per pixels.

struct fb_varscreeninfo var;
if (ioctl(fd, FBIOGET_VSCREENINFO, &var) < 0) {
    perror("FBIOGET_VSCREENINFO\n");
    close(fd);
    exit(0);
}
var.bpp = 24;
var.red.length = var.green.length = var.blue.length = var.transp.length = 4;
var.transp.offset = 18;
var.red.offset = 12;
var.green.offset = 6;
var.blue.offset = 0;
if (ioctl(fd, FBIOPUT_VSCREENINFO, &var) < 0) {
    perror("FBIOPUT_VSCREENINFO\n");
    close(fd);
    exit(0);
}

Buffer Formats

RGB565 Data Memory Organization

ARGB1555 Data Memory Organization

ARGB444 Data Memory Organization

RGBA5551 Data Memory Organization

RGBA4444 Data Memory Organization

RGB888 Data Memory Organization

ARGB6666 Data Memory Organization

RGBA6666 Data Memory Organization

ARGB8888 Data Memory Organization

RGBA8888 Data Memory Organization

BPP8 Data Memory Organization

BPP4 LOWER Data Memory Organization

BPP4 UPPER Data Memory Organization

BPP2 OFFSET0 Data Memory Organization

BPP2 OFFSET1 Data Memory Organization

BPP2 OFFSET2 Data Memory Organization

BPP2 OFFSET3 Data Memory Organization

BPP1 OFFSET0 Data Memory Organization

BPP1 OFFSET1 Data Memory Organization

BPP1 OFFSET2 Data Memory Organization

BPP1 OFFSET3 Data Memory Organization

BPP1 OFFSET4 Data Memory Organization

BPP1 OFFSET5 Data Memory Organization

BPP1 OFFSET6 Data Memory Organization

BPP1 OFFSET7 Data Memory Organization

Display Position of Graphics

The display position of graphics pipeline is able to changed within the resolution defined by the VENCs which graphics pipiline is connected.

Following example shows how to change display position graphics.

struct ti81xxfb_region_params  regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
	perror("TIFB_GET_PARAMS\n");
        close(fd);
	exit(1);
}
/*Set the Display position*/
regp.pos_x = 10;
regp.pos_y = 20;
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
    perror ("TIFB_SET_PARAMS\n");
    close(fd);
    exit(1);
}

Color look table

The graphics pipeline supports the color look up table. The CLUT mode uses the encoded pixel values from the input image as pointers to index the 32-bit-wide CLUT value: 1-BPP pixels address 2 entries, 2-BPP pixels address 4 entries, 4-BPP pixels address 16 entries, and 8-BPP pixels address 256 entries.

Driver supports 1, 2, 4 and 8 bits per pixel image format using color lookup table. FBIOPUTCMAP and FBIOGETCMAP can be used to set and get the color map table. When CLUT is set, the driver makes the hardware to reload the CLUT.

Following example shows how to change CLUT.

struct fb_cmap cmap;
unsigned short r[256]={0xFF, 0x00, 0x00, 0xFF};
unsigned short g[256]={0x00, 0xFF, 0x00, 0xFF};
unsigned short b[256]={0x00, 0x00, 0xFF, 0x00};
unsigned short t[256]={0xFF, 0xFF, 0xFF, 0xFF};
cmap.len = 256;
cmap.red = r;
cmap.green = g;
cmap.blue = b;
cmap.transp = t;
if (ioctl(fd, FBIOPUTCMAP, &cmap)) {
    perror("FBIOPUTCMAP\n");
    close(fd);
    exit(3);
}

Software Interfaces

Frame-Buffer Driver Interface

Application Interface

open ()
To open a framebuffer device
close ()
To close a framebuffer device
ioctl ()
To send ioctl commands to the framebuffer driver.
mmap ()
To obtain the framebuffer region as mmap'ed area in user space.

Supported Standard IOCTLs

FBIOGET_VSCREENINFO, FBIOPUT_VSCREENINFO
These I/O controls are used to query and set the so-called variable screen info. This allows an application to query or change the display mode, including the color depth, resolution, timing etc. These I/O controls accept a pointer to a struct fb_var_screeninfo structure. The video mode data supplied in the fb_var_screeninfo struct is translated to values loaded into the display controller registers.

FBIOGET_FSCREENINFO
This I/O control can be used by applications to get the fixed properties of the display, e.g. the start address of the framebuffer memory. This I/O control accepts a pointer to a struct fb_fix_screeninfo.

FBIOGETCMAP, FBIOPUTCMAP
These I/O controls are used to get and set the color-map for the framebuffer. These I/O controls accept a pointer to a struct fb_cmap structure. TI81XX supports 256*32(RGBT) color-map, so the len of the fb_cmap should be 256, or driver returns error.

FBIO_BLANK
This I/O control is used to blank or unblank the framebuffer console.

FBIO_WAITFORVSYNC
This I/O control is used to put an application to sleep until next vertical sync interval of the display.

Supported Custom IOCTLs

TIFB_GET_PARAMS
Ioctl returns the parameters of the current graphics features.

Data Structure:

enum ti81xxfb_status {
 Ti81XXFB_FEATURE_DISABLE = 0,
 Ti81XXFB_FEATURE_ENABLE
};

enum ti81xxfb_blending_type {
 Ti81XXFB_BLENDING_NO = 0,
 Ti81XXFB_BLENDING_GLOBAL,
 Ti81XXFB_BLENDING_PALETTE,
 Ti81XXFB_BLENDING_PIXEL
};

enum ti81xxfb_transparancy_type {
 Ti81XXFB_TRANSP_LSPMASK_NO = 0,
 Ti81XXFB_TRANSP_LSPMASK_1,
 Ti81XXFB_TRANSP_LSPMASK_2,
 Ti81XXFB_TRANSP_LSMMASK_3
};

struct ti81xxfb_region_params {
 __u16 				ridx;
 __u16 				pos_x;
 __u16 				pos_y;
 __u16 				priority;
 /*enum ti81xxfb_status*/
 __u32		  		firstregion;
 /*enum ti81xxfb_status*/
 __u32				lastregion;
 /*enum ti81xxfb_status*/
 __u32		  		scalaren;
 /*enum ti81xxfb_status*/
 __u32		  		stencilingen;
 /*enum ti81xxfb_status*/
 __u32				bben;
 /*enum ti81xxfb_status*/
 __u32		  		transen;
 /*enum ti81xxfb_blending_type*/
 __u32				blendtype;
 /*enum ti81xxfb_transparancy_type*/
 __u32 				transtype;
 __u32  			transcolor;
 __u8  				bbalpha;
 __u8   			blendalpha;
 __u8				reserved[2];
};

• NOTE: firstregion and lastregion must be set to 1, these two fields are reserved for future usages.

Usage:

struct ti81xxfb_region_params regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
 perror("TIFB_GET_PARAMS\n");
 close(fd);
 exit(1);
}

TIFB_SET_PARAMS
Ioctl set the current graphics features.

Data Structure:

enum ti81xxfb_status {
 TI81XXFB_FEATURE_DISABLE = 0,
 TI81XXFB_FEATURE_ENABLE
};

enum ti81xxfb_blending_type {
 TI81XXFB_BLENDING_NO = 0,
 TI81XXFB_BLENDING_GLOBAL,
 TI81XXFB_BLENDING_PALETTE,
 TI81XXFB_BLENDING_PIXEL
};

enum ti81xxfb_transparancy_type {
 TI81XXFB_TRANSP_LSPMASK_NO = 0,
 TI81XXFB_TRANSP_LSPMASK_1,
 TI81XXFB_TRANSP_LSPMASK_2,
 TI81XXFB_TRANSP_LSMMASK_3
};

struct ti81xxfb_region_params {
 __u16 				ridx;
 __u16 				pos_x;
 __u16 				pos_y;
 __u16 				priority;
 /*enum ti81xxfb_status*/
 __u32		  		firstregion;
 /*enum ti81xxfb_status*/
 __u32				lastregion;
 /*enum ti81xxfb_status*/
 __u32		  		scalaren;
 /*enum ti81xxfb_status*/
 __u32		  		stencilingen;
 /*enum ti81xxfb_status*/
 __u32				bben;
 /*enum ti81xxfb_status*/
 __u32		  		transen;
 /*enum ti81xxfb_blending_type*/
 __u32				blendtype;
 /*enum ti81xxfb_transparancy_type*/
 __u32 				transtype;
 __u32  			transcolor;
 __u8  				bbalpha;
 __u8   			blendalpha;
 __u8				reserved[2];
};

• NOTE: firstregion and lastregion must be set to 1, these two fields are reserved for future usages.

Usage:

struct ti81xxfb_region_params regp;
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
 perror("TIFB_GET_PARAMS\n");
 close(fd);
 exit(1);
}
if (ioctl(fd, TIFB_SET_PARAMS, &regp) < 0) {
 perror("TIFB_SET_PARAMS\n");
 close(fd);
 exit(1);
}

TIFB_QUERY_MEMINFO
Returns the size and type of the frame buffer

Data Structure:

enum ti81xxfb_mem_mode {
 TI81XXFB_MEM_NONTILER = 0,
 TI81XXFB_MEM_TILER_PAGE ,
 TI81XXFB_MEM_TILER_8,
 TI81XXFB_MEM_TILER_16,
 TI81XXFB_MEM_TILER_32
};
struct ti81xxfb_mem_info {
 __u32 size;
 /*ti81xxfb_mem_mode*/
 __u32  type;
};

NOTE: Only TI81XXFB_MEM_NONTILER is supported currently.

Usage:

struct ti81xxfb_mem_info mi;
if (ioctl(fb, TIFB_QUERY_MEM, &mi)) {
 perror("TIFB_QUERY_MEM.\n");
 close(fd);
 exit(1);
}

TI81XX_SETUP_MEM
Allows user to setup the frame buffer memory, like size and type.

Data Structure:

enum ti81xxfb_mem_mode {
 TI81XXFB_MEM_NONTILER = 0,
 TI81XXFB_MEM_TILER_PAGE ,
 TI81XXFB_MEM_TILER_8,
 TI81XXFB_MEM_TILER_16,
 TI81XXFB_MEM_TILER_32
};
struct ti81xxfb_mem_info {
 __u32 size;
 /*ti81xxfb_mem_mode*/
 __u32  type;
};

NOTE: Only TI81XXFB_MEM_NONTILER is supported currently.

Usage:

struct ti81xxfb_mem_info mi;
if (ioctl(fb, TIFB_QUERY_MEM, &mi)) {
 perror("TIFB_QUERY_MEM.\n");
 close(fd);
 exit(1);
}

mi.size = <Expected size of buffer>
mi.type = <Expected type of buffer>
if (ioctl(fb, TIFB_SETUP_MEM, &mi)) {
 perror("TIFB_SETUP_MEM.\n");
 close(fd);
 exit(1);
}

TIFB_SET_SCINFO

Allow users to config the scalar ratio

Data Structure:

struct ti81xxfb_coeff {
 __u16     horcoeff[TI81XXFB_COEFF_HOR_TAP][TI81XXFB_COEFF_PHASE];
 __u16     vercoeff[TI81XXFB_COEFF_VER_TAP][TI81XXFB_COEFF_PHASE];
};

NOTE:
each coefficient is 10 bit wide, so MSB[15:10] will be truncated by the driver.

struct ti81xxfb_scparams {
 __u16                  inwidth;
 __u16                  inheight;
 __u16                  outwidth;
 __u16                  outheight;
 struct ti81xxfb_coeff  *coeff
};

NOTE:

• If input is scaled either up or down to full screen of the display output format, the outwidth and outheight should be set to VENC output format -2. For example: if display output format is 1280x720, then outwidht is set to 1280 - 2 = 1178, outheight is set to 720 - 2 = 718. If the outwidth and outheight is not following the rule, a distorted image could be obtained.
• 0.25x-4x scaling is supported for both horizontal and vertical direction.
• if 1x is selected, hardware performs anti-flicker filtering.
• If app wants to use preloaded coefficients, please set coeff = NULL.

Usage: scale input image to 2x(horizontal) and 1.5x(vertical) with app's own coefficients

struct ti81xxfb_scparams  scprms;
struct ti81xxfb_coeff    coeff;
struct ti81xxfb_region_params regp;

scprms.inwidth = x;
scprms.inheight = y;
scprms.outwidth = 2*x;
scprms.outheight = 1.5*y,
scprms.coeff = &coeff;

if (ioctl(fd, TIFB_SET_SCINFO, &scprms) < 0) {
 perror("TIFB_SET_SCINFO.\n");
 close(fd);
 exit(1);
}

if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
 perror("TIFB_GET_PARAMS\n");
 close(fd);
 exit(1);
}

regp.scalaren = TI81XXFB_FEATURE_ENABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp)< 0) {
 perror("TIFB_SET_PARAMS\n");
 close(fd);
 exit(1);
}

Usage: scale input image to 2x(horizontal) and 1.5x(vertical) with preloaded coefficients

struct ti81xxfb_scparams  scprms;
struct ti81xxfb_region_params regp;

scprms.inwidth = x;
scprms.inheight = y;
scprms.outwidth = 2 * x;
scprms.outheight = 1.5 * y,
scprms.coeff = NULL;

if (ioctl(fd, TIFB_SET_SCINFO, &scprms) < 0) {
 perror("TIFB_SET_SCINFO.\n");
 close(fd);
 exit(1);
}
if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
 perror("TIFB_GET_PARAMS\n");
 close(fd);
 exit(1);
}

regp.scalaren = TI81XXFB_FEATURE_ENABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp)< 0) {
 perror("TIFB_SET_PARAMS\n");
 close(fd);
 exit(1);
}

Usage: Anti-Flicker Implementation

struct ti81xxfb_scparams  scprms;
struct ti81xxfb_region_params regp;

scprms.inwidth = x;
scprms.inheight = y;
scprms.outwidth = x;
scprms.outheight = y,
scprms.coeff = NULL;

if (ioctl(fd, TIFB_SET_SCINFO, &scprms) < 0) {
 perror("TIFB_SET_SCINFO.\n");
 close(fd);
 exit(1);
}

if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
 perror("TIFB_GET_PARAMS\n");
 close(fd);
 exit(1);
}

regp.scalaren = TI81XXFB_FEATURE_ENABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp)< 0) {
 perror("TIFB_SET_PARAMS\n");
 close(fd);
 exit(1);
}

TIFB_GET_SCINFO
Allow users to get current scalar ratio

Data Structure:

struct ti81xxfb_scparams {
 __u16                  inwidth;
 __u16                  inheight;
 __u16                  outwidth;
 __u16                  outheight;
 struct ti81xxfb_coeff  *coeff;
};

NOTE:
coeff is not used when called TIFB_GET_SCINFO ioctl.

Usage:

struct ti81xxfb_scparams  scprms;
if (ioctl(fd, TIFB_GET_SCINFO, &scprms) {
 perror("TIFB_GET_SCINFO.\n");
 close(fd);
 exit(1);
}

TIFB_ALLOC
This ioctl is used to allocate a memory from reserved pool and return the physical addres back to app. This memory can be used by the stenciling data buffer.

USAGE: allocate a buffer

unsigned long size;
unsigned long phy_addr;
unsigned long temp;

size = 8*1024;
temp = size;
if(ioctl(fd, TIFB_ALLOC, &size)) {
 perror(“TIFB_ALLOC.\n");
 close(fd);
 exit(1);
}
phy_addr = size;

TIFB_FREE
This ioctl is to free a memory allocated by the TIFB_ALLOC.

USAGE

unsigned long phy_addr;
void virt_addr;
unsigned long size;

munmap(virt_addr, stensize);
if (ioctl(fd,TIFB_FREE, &phy_addr)) {
 perror(" TIFB_FREE.\n");
 close(fd);
 exit(1);
}

NOTE:
If the memory is used by the stenciling, please disable stenciling feature before freeing it.

TIFB_SET_STENC
Allow user to config stenciling.

Data Structure:

struct ti81xxfb_stenciling_params {
 __u32               pitch;
 __u32               paddr;
};

NOTE:
pitch must be 16 byte alignment.

USAGE: how to enable the stenciling feature

struct ti81xxfb_stenciling_params stenprms;
struct fb_var_screeninfo var;
struct ti81xxfb_region_params regp;
unsigned long size;
unsigned long temp;

if (ioctl(fd, FBIOGET_VSCREENINFO, &var)) {
 perror("FBIOGET_VSCREENINFO.\n");
 close(fd);
 exit(1);
}

stenprms.pitch = var.xres >> 3;
if (stenprms.pitch & 0xF)
    stenprms.pitch += 0xF - (stenprms.pitch & 0xF);

size = stenprms.pitch * var.yres;

temp = size;
if(ioctl(fd, TIFB_ALLOC, &size)) {
 perror("TIFB_ALLOC.\n");
 close(fd);
 exit(1);
}

stenprms.paddr = size;
size = temp;

virt_addr = (unsigned char *)mmap(0, size,
	(PROT_READ | PROT_WRITE),
	MAP_SHARED, fd, stenprms.paddr);
if ((int)stenbuf == -1) {
 perror("sten MMAP failed.\n");
 close(fd);
 exit(1);
}

if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
 perror("TIFB_GET_PARAMS\n");
 close(fd);
 exit(1);
}

regp.stencilingen = TI81XXFB_FEATURE_ENABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp)< 0) {
 perror("TIFB_SET_PARAMS\n");
 close(fd);
 exit(1);
}

USAGE: how to disable the stenciling feature

struct ti81xxfb_stenciling_params stenprms;
struct ti81xxfb_region_params regp;
unsigned long size;

if (ioctl(fd, FBIOGET_VSCREENINFO, &var)) {
 perror("FBIOGET_VSCREENINFO.\n");
 close(fd);
 exit(1);
}

stenprms.pitch = var.xres >> 3;
if (stenprms.pitch & 0xF)
    stenprms.pitch += 0xF - (stenprms.pitch & 0xF);

size = stenprms.pitch * var.yres;


if (ioctl(fd, TIFB_GET_PARAMS, &regp) < 0) {
 perror("TIFB_GET_PARAMS\n");
 close(fd);
 exit(1);
}

regp.stencilingen = TI81XXFB_FEATURE_DISABLE;
if (ioctl(fd, TIFB_SET_PARAMS, &regp)< 0) {
 perror("TIFB_SET_PARAMS\n");
 close(fd);
 exit(1);
}

munmap(virt_addr, size);
if (ioctl(fd,TIFB_FREE, &stenprms.paddr)) {
 perror(" Failed to free memory.\n");
 close(fd);
 exit(1);
}

OMAPFB Compatible IOCTLS

TI81XX Fbdev driver also supports the following OMAPFB IOCTLs.

OMAPFB_SETUP_MEM
check OMAPFB userguide for the usage

OMAPFB_QUERY_MEM
check OMAPFB userguide for the usage

OMAPFB_SETUP_PLANE
Data Structure:

struct omapfb_plane_info {
	__u32 pos_x;
	__u32 pos_y;
	__u8  enabled;
	__u8  channel_out;
	__u8  mirror;
	__u8  reserved1;
	__u32 out_width;
	__u32 out_height;
	__u32 reserved2[12];
};

Usage:
Only pos_x/pos_y/enabled/out_width/out_height are valid for this ioctl. pos_x/pos_y change the display starting location. enabled bit enable/disable the corresponding graphcis port. out_width/out_height enable the scaling feature of the graphics ports. if both out_width/out_height are set to zero, driver treat is as non-scaling case.

NOTE:
application need make sure the pos_x/pos_y and out_width/out_height do not out of the current display frame boundary.

OMAPFB_QUERY_PLANE

OMAPFB_GET_VRAM_INFO
check OMAPFB userguide for the usage

Data Structures

fb_var_screeninfo
This structure is used to query and set the so-called variable screen information. This allows an application to query or change the display mode, including the color depth, resolution, timing etc.

fb_fix_screeninfo
This structure is used by applications to get the fixed properties of the display, e.g. the start address of the framebuffer memory, framebuffer length etc.

fb_cmap
This structure is used to get/set the color-map for the framebuffer.

V4L2 Driver Interface

Application Interface

TBD.

SYSFS Software Interfaces

User can control all dynamic configuration of DSS core and Fbdev functionality thorugh SYSFS interface.

Frame-buffer Driver sysfs attributes

Following attributes are available for user control.

#
# ls -1 /sys/class/graphics/fb0/
bits_per_pixel
blank
console
cursor
dev
device
mode
modes
name
rotate
pan
phys_addr
rotate
size
state
stride
subsystem
uevent
virt_addr
virtual_size
#

Frame-buffer Driver sysfs attributes

Acronym	Definition
bits_per_pixel	Allows user to control bits per pixel configuration, currently the supported values are 1, 2, 4, 8, 16, 24 and 32. # echo 1/2/4/8/16/24/32 > /sys/class/graphics/fb0/ bits_per_pixel
blank	Allows user to control lcd display blanking configuration independently. # echo 0/1 > /sys/class/graphics/fb0/blank Values only 0(FB_BLANK_UNBLANK) and 4(FB_BLANK_NORMAL) is supported
virtual_size	Allows user to configure xres_virtual and yres_virtual parameters of frame-buffer, # cat /sys/class/graphics/fb0/virtual_size 480,640
virt_addr	Readonly entry, displays virtual address of the frame-buffer memory.
phys_addr	Readonly entry, displays physical address of the frame-buffer memory.

VPSS Library sysfs attributes

VPSS library provides/exports following attributes, which explained in detail below -

#
# ls -1 /sys/devices/platform/vpss/
dvo2
graphics0
graphics1
graphics2
hdmi
modalias
sdvenc
subsystem
system
uevent
#

VPSS Library: system

Config Display Controller

#
# ls -1 /sys/devices/platform/vpss/system/
automode
pllclks
tiedvencs
#

VPSS Library-system: sysfs attributes

Acronym	Definition
automode	allow the vpss driver set the video PLL clock automatically based on the VENC mode echo 0/1 > /sys/devices/platform/vpss/system/automode
pllclks	change the clocks for three video PLLs. automode need be turned off before using this. echo rfclk:54000,dclk:XKHz> /sys/devices/platform/vpss/system/pllclks rfclk only support 54000KHz Clock.
tiedvencs	tie multiple vencs together: hdmi id = 1, dvo2 id = 4, sdvenc id = 8 # echo XX > /sys/devices/platform/vpss/system/tiedvencs where XX: OR value of the venc id.

NOTE:

• By Default, VPSS driver automatically configures the PLL clock based on the display mode setuped by the application for individual VENC without considering the PLL clock is shared or not with other VENC. So it is application's responsiblity to make sure that PLL clock and clock source of VENC are coupled well to supported the desired display mode.

VPSS Library: display

display Output

Arguments	Definition
single	An 10-bit wide, single channel CCIR656 video stream
double	Two 10-bit wide video streams in CCIR656 format. The video data is YUV422 format
triple	Three channel 10-bit video streams with embedded sync SAV/EAV. The video format can be YCbCr 444 or RGB
doublediscrete	Two channel 10-bit video streams with dedicated HS/VS/FID/ACTVID sync signals. The video data format is YUV 422. The first channel is Y; and CbCr are multiplexed on the second channel
triplediscrete	Three channel 10-bit video streams with dedicated HS/VS/FID/ACTVID sync signals. The three channel component digital video can be RGB or YUV 444 format

VPSS Library: dvo2

Configure DVO2 VENC, which is connceted to the external display device,such as LCD panel, HDMI transmitter, etc. This document does not cover any such information.

#
# ls -1 /sys/devices/platform/vpss/dvo2/
clksrc
enabled
mode
output
timing
#

VPSS Library-dvo2: sysfs attributes

Acronym	Definition
clksrc	Set the right clock source for the VENC echo aclk/aclkdiv2/aclkdiff/dclk/dclkdiv2/dclkdiff > /sys/devices/platform/vpss/dvo2/clksrc
enabled	Enable/Disable the VENC. # echo 0/1 > /sys/devices/platform/vpss/dvo2/enabled
mode	Set the right VENC mode:1080p-60/1080p-30/1080i-60/720p-60 are supported(default 1080p-60). # echo 1080p-60/1080p-30/1080i-60/720p-60 > /sys/devices/platform/vpss/dvo2/mode if automode is on, driver will set the PLL accordingly based on the mode, otherwise it is application's responsibility to set the right PLL clock before changing mode.
output	Set the right VENC output echo single/double/doublediscrete/triple/triplediscrete, rgb888/yuv444p/yuv422spuv > /sys/devices/platform/vpss/dvo2/output the first part is the sync mode, the second part is output data format.
timings	Display timing configuration. echo 148500,1920/88/148/44,1080/4/36/5,1 > /sys/devices/platform/vpss/dvo2/timings where: 148500: display pixel clock(KHz) 1920: display width 88: horizontal front porch 148: horizontal back porch 44: horizontal sync width 1080: display height 4: vertical front porch 36: vertical back porch 5: vertical sync width 1: progressive output >sys/devices/platform/vpss/dvo2/timings

VPSS Library: hdmi

Configure the HDMI VENC, which is connected to the On-chip HDMI module.

#
# ls -1 /sys/devices/platform/vpss/hdmi/
clksrc
enabled
mode
output
timing
#

VPSS Library-hdmi: sysfs attributes

Acronym	Definition
clksrc	Set the right clock source for the VENC echo dclk/dclkdiv2/dclkdiff > /sys/devices/platform/vpss/hdmi/clksrc
enabled	Enable/Disable the VENC. # echo 0/1 > /sys/devices/platform/vpss/hdmi/enabled
mode	Set the right VENC mode:1080p-60/1080p-30/1080i-60/1080p-30/720p-60 are supported (default 1080p-60). # echo 1080p-60/1080p-30/1080i-60/1080p-30/720p-60 > /sys/devices/platform/vpss/hdmi/mode if automode is on, driver will set the PLL accordingly based on the mode, otherwise it is application's responsibility to set the right PLL clock before changing mode.
output	Set the right VENC output echo single/double/doublediscrete/triple/triplediscrete, rgb888/yuv444p/yuv422spuv > /sys/devices/platform/vpss/hdmi/output the first part is the sync mode, the second part is output data format.
timings	Display timing configuration. echo 148500,1920/88/148/44,1080/4/36/5,1 > /sys/devices/platform/vpss/hdmi/timings where: 148500: display pixel clock(KHz) 1920: display width 88: horizontal front porch 148: horizontal back porch 44: horizontal sync width 1080: display height 4: vertical front porch 36: vertical back porch 5: vertical sync width 1: progressive output >sys/devices/platform/vpss/dvo2/timings

VPSS Library: sdvenc

Configure the SD VENC(SVIDEO output)

#
# ls -1 /sys/devices/platform/vpss/sdvenc/
clksrc
enabled
mode
output
timing
#

VPSS Library-sdvenc: sysfs attributes

Acronym	Definition
clksrc	not supported
enabled	Enable/Disable the VENC. # echo 0/1 > /sys/devices/platform/vpss/sdvenc/enabled
mode	Set the right VENC mode:ntsc/pal are supported (default ntsc). # echo ntsc/pal > /sys/devices/platform/vpss/sdvenc/mode
output	set the output for SDVENC echo composite/svideo > /sys/devices/platform/vpss/sdvenc/output
timings	Display timing configuration. (Not Supported)

VPSS Library: graphics0/1/2

In all total 3 graphics pipeline are supported on hardware,

#
# ls -1 /sys/devices/platform/vpss/graphics0/
enabled
nodes
#

VPSS Library-graphics0/1/2: sysfs attributes

Acronym	Definition
enabled	User can enable/disable overlay through this entry. # echo 0/1 > /sys/devices/platform/vpss/graphics0/enabled
nodes	User can configure which vencs(hdmi/dvo2/sdvenc) this graphics pipeline connected to. One graphics pipeline can be connected to multiple video compositor as long as those VENCs associated with video compositor are in the same timing. # echo XX:AAA,BBB,CCC > /sys/devices/platform/vpss/graphics0/nodes where XX: 1-4 number of vencs connected, AAA,BBB,CCC: hdmi/dvo2/sdvenc name of the vencs

Miscellaneous Configurations

The default setup/configuration is -

fb0  -- => graphics0 - - => hdmi_venc -> On_Chip_HDMI output

fb1  -- => graphics1 - - => dvo2_venc -> LCD pannel or external display device

fb2  -- => graphics2 - - => sdvenc -> SVIDEO ouput

User can control/configure the various graphics pipeline to different video compositor(VENCs). This section demonstrate/explains the switching of output using above interfaces.

NOTE The connections between fb node and graphics pipeline are fixed and not able to change.

Switching graphics0(fb0) output from HDMI VEVC to DVO2 VENC

Follow the steps below to switch graphics0(fb0)output from HDMI to DVO2 VENC

• Disable graphics 0

#echo 0 > /sys/devices/platform/vpss/graphics0/enabled

• Switch output VENC

# echo 1:dvo2 > /sys/devices/platform/vpss/graphics0/nodes

• Enable graphics 0

#echo 1 > /sys/devices/platform/vpss/graphics0/enabled

NOTE:
Similar steps must be followed for switching other graphcis piple line to different VENC.

Cloning fb0(graphics0) output to both HDMI VENC and DVO2 VENC

Follow below steps to clone GFX overlay output to both HDMI and DVO2 VENC.

NOTE:
Appliation should make sure that both VENC has the same timing.
If one graphics plane is connected to multiple vencs, those vencs must tied.

• Disable graphics0 pipeline

#echo 0 > /sys/devices/platform/vpss/graphics0/enabled

• Disable hdmi VENC

#echo 0 > /sys/devices/platform/vpss/hdmi/enabled

• Disable dvo2 venc

#echo 0 > /sys/devices/platform/vpss/dvo2/enabled

• Tited the VENCs

# echo 5 > /sys/devices/platform/vpss/system/tiedvenc

• Switch the both HDMI and DVO2 VENCs

# echo 2:hdmi,dvo2 > /sys/devices/platform/vpss/graphics0/nodes

• Enable graphics 0 pipeline

#echo 0 > /sys/devices/platform/vpss/graphics0/enabled

NOTE:
The similar stpes must be following when cloning other graphics pipeline to multiple VENCs

Change the mode on HDMI VENC

Follow below steps to change the VENC mode on HDMI, assuming that Graphics0(fb0) is connected to HDMI

• Disable graphics0 pipeline

#echo 0 > /sys/devices/platform/vpss/graphics0/enabled

• Disable hdmi VENC

#echo 0 > /sys/devices/platform/vpss/hdmi/enabled

• Set the new VENC mode

#echo 720p-60 > /sys/devices/platform/vpss/hdmi/mode

• Enable hdmi VENC

#echo 1 > /sys/devices/platform/vpss/hdmi/enabled

• Enable graphics0 pipeline

#echo 1 > /sys/devices/platform/vpss/graphics0/enabled

NOTE:
The similar stpes must be following when change mode of other VENCs.
application should disable all the pipeline connected to the HDMI venc before performing the above steps.

Change display timing on DVO2 VENC

Follow below steps to change the display timing on DVO2 VENC

• Disable DVO2 VENC

#echo 0 > /sys/devices/platform/vpss/dvo2/enabled

• set new display timings

#echo 74250,1280/110/220/40,720/5/20/5,1/3 > /sys/devices/platform/vpss/dvo2/timings

• Enable DVO2 VENC

#echo 1 > /sys/devices/platform/vpss/dvo2/enabled

NOTE:
The similar stpes must be following when change mode of other VENCs.
application should disable all the pipeline connected to the HDMI venc before performing the above steps.

Change the clock source on HDMI VENC

Follow below steps to change the clock source on HDMI VENC.

• Disable hdmi VENC

#echo 0 > /sys/devices/platform/vpss/hdmi/enabled

• Set the new clock source

#echo dclkdiff > /sys/devices/platform/vpss/hdmi/clksrc

• Enable hdmi VENC

#echo 1 > /sys/devices/platform/vpss/hdmi/enabled

NOTE:
The similar stpes must be following when change mode of other VENCs.
application should disable all the pipeline connected to the HDMI venc before performing the above steps.

Change the OUTPUT of HDMI VENC

Follow below steps to change the OUTPUT of HDMI VENC.

• Disable hdmi VENC

#echo 0 > /sys/devices/platform/vpss/hdmi/enabled

• Set the new clock source

#echo double > /sys/devices/platform/vpss/hdmi/output

• Enable hdmi VENC

#echo 1 > /sys/devices/platform/vpss/hdmi/enabled

NOTE:
The similar stpes must be following when change mode of other VENCs.
application should disable all the pipeline connected to the HDMI venc before performing the above steps.

Change Video PLL Clock

Follow below steps to change the video pll clock for the vencs

• Disable the auto mode

$ echo 0 > /sys/devices/platform/vpss/system/automode

• Change the D clock to 148.5MHz

echo dclk:148.5 > /sys/devices/platform/vpss/system/pllclks

Note:
If automode is off, vpss driver does not change PLL clock accordingly when application tunes to different mode.

Driver Configuration

V4L2 video driver

NA

Framebuffer driver

$ make ARCH=arm CROSS_COMPILE=$(PATH_TO_TOOLCHAIN)/bin/arm-none-linux-gnueabi- menuconfig

• Select Device Drivers from the main menu.

...
    ...
    Kernel Features  --->
    Boot options  --->
    CPU Power Management  --->
    Floating point emulation  --->
    Userspace binary formats  --->
    Power management options  --->
[*] Networking support  --->
"   Device Drivers  --->"
    ...
    ...

• Select Graphics support from the menu.

    ...
    ...
    Sonics Silicon Backplane  --->
    Multifunction device drivers  --->
[*] Voltage and Current Regulator Support  --->
<*> Multimedia support  --->
"    Graphics support  --->"
<*> Sound card support  --->
[*] HID Devices  --->
[*] USB support  --->
    ...
    ...

• Select Support for frame buffer devices from the menu.

    ...
    ...
<M> Lowlevel video output switch controls
<*> Support for frame buffer devices  --->
< > E-Ink Broadsheet/Epson S1D13521 controller support
<M> TI81XX Viddeo Processing Subsystem support (EXPERIMENTAL)  --->
[ ] Backlight & LCD device support  --->
    ...
    ...

• Select TI81XX Viddeo Processing Subsystem support (EXPERIMENTAL) from the same menu.

    ...
    ...
<*> Support for frame buffer devices  --->
(50)   VRAM size (MB)
[*]   Debug support
<M> TI81XX frame buffer support (EXPERIMENTAL)  --->

• Configure default VRAM size to the required/expected size of buffer, the default is 50MB.

    ...
    ...
--- Select TI81XX Viddeo Processing Subsystem support (EXPERIMENTAL)
"(50)   VRAM size (MB)"
[*]   Debug support
    ...
    ...

• Enable/Disable Debug function of VPSS

[*]   Debug support

• Select TI81XX frame buffer support (EXPERIMENTAL) from the same menu. Press <ENTER> to enter the corresponding sub-menu.

    ...
    ...
[*]   Debug support for TI81XXFB
"(3)   Number of framebuffers"
    ...
    ...

NOTE: If this value is set as 1, only fb0(graphics0) is availabe in the fbdev.
If this value is set as 2, then graphics0(fb0) and graphics1(fb1) pipeline are available in FBDEV.
If this value is set as 3, all 3 graphics0/1/2(fb0/1/2) pipelines are available the FBDEV interface.

Sample Application Flow

This chapter describes the application flow using the V4l2 and FBDEV drivers.

V4L2-Display Application Flow

TBD.

Fbdev-Display Application Flow

Application for FBDEV driver

Installation Guide

Introduction

This is the TI81XX Linux VPSS and Fbdev Driver user installation guide. This documents the steps to get the VPSS Driver worked up on TI814X based EVM(Simulator is not tested). This documetns deatils the steps in load syslink, M3 BIOS VPSS firmware and VPSS symbol. This driver is verified over the TI814X PSP 04.01.00.02 release, syslink_02_00_00_67_alpha2 release, and HDVPSS 01.00.01.26 Release.

Note: Only the above mentioned version of the components are verified and tested.

Preliminary Work

• Build the Linux Uboot and Kernel following the installation guide of TI814x PSP 04.00.00.02 release.

• As both VPSS and Fbdev driver are built over Syslink linux Kernel driver. It is required to build syslink kernel driver before building VPSS and Fbdev Driver. Please Follow installation guide and release notes of syslink 02.00.00.67_alpha2 to build syslink.ko.

• M3 BIOS VPSS Firmware(c6a814x_hdvpss.xem3/ti814x_hdvpss.xem3) is loaded by the procmgrapp, which is the user space program from syslink. Please follow installatation guide of syslink 02.00.00.67_alpha2 to generate procmgrapp.

• M3 BIOS VPSS Firmware(c6a814x_hdvpss.xem3/ti814x_hdvpss.xem3) is the software running over the VPSS M3 Processor.

Build Linux VPSS and Fbdev Drivers

Since Syslink kernel driver is not part of the TI814x PSP release packages, both VPSS and Fbdev driver are built in the format of module, which are parts of the PSP release. The pre-build uImage inside of PSP release package supports the prebuit VPSS/Fbdev modules.

NOTE: Applications are not required to rebuild the uImage or VPSS/Fbdev module unless VPSS/Fbdev drivers are changed.

• Enable the VPSS and Fbdev in menuconfig

$ make ARCH=arm CROSS_COMPILE=PATH_TO_TOOLCHAIN/bin/arm-none-linux-gnueabi- ti8148_evm_defconfig
$ make ARCH=arm CROSS_COMPILE=PATH_TO_TOOLCHAIN/bin/arm-none-linux-gnueabi- menuconfig

select Device Drivers

   Userspace binary formats  --->
   Power management options  --->
   [*] Networking support  --->
 " Device Drivers  --->    "
   CBUS support  --->
   File systems  --->

select graphics support:

   Multifunction device drivers  --->
   [ ] Voltage and Current Regulator Support  --->
   < > Multimedia support  --->
 " Graphics support  --->     "
   <*> Sound card support  --->
   [*] HID Devices  --->

Select TI81XX Video Processing Subsystem (EXPERIMENTAL)

   < > Fujitsu MB862xx GDC support
   < > E-Ink Broadsheet/Epson S1D13521 controller support
   < > OMAP frame buffer support (EXPERIMENTAL)
 " <M> TI81XX Video Processing Subsystem (EXPERIMENTAL)  ---> "
   [ ] Backlight & LCD device support  --->

Setup the VPSS configuraiton.

 --- TI81XX Video Processing Subsystem (EXPERIMENTAL)
   (50)  VRAM size (MB)
   [*]   Debug support
    <>   TI81XX frame buffer support (EXPERIMENTAL)  --->

select TI81XX frame buffer support (EXPERIMENTAL)

 --- TI81XX Video Processing Subsystem (EXPERIMENTAL)
   (50)  VRAM size (MB)
   [*]   Debug support
   " <M>   TI81XX frame buffer support (EXPERIMENTAL)  ---> "

--- TI81XX frame buffer support (EXPERIMENTAL)
   [*]   Debug support for TI81XX FB
   (3)   Number of framebuffers

• Rebuild the Kernel uImage

$ make ARCH=arm CROSS_COMPILE=PATH_TO_TOOLCHAIN/bin/arm-none-linux-gnueabi- uImage

• Set SYSLINK_ROOT environment variable

 $ export SYSLINK_ROOT=$(PATH_WHERE_SYSLINK_IS_INSTALLED)

• Set IPCDIR environment variable

 $ export IPCDIR=$(PATH_WHERE_IPC_IS_INSTALLED/packages)

• Build module for the drivers

$ make ARCH=arm CROSS_COMPILE=PATH_TO_TOOLCHAIN/bin/arm-none-linux-gnueabi- KBUILD_EXTRA_SYMBOLS=$SYSLINK_ROOT/ti/syslink/utils/hlos/knl/Linux/Module.symvers modules

• vpss.ko will be generated under driver/video/ti81xx/vpss and ti81xxfb.ko will be generated under driver/video/ti81xx/ti81xxfb

Prerequisites

The following files will be available after the above steps have been executed:

1. syslink kernel module file, referred as "syslink.ko"
2. Proc manager user space program, referred as "procmgrapp"
3. VPSS M3 BIOS Firmware binary, referred as "c6a814x_hdvpss.xem3/ti814x_hdvpss.xem3"
4. VPSS module binary, referred as "vpss.ko"
5. fbdev module binary, referred as "ti81xxfb.ko"

Load VPSS and Fbdev Driver Modules

• After seeing Linux booting log at Hyper Terminal or Tera Term, type "root" to log int.

$ cd to the folder where those Prerequisites are stored in the NFS or RamDisk

• Load syslink module

$ insmode syslink.ko

• load VPSS-M3 Firmware

• DM814X Platform

 $ ./procmgrapp 2 ti814x_hdvpss.xem3 0

• C6A814X Platform

$ ./procmgrapp 2 c6a814x_hdvpss.xem3 0

• Load vpss module

• DM814X Platform

$ insmod vpss.ko sbufaddr=0xCFE00000

• C6A814x Platform

& insmod vpss.ko

• Load fbdev module

$ insmod ti81xxfb.ko

• Now Fbdev module is loaded and application can be executed from here.

NOTE:

 HDMI Kernel module is required to view the output from On-Chip HDMI, see next section.
 Application need develop their own software component to support the external display device connected with DVO2 VENC.
 Add debug=1 to enable the debug function of vpss.ko and ti81xxfb.ko
 Application need assign the framebuffer size when loading ti81xxfb.ko if accessing /dev/fb1 and /dev/fb2 nodes
    $ insmod ti81xxfb.ko vram=0:XXM,1:YYM,2:ZZM

Load On-Chip HDMI Module

On-Chip HDMI hardware is controlled through another kernel driver, which should be loaded after vpss.ko is loadded. Please refer TI81XX HDMI user guide for details.

• Load HDMI Module

$ insmod TI81xx_hdmi.ko hdmi_mode=2

NOTE:

• Please note that HDMI module parameter(hdmi_mode) is required to set to appropirate value (2 for 1080P60), failing which the HDMI display will NOT be started. However, applications can start the HDMI after insertion of the module. How to start the HDMI after insertion is not part of FBDEV sample application. Please refer TI81XX HDMI user guide for details.