PDK/PDK VPS Display Driver User Guide

Display Drivers

Introduction

Display drivers takes the video buffer from the application and displays the video on the video encoder (VENC) at specified frame rate and resolution.

Display driver follows the FVID2 interface for the applications:

• Supports only one handle per instance. This means that a specific driver could be opened only once.
• Supports queuing mechanism. Application may queue multiple buffers with the driver and the driver displays the buffers one after the another sequentially in order the buffers are queued.
• Multiple buffer submission per queue/dequeue is not supported. Supports only one request per queue/dequeue operation. In order to queue/dequeue multiple buffers, the application has to call queue/dequeue multiple times.
• Queue and Dequeue FVID2 calls for all the display drivers are non blocking.
• Display driver calls the application call back function on displaying the application buffer. Application could dequeue the buffers by explicitly calling dequeue function after the callback.
• Once the display operation is started, the display driver always retains the last buffer and displays the same buffer continuously till the application gives a new buffer to display.
• Any dequeue call to get back the last buffer when display is in progress will return error. Application should stop display operation before it could dequeue the last buffer from the driver.
• When operating in interlaced mode, the display driver always takes both the field in a queue/dequeue call.
• Before the display operation is started, the application has to queue a minimum set of buffers. This operation is called priming.
• The minimum of number buffers required could defer from driver to driver. Generally this is equal to 1 buffer and the recommended value is equal to 3 buffers. Refer the driver specific documentation for the exact value.

Sample Application Flow

Following diagrams show the typical application flows for the display driver:

Sample Application Flow

Display Controller Driver

Introduction

This chapter describes the hardware overview, application software interfaces for Display Controller driver. The features and limitations of current driver implementation are listed in subsequent sections.

Important
The features supported or NOT supported in any release of the driver may vary from one HDVPSS driver release to another. See respective release notes for exact release specific details.

Features Supported

• Connecting pipelines, Overlay Managers(LCD1,LCD2,LCD3,TV),display ports(DPI1,DPI2,DPI3) modules statically and dynamically (but not at run time, i.e. after display is started)
• All VENCs(LCD1,LCD2,LCD3) support upto 720p60, 1080p30, 1080i60 and 1080p60 mode
• Supports FVID2 interface

Features Not Supported

• Run time changing of Overlay manager parameters once it has started

Hardware Overview

Below figures shows the complete DSS Hardware. The circled part in the figure shows the modules which are controlled by display controller.

Overview - TDA2xx/TDA2Px/TDA2Ex

Display Controller - TDA2SEDx

As shown in the figure, display controller driver controls configuration of paths i.e connnections of pipelines(VID1,VID2,VId3,GFX), Overlay managers(LCD1, LCD2,LCD3) and Display ports(DPI1,DPi2,DPI3). It also configures the timing of overlay managers.

It provides APIs to the application to configure these paths and to set the different frame rates and resolutions in the VENC.

The display controller will provide necessary information to the display driver about the resolution and frame rate that it has to operate. This is abstracted from the application.

Overview - TDA3xx

Figure shows a block diagram with the DSS module within the device.

The supported display interfaces are:

• One parallel CMOS output, which can be used for MIPI® DPI 2.0, or BT-656 or BT-1120.
• One TV output, which is connected to the internal Video Encoder module (VENC). The VENC drives a single video digital-to-analog converter (SD_DAC) supporting composite video mode.

Software Application Interfaces

Display controller driver is not the streaming driver. Its used to control the specific part of the display controller as shown in above figure. The driver operation can be partitioned into the below phases:

• System Init Phase: Here the driver sub-system is initialized
• Create Phase: Here the driver handle is created or instantiated
• Run Phase: NA
• Delete Phase: Here the driver handle or instance is deallocated
• System De-init Phase: Here the driver sub-system is de-initialized

The subsequent sections describe each phase in detail.

Note

Details of the structure, enumerations and #defines mentioned in the section can be found in PDK API guide

System Init Phase

The display driver sub-system initialization happens as part of overall HDVPSS system init. This API must be the the first API call before making any other FVID2 calls. Below section lists all the APIs which are part of the System Init phase.

FVID2 Init

Int32 FVID2_init(Ptr args);

args - NULL currently not used.

Create Phase

In this phase user application opens or creates a driver instance. Any number of instances can be created for the display controller. Each instance works on the same central hardware block show above. Concurrency issues between the different handles is taken care by the display controller driver. User can pass number of parameters to the drivers during create phase like configuration of the path, settings of the venc etc, either through the create parameters or through the control commands.

FVID2 Create

This API is used to open the display controller driver. This is a blocking call and it returns the handle which is to be used in subsequent call to this driver.

FVID2_Handle FVID2_create(UInt32 drvId,
                          UInt32 instanceId,
                          Ptr createArgs,
                          Ptr createStatusArgs,
                          const FVID2_CbParams *cbParams);

drvId - FVID2_VPS_DCTRL_DRV Display Controller Driver ID. Use this ID to open display controller driver. Details can be found in UserGuide

instanceId - VPS_DCTRL_INST_0 Instance 0 of the display controller.

createArgs - Pointer to Vps_DcCreateConfig structure containing valid create params. This parameter can be NULL.

createStatusArgs - Pointer to UInt32 return value where the driver returns the actual return code for create function. This parameter should not be NULL.

cbParams - Since there is no callback from the display controller, this parameters should be set to NULL.

FVID2 Control - Set Config

This is used to issue a control command to the driver. IOCTL_VPS_DCTRL_SET_CONFIG ioctl is used to set the entire display configuration in one shot. This ioctl takes pointer to the structure Vps_DctrlConfig. This structure takes list of edges connecting nodes and configures display paths. It first validates these paths and then configures VPS for the display paths. It configures all display controller modules.

Important
This API should not be called after the display operation is started.

Int32 FVID2_control(FVID2_Handle handle,
                    UInt32 cmd,
                    Ptr cmdArgs,
                    Ptr cmdStatusArgs);

handle - Driver handle returned by create function call. This parameter should not be NULL.

cmd - IOCTL_VPS_DCTRL_SET_CONFIG ioctl.

cmdArgs - Pointer to Vps_DctrlConfig structure containing Display Controller configuration. This parameter should not be NULL.

cmdStatusArgs - Not used currently. This parameter should be set to NULL.

FVID2 Control - Clear Config

This is used to issue a control command to the driver. IOCTL_VPS_DCTRL_CLEAR_CONFIG ioctl is used to clear the entire display configuration in one shot. This ioctl takes pointer to the structure Vps_DctrlConfig. This structure takes list of edges connecting nodes and disables path between these nodes. It does not validate the edge list. It simply disables edge connecting nodes. For the vencs, it checks for the validity and then disables the VENC of there are no errors.

Important
This API should not be called after the display operation is started.

Int32 FVID2_control(FVID2_Handle handle,
		    UInt32 cmd,
		    Ptr cmdArgs,
		    Ptr cmdStatusArgs);

handle - Driver handle returned by create function call. This parameter should not be NULL.

cmd - IOCTL_VPS_DCTRL_CLEAR_CONFIG ioctl.

cmdArgs - Pointer to Vps_DctrlConfig structure containing Display Controller configuration. This parameter should not be NULL.

cmdStatusArgs - Not used currently. This parameter should be set to NULL.

Delete Phase

In this phase FVID2 delete API is called to close the driver instance. Remember to clear the configuration before closing the driver instance.

FVID2 Delete

This API is used to close the display controller driver. This is a blocking call and returns after closing the handle.

Int32 FVID2_delete(FVID2_Handle handle, Ptr deleteArgs);

handle - Driver handle returned by create function call. This parameter should not be NULL.

deleteArgs - Not used currently. This parameter should be set to NULL.

System De-Init Phase

FVID2 de-Init

Display controller is de-initialized as a part of this phase. Here all resources acquired during system initialization are freed. Make sure all driver instances deleted before calling this API. Display sub-system de-init happens as part of overall FVID2 system de-init. Typically this is done during system shutdown.

Int32 FVID2_deInit(Ptr args);

args - Not used

Display Driver

Introduction

This chapter describes the hardware overview, application software interfaces, typical application flow and sample application usage for display driver involving bypass paths and secondary path.

Important

Software Application Interfaces

The driver operation can be partitioned into the below phases:

• System Init Phase: Here the driver sub-system is initialized
• Create Phase: Here the driver handle is created or instantiated
• Run Phase: Here the driver is used to capture, process and release frames continuously
• Delete Phase: Here the driver handle or instance is deallocated
• System De-init Phase: Here the driver sub-system is de-initialized

The subsequent sections describe each phase in detail.

Note

Details of the structure, enumerations and #defines mentioned in the section can be found in PDK API guide

System Init Phase

The display driver sub-system initialization happens as part of overall HDVPSS system init. This API must be the the first API call before making any other FVID2 calls. Below section lists all the APIs which are part of the System Init phase.

FVID2 Init

Int32 FVID2_init(Ptr args);

args - NULL currently not used.

Create Phase

In this phase user application opens or creates a driver instance. Up to VPS_DISPLAY_INST_MAX (defined in vps_display.h ) driver instances can be opened by a user. Each driver instance is associated with one of the pipeline(video/ Graphics) paths as listed in detail in PDK API guide.

User can pass number of parameters to the drivers during create phase like setting the format, setting the multi window configuration etc. These all configuration can be either done through standard FVID2 APIs or driver exported control commands or through driver create parameters itself.

FVID2 Create

This API is used to open the driver. This is a blocking call and it returns the handle which is to be used in subsequent call to this driver. This cannot be called from ISR context.

FVID2_Handle FVID2_create(UInt32 drvId,
                          UInt32 instanceId,
			  Ptr createArgs,
			  Ptr createStatusArgs,
			  const FVID2_CbParams *cbParams);

drvId - FVID2_VPS_DISP_DRV to open the display driver.

instanceId - VPS_DISP_INST_DSS_VID1 macro to open Video 1 path display driver or pass VPS_DISP_INST_DSS_VID2 macro to open Video 2 path display driver or VPS_DISP_INST_DSS_VID3 macro to open Video 3 path display driver or VPS_DISP_INST_DSS_GFX1 macro to open Graphics path display driver.

createArgs - Pointer to Vps_DispCreateParams structure containing valid create params. This parameter should not be NULL.

createStatusArgs - Pointer to Vps_DispCreateStatus structure containing the return value of create function and other driver information. This parameter could be NULL if application don't want the create status information.

cbParams - Pointer to FVID2_CbParams structure containing FVID2 callback parameters. This parameter should not be NULL. But the callback function pointers inside this structure is optional.

FVID2_control

This API is used to expose the different control commands to the application depending upon the specific driver.

Int32 FVID2_control(FVID2_Handle handle,
                    UInt32 cmd,
                    Ptr cmdArgs,
                    Ptr cmdStatusArgs);

FVID2 Control - Set Dss params

IOCTL_VPS_DISP_SET_DSS_PARAMS ioctl is used to Set the all parameters related to DSS. This is a blocking call.

Int32 FVID2_control(FVID2_Handle handle,
                    UInt32 cmd,
                    Ptr cmdArgs,
                    Ptr cmdStatusArgs);

handle - Driver handle returned by create function call. This parameter should not be NULL.

cmd - IOCTL_VPS_DISP_SET_DSS_PARAMS ioctl.

cmdArgs - Pointer to Vps_DispDssParams.

cmdStatusArgs - This Parameter can be NULL.

Run Phase

This phase is used to start or stop the already started display driver. This is also used to exchange the displayed buffers and the fresh buffers between the driver and applications.

FVID2 Start

This API is used by the application to start the display operation. This is a blocking call and returns after starting the display operation. Before starting the display operation, the application has to prime at least 1 buffer with the driver using queue API. Typically 3 buffers are used: 1 used by application and 2 buffers are queued with the driver at any given time. This cannot be called from ISR context.

Int32 FVID2_start(FVID2_Handle handle, Ptr cmdArgs);

handle - Driver handle returned by create function call. This parameter should not be NULL.

cmdArgs - Not used currently. This parameter should be set to NULL.

FVID2 Stop

This API is used by the application to stop the display operation. This is a blocking call and returns after stopping the display operation. This cannot be called from ISR context.

Int32 FVID2_stop(FVID2_Handle handle, Ptr cmdArgs);

handle - Driver handle returned by create function call. This parameter should not be NULL.

cmdArgs - Not used currently. This parameter should be set to NULL.

FVID2 Queue

This API is used to submit a video buffer to the driver for display operation. This is a non-blocking call and could be called from task or ISR context. Once the buffer is queued the application loses ownership of the buffer and is not suppose to modify or use the buffer.

Int32 FVID2_queue(FVID2_Handle handle,
                  FVID2_FrameList *frameList,
                  UInt32 streamId);

handle - Driver handle returned by create function call. This parameter should not be NULL.

frameList - Pointer to FVID2_FrameList structure containing the pointer to the FVID2 frames. This parameter should not be NULL. In normal display operation, the number of frames passed using this call is one.

streamId - Not used currently. This parameter should be set to 0.

FVID2 Dequeue

This API is used by the application to get ownership of a displayed video buffer from the display driver. This is a non-blocking call and could be called from task or ISR context.

Int32 FVID2_dequeue(FVID2_Handle handle,
                    FVID2_FrameList *frameList,
                    UInt32 streamId,
                    UInt32 timeout);

handle - Driver handle returned by create function call. This parameter should not be NULL.

frameList - Pointer to FVID2_FrameList structure where the driver will copy the displayed FVID2 frames. This parameter should not be NULL. In normal display operation, the number of frames returned using this call is one. When multiple window configuration is set, this frame list returns the frames of all the multiple window buffers of the current layout.

streamId - Not used currently. This parameter should be set to 0.

timeout - Not used currently as only non-blocking queue/dequeue operation is supported. This parameter should be set to FVID2_TIMEOUT_NONE.

Delete Phase

In this phase FVID2 delete API is called to close the driver instance. All the resources are freed. Make sure display is stopped using FVID2_stop() before deleting a display instance. Once the driver is instance is closed it can be opened again with new configuration.

FVID2 Delete

This API is used to close the display driver. This is a blocking call and returns after closing the handle. This cannot be called from ISR context.

Note
Closing the driver will implicitly stop the display if stop IOCTl is not called by the application. This will also delete all the created layouts.

Int32 FVID2_delete(FVID2_Handle handle, Ptr deleteArgs);

handle - Driver handle returned by create function call. This parameter should not be NULL.

deleteArgs - Not used currently. This parameter should be set to NULL.

System De-Init Phase

FVID2 de-Init

In this phase display driver is de-initialized. Here all resources acquired during system initialization are free'ed. Make sure all driver instances deleted before calling this API. Display sub-system de-init happens as part of overall FVID2 system de-init. Typically this is done during system shutdown.

Int32 FVID2_deInit(Ptr args);

args - Not used

Sample Application

Dss Display

This example illustrates the display streaming feature of video and graphics Path displaying buffers on LCD and TV outputs.

• Load vps_examples_displayDss_ipu1_0_release.xem4 executable file found at $(rel_folder)\packages\ti\binary\vps_examples_displayDss\bin\$platform\exampleName_core_release.xem4 to DSS M4 debug session
• Run the application and it will halt for the user to provide the Option to run.
• Then it will halt for the user to load the input frames.
• Using loadRaw command in script console of CCS, load 4 frames of 800 x 480 YUYV interleaved data to the printed location. (Ignore "syntax error" if it appears during loading)

loadRaw(<Address Location>, 0, " < File Path > ", 32, false);

• Enter 1 on the console when application stops at after loading of the frames is completed.

Input a numeric key and press enter after loading...

• This will display the Buffers one after the other on LCD/TV.
• Application will stop after displaying TOTAL_LOOP_COUNT frames
• Configuration Options: To change the number of frames to display, change the macro TOTAL_LOOP_COUNT to any desired value greater than 2.
• Configuration Options: Change BUFFER_WIDTH and BUFFER_HEIGHT macro according to the input buffer dimension. The application will automatically change the window sizes according to the buffer size and pitch.
• Option 3 and 4 has features of blending and transparency color keying. In option 3 gfx layer is blended with video layer.In option 4 two video planes(side by side) are blended with graphics layer on top of it.
• Option 5 showcases use of all four pipelines(three video and one graphics), first video pipeline output is of full screen, the other two pipeline outputs are of small size window. These three video pipelines are blended with full size graphics layer.

DSS Bypass Mode

DSS (Display sub system) in Tda2xx/Tda2px/Tda2ex/Tda3xx can be configured to operate in bypass/Transparent mode. It means that there will be no processing on the input data. It will be sent out on the DPI output as is.

This mode can be used to transfer data from DMA to other modules via DPI port.

The IOCTL call should be made with following parameters.

IOCTL_VPS_DISP_SET_DSS_PARAMS

• dispDssPrms.inFmt.width = Should be same as Overlay width.
• dispDssPrms.inFmt.height = Should be same as Overlay Height.
• dispDssPrms.inFmt.pitch[0] = (dispDssPrms.inFmt.width * 3)
• dispDssPrms.inFmt.dataFormat = FVID2_DF_BGR24_888
• dispDssPrms.inFmt.scanFormat = FVID2_SF_PROGRESSIVE
• dispDssPrms.tarWidth = dispDssPrms.inFmt.width;
• dispDssPrms.tarHeight = dispDssPrms.inFmt.height;
• dispDssPrms.posX = 0;
• dispDssPrms.posY = 0;
• dispDssPrms.memType = VPS_VPDMA_MT_NONTILEDMEM;
• dispDssPrms.vidCfg->pipeCfg.repliEnable = FALSE;
• dispDssPrms.vidCfg->pipeCfg.scEnable = FALSE;
• dispDssPrms.vidCfg->pipeCfg.cscFullRngEnable = VPS_DSS_DISPC_CSC_FULL;
• dispDssPrms.vidCfg->pipeCfg.chromaSampling = 0;

• dispDssPrms.vidCfg->pipeCfg.vc1Cfg->enable = FALSE;
• dispDssPrms.vidCfg->pipeCfg.vc1Cfg->rangeY = 0;
• dispDssPrms.vidCfg->pipeCfg.vc1Cfg->rangeUV = 0;

• dispDssPrms.vidCfg->pipeCfg.advDmaCfg = NULL;
• dispDssPrms.vidCfg->pipeCfg.gfxCfg = NULL;

IOCTL_VPS_DCTRL_SET_CONFIG in case of Display Controller driver

• mInfo = &dctrlCfg->vencInfo.modeInfo[0U].mInfo;
• mInfo->standard = FVID2_STD_CUSTOM;
• mInfo->width = overlay Width; /*Same width should be set for dispDssPrms.inFmt.width */
• mInfo->height = overlay height; /*Same height should be set for dispDssPrms.inFmt.height */
• mInfo->scanFormat = FVID2_SF_PROGRESSIVE;

The timing like hsynclength, vsync length and porches should be as per the width and height.

In IOCTL_VPS_DCTRL_SET_OVLY_PARAMS IOCTL.

Both alpha blending and color key should be disabled.

• panelCfg->alphaBlenderEnable = 0;
• panelCfg->colorKeyEnable = 0;

DSS Region Based Writeback

Region based writeback feature is available in TDA3xx. The driver does the region based writeback on TDA3xx when the Vps_CaptDssWbParams.inFmt.width (This should be overlay width) and Vps_CaptDssWbParams.inCropCfg.cropWidth are not same or Vps_CaptDssWbParams.inFmt.height (This should be overlay height) and Vps_CaptDssWbParams.inCropCfg.cropHeight are not same. By specifying the above values only part of the overlay can be written back. The position of the region to be written back can be specified by Vps_CaptDssWbParams.inCropCfg.cropStartX and Vps_CaptDssWbParams.inCropCfg.cropStartY

Limitations of Region Based Writeback

There are some of the hardware constraints listed below while using the region based writeback. The DSS writeback registers are shadowed just like the other pipes, but shadow to work copy happens at the WB Sync Event (At the beginning of active display) and RB Events (At the end ot the writeback region), they are as shown in below Image

DSS Region based Writeback Events

The register DISPC_WB_ATTRIBUTES2->REGION_BASED determines whether the writeback is region based or full frame. Further DSS Hw expects Region based bit to be set to 1 in the work register only between WB Sync Event and RB Event. And it should be set to 0 after RB Event to Next WB Sync Event.
This puts the constraint on software to write 0 to region based bit in WB Sync ISR and write 1 in RB Event ISR in every frame (This is handled by the driver internally), and these ISRs should be serviced before the next event happens. Below are the issues could happen if the ISRs are delayed

• DSS Hw might write extra full frame data insted of only the region.
• DSS Hw might skip writeback for few frames.

Driver will handle these scenarios internally and return the buffers to application only when the proper frame is captured.

Care abouts by application

• Allocate the buffer for full frame size but use the pixel data corresponding to only the region width and height.
• The writeback framerate as seen from application might be less than the display frame rate.
• the ISR priorities should be adjusted to make sure the DSS ISRs (WB Sync and RB Event) are serviced before next event from hardware happens so that frame drop is less. Time to service WB Sync ISR is from start of active video to last line of the region to be captured and time to service RB Event ISR is from last line of region to be captured to next Vsync. Based on worst case ISR latency and the time taken for each line of display the safe region to capture should be derived.