| dp14 Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

dp14 Documentation

The Xilinx DisplayPort transmitter (DP) driver. This driver supports the Xilinx DisplayPort soft IP core in both transmit/source (TX) and receive/sink (RX) modes of operation.

The Xilinx DisplayPort soft IP supports the following features:

- 1, 2, or 4 lanes.
- A link rate of 1.62, 2.70, or 5.40Gbps per lane.
- 1, 2, or 4 pixel-wide video interfaces.
- RGB and YCbCr color space.
- Up to 16 bits per component.
- Up to 4Kx2K monitor resolution.
- Auto lane rate and width negotiation.
- I2C over a 1Mb/s AUX channel.
- Secondary channel audio support (2 channels).
- 4 independent video multi-streams.

The Xilinx DisplayPort soft IP does not support the following features:

- The automated test feature.
- Audio (3-8 channel).
- FAUX.
- Bridging function.
- MST audio.
- eDP optional features.
- iDP.
- GTC.

DisplayPort overview

A DisplayPort link consists of:

- A unidirectional main link which is used to transport isochronous data streams such as video and audio. The main link may use 1, 2, or 4 lanes at a link rate of 1.62, 2.70, or 5.40Gbps per lane. The link needs to be trained prior to sending streams.
- An auxiliary (AUX) channel is a 1MBps bidirectional channel used for link training, link management, and device control.
- A hot-plug-detect (HPD) signal line is used to determine whether a DisplayPort connection exists between the DisplayPort TX connector and an RX device. It is serves as an interrupt request by the RX device.

Device configuration

The device can be configured in various ways during the FPGA implementation process. Configuration parameters are stored in the xdp_g.c file which is generated when compiling the board support package (BSP). A table is defined where each entry contains configuration information for the DisplayPort instances present in the system. This information includes parameters that are defined in the driver's data/dp.tcl file such as the base address of the memory-mapped device and the maximum number of lanes, maximum link rate, and video interface that the DisplayPort instance supports, among others.

The DisplayPort core may be configured in both transmitter (TX) or receiver (RX) modes of operation. Depending on which mode of operation the hardware is configured for, the set of registers associated with the core will be different.

Driver description

The DisplayPort (DP) driver consists of functions, structures, and definitions: 1) Specific to the DisplayPort TX mode of operation.

- Prefix: XDp_Tx* and XDP_TX_* 2) Specific to the DisplayPort RX mode of operation.
- Prefix: XDp_Rx* and XDP_RX_* 3) Common to both DisplayPort modes of operation.
- Prefix: XDp_* and XDP_*

Driver description: TX mode of operation

The device driver enables higher-level software (e.g., an application) to configure and control a DisplayPort TX soft IP, communicate and control an RX device/sink monitor over the AUX channel, and to initialize and transmit data streams over the main link. This driver follows the DisplayPort 1.2a specification.

This driver implements link layer functionality: a Link Policy Maker (LPM) and a Stream Policy Maker (SPM) as per the DisplayPort 1.2a specification.

- The LPM manages the main link and is responsible for keeping the link synchronized. It will establish a link with a downstream RX device by undergoing a link training sequence which consists of:
  - Clock recovery: The clock needs to be recovered and PLLs need to be locked for all lanes.
  - Channel equalization: All lanes need to achieve channel equalization and and symbol lock, as well as for interlane alignment to take place.
- The SPM manages transportation of an isochronous stream. That is, it will initialize and maintain a video stream, establish a virtual channel to a sink monitor, and transmit the stream.

Using AUX transactions to read/write from/to the sink's DisplayPort Configuration Data (DPCD) address space, the LPM obtains the link capabilities, obtains link configuration and link and sink status, and configures and controls the link and sink. The main link is trained this way.

I2C-over-AUX transactions are used to obtain the sink's Extended Display Identification Data (EDID) which give information on the display capabilities of the monitor. The SPM may use this information to determine what available screen resolutions and video timing are possible.

Driver description: RX mode of operation

The device driver enables higher-level software (e.g., an application) to configure and control a DisplayPort RX soft IP.

This driver gives applications the ability to configure the RX using various settings, handle and issue interrupts, and modify a subset of its DisplayPort Configuration Data (DPCD) fields.

Link training is done automatically by the hardware.

Interrupt processing

For the driver to process interrupts, the application must set up the system's interrupt controller and connect the XDp_InterruptHandler function to service interrupts. When an interrupt occurs, XDp_InterruptHandler will check which mode of operation the DisplayPort core is running in, and will call the appropriate interrupt handler for that core (XDp_TxInterruptHandler or XDp_RxInterruptHandler - local to xdp_intr.c).

Interrupt processing: TX mode of operation

DisplayPort interrupts occur on the HPD signal line when the DisplayPort cable is connected/disconnected or when the RX device sends a pulse. The user hardware design must contain an interrupt controller which the DisplayPort TX instance's interrupt signal is connected to. The user application must enable interrupts in the system and set up the interrupt controller such that the XDp_TxHpdInterruptHandler handler will service DisplayPort interrupts. When the XDp_TxHpdInterruptHandler function is invoked, the handler will identify what type of DisplayPort interrupt has occurred, and will call either the HPD event handler function or the HPD pulse handler function, depending on whether a an HPD event on an HPD pulse event occurred.

The DisplayPort TX's XDP_TX_INTERRUPT_STATUS register indicates the type of interrupt that has occurred, and the XDp_TxInterruptHandler will use this information to decide which handler to call. An HPD event is identified if bit XDP_TX_INTERRUPT_STATUS_HPD_EVENT_MASK is set, and an HPD pulse is identified from the XDP_TX_INTERRUPT_STATUS_HPD_PULSE_DETECTED_MASK bit.

The HPD event and HPD pulse handler may be set up by using the XDp_TxSetCallback function and XDP_TX_HANDLER_HPDEVENT and XDP_TX_HANDLER_HPDPULSE enumerations of the XDp_Tx_HandlerType type.

Interrupt processing: RX mode of operation

The DisplayPort RX driver may generate a pulse on the hot-plug-detect (HPD) signal line using the XDp_RxGenerateHpdInterrupt function. This allows the RX to send an interrupt to the upstream TX device, useful for signaling the TX that it needs to do some checks for changes in downstream devices or a loss of link training.

For RX interrupt handling of HPD events or events that happen internal to the RX, the user hardware design must contain an interrupt controller which the DisplayPort RX instance's interrupt signal is connected to. The user application must enable interrupts in the system and set up the interrupt controller such that the XDp_RxInterruptHandler handler will service interrupts. When the XDp_RxInterruptHandler function is invoked, the handler will identify what type of interrupt has occurred, and will call the appropriate interrupt handler.

The DisplayPort RX's XDP_RX_INTERRUPT_CAUSE register indicates the type of interrupt that has occured, and the XDp_RxInterruptHandler will use this information to decide which handler to call.

The handlers are set up using the XDp_RxSetIntr* functions.

Specific interrupts may be enabled or disabled using the XDp_RxInterruptEnable and XDp_RxInterruptDisable functions.

Multi-stream transport (MST) mode: TX mode of operation

The driver handles MST mode functionality in TX mode of operation, including sideband messaging, topology discovery, virtual channel payload ID table management, and directing streams to different sinks.

MST testing has been done at all possible link rate/lane count/topology/ resolution/color depth combinations with each setting using following values:

- Link rate: 1.62, 2.70, and 5.40Gbps per lane.
- Lane count: 1, 2, and 4 lanes.
- Number of sink displays: 1, 2, 3, and 4 sink displays in both a daisy-chain configuration and in a configuration using a combination of a 1-to-3 hub and daisy-chain. Each stream was using the same resolution.
- Resolutions (60Hz): 640x480, 800x600, 1024x768, 1280x800, 1280x1024, 1360x768, 1400x1050, 1680x1050, 1920x1080, 1920x2160, and 3840x2160.
- Color depths: 18, 24, 30, 36, and 48 bits per pixel.

Multi-stream transport (MST) mode: RX mode of operation

The driver handles MST mode functionality in RX mode of operation. The API function, XDp_RxHandleDownReq, will read a sideband message from the down request registers in the DisplayPort RX core, parse it, arbitrate control for the sideband message type that was requested, format a reply, and send the reply.

The current version of the driver only supports a software representation of a shallow topology - meaning virtual sinks are defined in the user application and assigned to port numbers. The RX acts as a branch connected to multiple sinks, but is not connected to another branch. Sideband messages will then be handled for the targeted downstream sink.

The user application creates the topology using the driver's API functions:

- XDp_RxSetIicMapEntry : Used to specify the I2C contents of a virtual sink.
- XDp_RxSetDpcdMap : Used to specify the DPCD of a virtual sink.
- XDp_RxMstSetPbn : Used to specify the available PBN of a virtual sink.
- XDp_RxMstSetPort : Used to specify how the sink will appear when the an upstream device sends a LINK_ADDRESS sideband request to the RX branch.
- XDp_RxMstSetInputPort : Used to specify the input port.
- XDp_RxMstExposePort : Used to enable the port by exposing it to incoming LINK_ADDRESS sideband requests.

The driver will keep track of the topology in the structures:

- XDp_RxTopology : Stores topology information as a reply to LINK_ADDRESS requests, the virtual channel payload table, and port representations (XDp_RxPort[] type).
- XDp_RxPort : Stores the I2C map (XDp_RxIicMapEntry[] type), DPCD address space (XDp_RxDpcdMap type), PBN information, and whether or not the represented sink is exposed to upstream devices.
- XDp_RxIicMapEntry : Represents data stored at an associated I2C address.
- XDp_RxDpcdMap : Represents the DPCD of an associated port's sink.

Note that the driver uses the topology's XDp_RxPort[] array such that the indices match the port number that attaches the virtual sink to the RX branch.

The following sideband messages are supported:

- CLEAR_PAYLOAD_ID_TABLE
- LINK_ADDRESS
- REMOTE_I2C_READ
- REMOTE_DPCD_READ
- ENUM_PATH_RESOURCES
- ALLOCATE_PAYLOAD Other sideband messages are replied to with NACK.

Audio

The driver in RX mode of operation may received audio info and extension packets. When this happens, if interrupts are enabled, the appropriate handlers will be invoked. Control functions are available for enabling, disabling, and resetting audio in the DisplayPort RX core.

The TX driver does not handle audio. For an example as to how to configure and transmit audio, examples/xdptx_audio_example.c illustrates the required sequence in the TX mode of operation. The user will need to configure the audio source connected to the Displayport TX instance and set up the audio info frame as per user requirements.

Asserts

Asserts are used within all Xilinx drivers to enforce constraints on argument values. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that application developers leave asserts on during development.

Limitations: TX mode of operation

- For MST mode to correctly display, the current version of the driver requires that each of the DisplayPort TX streams be allocated without skipping streams (i.e. assign stream 1, stream 2, and stream 3 - problems were experienced if skipping stream 2 and assigning stream 4 instead). skipping monitors in a daisy chain is OK as long as they are assigned to streams in order.
- In MST mode, the current version of the driver does not support removal of an allocated stream from the virtual channel payload ID table without clearing the entire table.
- Some sideband messages have not been implemented in the current version of the driver for MST mode. Notably, reception of a CONNECTION_STATUS_NOTIFY sideband message.
- The driver does not handle audio. See the audio example in the driver examples directory for the required sequence for enabling audio.

Limitations: RX mode of operation

- Sideband messages that aren't supported as specified above will be NACK'ed.

Note
  For a 5.4Gbps link rate, a high performance 7 series FPGA is required with a speed grade of -2 or -3.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.0   als  01/20/15 Initial release. TX code merged from the dptx driver.
    2.0   als  06/08/15 Added MST functionality to RX. New APIs:
                            XDp_RxHandleDownReq, XDp_RxGetIicMapEntry,
                            XDp_RxSetIicMapEntry, XDp_RxSetDpcdMap,
                            XDp_RxMstExposePort, XDp_RxMstSetPort,
                            XDp_RxMstSetInputPort, XDp_RxMstSetPbn,
                            XDp_RxSetIntrDownReqHandler,
                            XDp_RxSetIntrDownReplyHandler,
                            XDp_RxSetIntrAudioOverHandler,
                            XDp_RxSetIntrPayloadAllocHandler,
                            XDp_RxSetIntrActRxHandler,
                            XDp_RxSetIntrCrcTestHandler
                        Added Intr*Handler and Intr*CallbackRef interrupt-related
                        members to XDp_Rx structure for:
                            DownReq, DownReply, AudioOver, PayloadAlloc, ActRx,
                            CrcTest
                        Added new data structures related to RX MST topology:
                            XDp_RxIicMapEntry, XDp_RxDpcdMap, XDp_RxPort,
                            XDp_RxTopology
                        Renamed XDp_Tx* to XDp_* to reflect commonality with RX
                        for:
                            XDp_TxSbMsgLinkAddressReplyPortDetail
                            XDp_TxSbMsgLinkAddressReplyDeviceInfo
                        GUID type change for ease of use:
                            'u32 Guid[4]' changed to 'u8 Guid[16]'
                        Added handlers and setter functions for HDCP and unplug
                        events.
                        Added callbacks for lane count changes, link rate changes
                        and pre-emphasis + voltage swing adjust requests.
    3.0   als  10/07/15 Added MSA callback.
    4.0   als  12/08/15 Added link rate and lane count validity check APIs:
                            XDp_IsLinkRateValid
                            XDp_IsLaneCountValid
                        XDp_TxAllocatePayloadVcIdTable now takes an additional
                        argument (StartTs, the starting timeslot).
                        Added RX API to get color depth of a given stream.
                            XDp_RxGetBpc
                        Added RX API to get color component format of a stream.
                            XDp_RxGetColorComponent
                        Added RX API to set end of line reset as appropriate.
                            XDp_RxSetLineReset
                        Added RX MST API to allocate payload from ISR:
                            XDp_RxAllocatePayloadStream
    5.0   als  05/16/16 Added APIs to set color encoding scheme.
    5.1   als  08/12/16 Updates to support 64-bit base addresses.
          ms   01/23/17 Added xil_printf statement in main function for all
                        examples to ensure that "Successfully ran" and "Failed"
                        strings are available in all examples. This is a fix
                        for CR-965028.
          ms   03/17/17 Modified readme.txt file in examples folder for doxygen
                        generation.
    5.3   ms   04/18/17 Modified tcl file to add suffix U for all macros
                        definitions of dp in xparameters.h
    6.0   tu   09/08/17 Added two interrupt handler that addresses driver's
                        internal callback function of application
                        DrvHpdEventHandler and DrvHpdPulseHandler
    6.0   tu   09/08/17 Added three interrupt handler that addresses callback
                        function of driver
    6.0   jb   02/19/19 Added Intr*Handler and Intr*CallbackRef interrupt-related
                        members to XDp_Rx structure for:
                                    Hdcp22AkeInitWr, Hdcp22AkeNoStoredKmWr,
                                    Hdcp22AkeStoredWr, Hdcp22LcInitWr,
                                    Hdcp22SkeSendEksWr, Hdcp22LinkIntegrityFail,
                                    Hdcp22HprimeReadDone, Hdcp22PairingReadDone
                            Added new HDCP22 functions:
                                    XDp_GenerateCpIrq,
                                    XDp_EnableDisableHdcp22AuxDeffers
    7.4   rg   09/01/20 Added XDp_TxColorimetryVsc API for reading sink device
                        capability for receiving colorimetry information through
                        VSC SDP packets.
    7.4   rg   09/26/20 Added support yuv420 color format.