ZynqMP DisplayPort Linux driver

This page gives an overview of the DisplayPort driver which is available as part of the ZynqMP Linux distribution. The main driver is based on the Linux DRM KMS display subsystem. Some additional drivers are based on other subsystem: DMA engine driver for DPDMA and ALSA driver for audio support.

Paths, files, links and documentation on this page are given relative to the Linux kernel source tree.


Table of Contents


HW IP features

Features in bold are supported by the driver
  • Based on the VESA DisplayPort V.12a source-only specification.
  • Video support for the following:
    ° Resolution up to 4K x 2K at 30Fps.
    ° Y-only, YCbCr444, YCbCr422, YCbCr420, and RGB video formats.
    ° 6, 8, 10, or 12 bits per color components.
    ° Progressive video.
    ° A 36-bit native video input interface to capture live video.
    ° Non-live video from frame buffers using internal DPDMA.
  • Graphics support for the following:
    ° Non-live graphics from the frame buffer.
    ° 36-bit native video interface along with an 8-bit alpha channel to capture live graphics.
    ° 2-plane, on-the-fly rendering of video and graphics.
    ° Chroma upsampling.
    ° Chroma downsampling.
    ° Color space conversion from YCbCr to RGB and vice versa.
    ° Video blending.
    ° Chroma keying.
  • Audio support for the following:
    ° Up to two audio channels.
    ° Sample size of up to 24 bits.
    ° Maximum sample rate of 48 KHz.
    ° Live 24-bit audio from the PL.
    ° Non-live 16-bit audio from the frame buffer.
  • Audio mixer and volume control.
    ° Mixing of two audio streams of the same sampling rate and channel count.
    ° Provides gain control for audio streams.
  • Streaming A/V output back to the PL.
  • Includes a system time clock (STC) that is compliant with the ISO/IEC 13818-1 standard. Provides time stamping of the A/V presentation unit.

Missing Features, Known Issues and Limitations

Missing Features

This section summarizes the known issues and missing features (or experimental)
  • Live support is experimental feature
    • Live input is supported as experimental (live input)
    • Live output hasn't been fully verified
  • Pixel formats
    • 12 bit YUV formats are not supported
  • Interop

Limitation

  • Both layers (drm planes) should be in the same size. Otherwise, if the requested size is different, the driver returns an error. This is hardware limitation.

Note

The driver implementation has switched to the new driver in 2018.1, which supports new software features with more modular / scalable structure. The behavior of some APIs may be different, as well as the driver name from "xilinx_drm" to "xlnx".

Kernel Configuration


The dedicated DMA engine for DisplayPort should be enabled.
CONFIG_XILINX_DPDMA=y
The following config options are optional and required for audio support.
CONFIG_SOUND=y
CONFIG_SND=y
CONFIG_SND_SOC=y
CONFIG_SND_SOC_XILINX_DP=y
The driver, as some other multimedia drivers, needs CMA chunk. The following config options are recommended.
CONFIG_CMA=y
CONFIG_DMA_CMA=y
CONFIG_CMA_SIZE_MBYTES=256

The below is for new driver (>= 2018.1)
The following config options should be enabled in order to build the DisplayPort driver
CONFIG_DRM_XLNX=y
CONFIG_DRM_XLNX_BRIDGE=y
CONFIG_DRM_XLNX_BRIDGE_DEBUG_FS=y
CONFIG_DRM_ZYNQMP_DPSUB=y

The below is for old driver (< 2018.1)
The following config options should be enabled in order to build the DisplayPort driver
CONFIG_DRM=y
CONFIG_DRM_XILINX=y
CONFIG_DRM_XILINX_DP=y
CONFIG_DRM_XILINX_DP_SUB=y

Devicetree

The below is for new driver (>= 2018.1)
The snippet:
- zynqmp-display: zynqmp-display
The dt binding doc: Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.txt
- xlnx,zynqmp-dpsub.txt

The below is for old driver (< 2018.1)
Device tree nodes required are as below in "arch/arm64/boot/dts/xilinx/zynqmp.dtsi"
- Xilinx drm: xilinx drm node
- dp: dp
- dp subsystem: dp_sub
- dpdma: dpdma
For audio support
- alsa nodes: card, codec, pcm

For more details, Please refer to "Documentation/devicetree/bindings/drm/xilinx"
- dp.txt
- dp_sub.txt
- xilinx_drm.txt

Implementation

Power Management

The display pipeline is enabled and disabled upon the monitor HPD (hot plug detect) events. When there's disconnect event the DRM framework disables the pipeline. For the connect event the pipeline is enabled. The detect callback below from DP driver reports the connection status. This management is called DPMS (Display Power Management Signaling).

Upon the event, the DRM framework enables and disables the pipeline if possible. The below, the drm_kms_helper_hotplug_event() will disable or enable the fb console based on the event type.
The event also goes into userspace through sysfs, so that any actively running application (ex, Xorg) can handle the event properly
The userspace can handle the event. The below is the example of handling for Xorg,
https://github.com/Xilinx/meta-petalinux/blob/4e84d60865bf505d1ea425f3e5c84e37bf8f7455/recipes-core/udev/eudev/monitor-hotplug.sh
At the driver level, when the pipeline is enabled / disabled, whatever necessary are notified (pmu fw) and enabled / disabled accordingly, including clock, dma, phy, and DP itself. Below is the enabling / disabling of display components such as clock, dma, and the IP. And enabling / disabling the encoder involves phy, connected monitor, transmitter,,,.
The system level suspend and resume is handled at the upper level, called xlnx drv, which will shut down or turn on the entire pipeline.

Applications

This section describes the example commands in drm or Xorg environment.

DRM

modetest is the test application available from libdrm: https://cgit.freedesktop.org/mesa/drm/tree/tests/modetest.
For information on boot args see Xilinx DRM KMS related bootargs.

The below is the help from the application. Please note, some arguments / commands changes.

Running the modetest with driver id string lists available modes / properties from the connected monitor. Please note the IDs are not fixed and changes due to framework updates or so.
  • Available modes under connector@38
  • Current framebuffer set to crtc@36
  • Available planes (layers): plane@34 and plane@35
  • List of supported formats for each plane
  • Alpha properties of plane@35

Please note, the driver name has been changed to xlnx for release >= 2018.1. For release <= 2017.4, the ID is 'xilinx_drm'. Alternatively, the bus id can be used with '-D' option. The bus id is the device specific id to differentiate between devices under same drm driver. The bus id can be found by cat /sys/kerne/debug/dri/0/name. The bus id for ZynqMP DP is 'fd4a0000.zynqmp-display'. The value should be set differently for each device.


To set the test pattern on the crtc, 'RG16' can be replaced with any other format from primary plane (plane@35).
To enable the overlay plane, use '-P' with arguments below. 'YUYV' can be replaced with any other format from overlay plane (plane@34).
plane@34 wouldn't be visible as plane@35 is always on top. Set the alpha property using '-w'.
The modetest also demonstrates the page flipping with '-v' option. The command flips two buffers and prints the framerate.
Enabling The Zynq MPSoC DisplayPort Controller internal TPG via modetest.
NOTE: that the TPG command below should only be used before running modetest -P.

Live Input


The live input can be configured through Xilinx bridge interface (https://github.com/xilinx//linux-xlnx/blob/xilinx-v2018.2/drivers/gpu/drm/xlnx/xlnx_bridge.h#L65), which is the kernel level APIs. The APIs can be used directly by the client driver, ex V4L TPG driver. The interface is also available through debugfs for userspace application to control, as this feature is experimental stage as of 2018.2 release.

The live input requires the clock and timing to be generated from PL, so that such requirement should be reflected in the PL design. The clock should be specified in the devicetree, with 'dp_live_video_in_clk' (http://github.com/xilinx/linux-xlnx/blob/xilinx-v2018.2/Documentation/devicetree/bindings/display/xlnx/xlnx%2Czynqmp-dpsub.txt#L20). The driver will automatically switches to PL clock when switching to live input. The DT binding doc describes as below.
As an example, if the si570 is connected to DP live clock through FPGA logic, the DT change is as below.
There are two live inputs available, video and graphics, and two debugfs entries are available.
Some operations can be done through debugfs: enable / disable / set_input:
http://github.com/xilinx/linux-xlnx/blob/xilinx-v2018.2/drivers/gpu/drm/xlnx/xlnx_bridge.c#L310. But please note, debugfs is not treated as stable ABI, so any application shouldn't rely on specific ABI, meaning it may change from one version to another.
The below command will set video layer to use live input.
For 'set_input', 1st arg = width, 2nd arg = height, 3rd arg = media bus format (from media-bus-format.h). 0x100e maps to RGB24 (
http://github.com/xilinx/linux-xlnx/blob/xilinx-v2018.2/include/uapi/linux/media-bus-format.h#L49)
This assumes that the logic connected to live input (ex, TPG / VTC) are already configured prior to enable command. Then the live input can be disabled as below.

ALSA

The "aplay" is an ALSA (Linux audio/sound subsystem) example and demonstrates the audio play. The command sends audio data on specific pcm channel which is audible at DPout.

Xorg

Xorg automatically launches at boot up. If needed to run manually,
Xorg clients look for the env variable to find corresponding server. Thus export before running clients from serial console.
Run window manager and desktop session (matchbox example).
'xrandr' is to display and change the resolutions.

'xset' changes some setting. Change of power states can be done as below.

Disable Xorg Timeouts


The default settings for Xorg may cause the screen to go black after a 10 minute timeout.  The user can disable these in their xorg.conf file using "ServerFlasgs" options as follows.