Xilinx DRM KMS HDMI-Tx Driver

Table of Contents


The purpose of this page is to describe the Linux DRM driver for Xilinx HDMI Tx Soft IP for Zynq Ultrascale+ MPSOC
The HDMI 1.4/2.0 Transmitter Subsystem is a feature-rich soft IP incorporating all the necessary logic to properly interface with PHY layers and provide HDMI® encoding functionality. The subsystem is a hierarchical IP that bundles a collection of HDMI TX-related IP sub-cores and outputs them as a single IP. The subsystem takes incoming video and audio streams and transfers them to an HDMI stream. The stream is then forwarded to the video PHY layer.

The HDMI 1.4/2.0 Transmitter Subsystem is a MAC subsystem which works with a Video PHY Controller (PHY) to create a video connectivity system. The HDMI 1.4/2.0 Transmitter Subsystem is tightly coupled with the Xilinx Video PHY Controller, which itself is independent and offer flexible architecture with multiple-protocol support. Both MAC and PHY are dynamically programmable through the AXI4-Lite interface.

MAC Interface with PHY

Driver Overview

HDMI Tx is the last node in the display pipeline. The linux driver is implemented as a sub-component of the Xilinx DRM KMS bridge driver and implements the encoder/connector interface. The subsystem includes the video timing generator and Tx sub-core. Driver implements the DRM callbacks to read the display EDID and present it to the framework anytime a display is connected. It works in tandem with the DRM bridge driver to validates each mode listed in the EDID and reject unsupported modes.

On mode change request from user application driver works in conjunction with DRM framework to validate the requested mode to ensure the stream can be generated by Tx core and is supported by the attached display. If requested mode is supported the driver will configure Tx sub-core for new mode and the internal video timing controller (VTC) to generate requisite video timing for it. It also configures the PHY layer for the new mode and manages all required interaction between MAC & PHY layer.

After mode setup is complete PHY state machine is reset and put into a wait state awaiting the reference clock for the new mode from an external clock source. DRM framework requests the registered clock producer (SI5324/SI5319 for Xilinx HDMI) to generate the clock for desired mode. Availability of this clock is checked by PHY using tx_refclk_rdy port pin. After this pin is asserted HIGH PHY’s internal state machine is triggered to lock onto the incoming frequency and stream transmission starts. As a last step the driver then configures the external LVDS to TMDS level shifter component (DP159), via CCF framework, which will convert the GT output signals to HDMI interface.

IP/Driver Features

IP Feature2018.1 hdmi-modules2018.3 and onward hdmi-modules
IP Version Supported3.13.1
HDMI 2.0 and 1.4 compatibleYY
2 or 4 symbol/pixel per clock input (PPC)2 PPC Only2 PPC Only
Supports resolutions up to 4,096 x 2,160 @60 fpsYY
8, 10, 12, and 16-bit Deep-color support8 & 10-bit Only8 & 10-bit Only
Support color space for RGB, YUV 4:4:4, YUV 4:2:2, YUV 4:2:0Support all color spaces Support all color spaces
Support AXI4-Stream Video output stream and
Native Video output stream
Axi-Stream Video OnlyAxi-Stream Video Only
Optional High Bandwidth Digital Copy Protection (HDCP) 1.4 supportYY
Optional HDCP 2.2 supportYY
Optional Video over AXIS compliant NTSC/PAL SupportYY
Optional Video over AXIS compliantYUV420 SupportYY

Missing Features / Known issues / Limitations in Driver

  • This driver doesn't support Xilinx DRM bridge. So display pipelines like Framebuffer Read → VPSS Scaler → HDMI Tx will not work.

Kernel Configuration Options for Driver

2018.1 and onwards Kernel brings-in the support for the new component based DRM framework from Xilinx. HDMI driver has been updated to work with the new framework and is not backward compatible with the old Xilinx drm framework.

2018.1 and onwards: Supports ONLY the new Xilinx DRM framework driver and PL crtc and can be enabled via following configurations options

The above defined options will only enable the new DRM framework. Since HDMI Tx driver is now added as an out-of-tree kernel module, there is not kernel configuration required. Instead user must include the driver in the rootfs. Following steps are required enable the driver
  • Make sure the meta-user layer has the recipe-hdmi included
  • For 2019.2 onwards
    • Add the recipe to petalinux image. Edit ./meta-user/conf/user-rootfsconfig and add the new recipe at the end

  • For 2018.1 to 2019.1
    • Add the recipe to petalinux image. Edit ./meta-user/recipes-core/images/petalinux-image-full.bbappend and add the new recipe at the end
      • NOTE - While using 2018.1 petalinux, the file name was ./meta-user/recipes-core/images/petalinux-image.bbappend
  • Next include the driver in the rootfs
  • Select "user-pakages->modules->kernel-module-hdmi", save and exit
  • Build the project

Device Tree Binding

The dts node should be defined with correct hardware configuration. How to define the node is documented in
2018.1: Documentation/devicetree/bindings/xlnx%2Cv-hdmi-tx-ss.txt

Device Control

Sysfs interface has been added to the driver to enable the user to query the current device status and/or change certain properties. Below table describes the available commands and the access permissions available

Command Name Permission Description
hdmi_infoRead-Only by allShows detected stream properties
hdmi_logRead-Only by allShows event logs captured by the driver
hdcp_logRead-Only by allShows event logs captured by the driver
hdcp_debugenWrite-Only by group and owner1: Enable detailed logging of hdcp events
0: Disable detailed logging of hdcp events
(0 is the default)
hdcp_authenticateWrite by group and owner

Read by all
1: enable authentication upon stream up
0: disable
hdcp_encryptWrite by group and owner

Read by all
1: enable encryption after authentication
0: do not enable encryption after authentication
hdcp_authenticated Read-Only by all 1: Authentication successful
0: Un-authenticated
hdcp_encrypted Read-Only by all 1: Input stream is encrypted
0: Input stream is unencrypted
hdcp_protectWrite by group and owner

Read by all
1: content must be protected - If the encrypted flag is not set, then the output will be blanked
0: no protection is required – disable hdcp blank
hdcp_keyR/W by owner onlyAllows owner to write the HDCP key binary data (read from EEPROM) to IP
hdcp_passwordR/W by owner onlyAllows owner to set a password for the hdcp key in eeprom. After writing (first) password
and (then) key, upon reading back hdcp_password it returns "accepted" when the password
could decrypt the key. It reads back "rejected" in all other cases.
vphy_infoRead-Only by allShows video_phy status for both Rx and Tx
vphy_logRead-Only by allShows event logs captured by both Rx and Tx

Sysfs entries are accessible at /sys/devices/platform/amba_pl\@0/<device_addr>/

For ex:
To read out information on current set output stream
To enable detailed logging of hdcp events

HDCP Support

Driver supports HDCP1.4 and 2.2 Protocols and exposes the sysfs controls to allow user space to load the encrypted HDCP production keys and read-in the requisite password to decrypt the keys. If the provided password is able to decrypt the keys, keys will be loaded into the required IP blocks and the HDCP feature will be enabled. The driver boots with HDCP disabled as default state. User can load the keys any time after the system is running. An example application that demonstrates the HDCP key loading process from user space will be provided by Xilinx for customer reference. For details on HDCP Support provided by the soft IP please refer product guide pg235 on Xilinx.com

Disclaimer: It is user’s responsibility to provide and protect the confidential key data. HDCP Keys must be programmed into the EEPROM on the board.

Test procedure

HDMI-Tx can be manually configured to generate the required mode. An open source utility like modetest can be used to configure the display pipeline.
  • DDR ==> FB_Rd (DMA) ==> HDMI_Tx

Note: Since 2018.1 introduces a new Xilinx drm driver, below test procedure will cover details for 2018.1 and later versions.
2018.1 and onwards: xlnx

2018.1 and onwards
Sample command to set a mode is shown below

For ex:

Above command will generate a color bar pattern at requested resolution in DDR, configures the DMA to read the frame from DDR and configures the HDMI Tx for said resolution. As a final result Color Bar at defined resolution should be visible on screen.

Driver also supports changing output color formats dynamically. Available output color formats supported by DMA engine can be determined using modetest utility as shown below

Refer Line "formats" that indicates the FrameBuffer DMA IP configuration supports XB24 XB30 XR24 XV24 VU24 XV30 YUYV UYVY NV16 NV12 XV15 XV20 BG24 GREY Y10 color formats. This setting is configured by the DMA driver device tree node property xlnx,vid-formats

DEBUG Capability

HDMI Linux driver implements the capability to tap IP status at pre-defined points in the control flow. User can enable the debug taps by uncommenting the pre-processor directive (#define DEBUG) to monitor the progress within the driver. All debug prints are sent to serial console and can be viewed in kernel dmesg buffer

Boards Supported

Driver has been tested on following boards
  • zcu102 Rev 1.0
  • zcu106 Rev 1.0

Driver has been tested with HDMI FrameBuffer Example Design design

Change Log




  • Summary
    • Driver updated for 2019.2
    • Enabled suspend and resume
    • Updated license file for 2019.2
  • Commits
    • be354c license: Update the license 2019.2
    • 55a308 phy: Enabling 4th GT channel in TX
    • 7eeeb1 hdmitx:hdmirx:vphy: Enabling suspend and resume
    • b608fb hdmitx:hdmirx:phy: remove "addtogroup" from files
    • e8da36 hdmitx:hdmirx:vphy: Driver update till 20190814


  • Summary
    • Fixed a bug so that HDMI/DVI mode is selected according to the connected monitor EDID
    • Updated lookup table for audio ACR N parameters
    • Made HDMI driver compliant with 4.19 linux kernel version
    • Made driver compliant with DTG tool generated Device tree nodes and updated the documentation.
    • Added support for NTSC and PAL resolutions
    • Added 10bpc media bus format support
    • Changed TX HPD to interrupt based
    • Updated license file for 2019.1
  • Commits
    • 21c537 hdmitx:hdmirx: 10 bit format support
    • cf0a56 hdmitx: hdmirx: vphy: Driver update 5Apr2019
    • 6f65b2 hdmitx: modify lookup table for audio N parameter
    • fe84ed license: Update the license obtained from legal
    • 3b3484 dt:bindings: Updated the documentation on DT bindings
    • 947f4f tx: hdmirx: vphy: Driver update 14Mar2018
    • 53af3d hdmitx: Changing tx hpd interrupt based
    • e96b83 hdmitx:hdmirx:vphy: Support for auto DTG
    • 1701dc hdmitx: HdmiTx is not put in DVI mode when attached to a DVI monitor
    • e6284b hdmirx:hdmitx: NTSC and PAL resolution support
    • cccf4a hdmitx:hdmirx: Adaptation to 4.19 kernel version


  • Summary
    • Added interlace resolution support (except NTSC and PAL)
    • Added support for audio using Xilinx PL Audio Formatter IP
    • Removed si5324 driver from hdmi-module and now its part of kernel.
    • Fixed bugs in 2018.1 and earlier release
  • Commits
    • 2a05aa hdmitx: use TMDS clock ratio flag for 4k in audio driver
    • 5d42de hdmitx:hdmirx:vphy:dt:bindings: Drivers update 20181004
    • 80dbb6 hdmirx:hdmitx: Interlace field 1 calculation fixed
    • 47bff5 hdmitx: Enabling audio in TXstreamupCb
    • f0a2a7 clk: Removing si5324 from hdmi_module
    • aa2455 hdmitx: Changed error to warning for non supported fourcc
    • 74a4c6 dt:bindings: Update related to snd-pcm name
    • 1c0710 hdmitx:hdmirx:phy: Update driver version 20180817
    • 99b8e7 hdmitx:hdmirx:dt:bindings: Updating comments and doc for audio
    • f9994e hdmitx:hdmirx:phy: Updated driver IP version
    • 5bc312 hdmitx: Disable IbufD when cable disconnect
    • b8508a hdmitx:hdmirx:dt:bindings: Integration of audio
    • a0771b hdmitx: Correction in XVidC_GetVideoModeIdExtensive


  • Summary
    • Updated to support v3.1 HDMI-Tx IP. This is the default IP version in the catalogue
    • Moved to new component based drm framework interface from Xilinx. This driver is not backward compatible with the older framework
  • Commits
    • 20a28a hdmitx: add gcp avmute capability
    • c58ab7 add BGR8 memory format to video common
    • ebee44 Initial release of 2018.1 hdmi drivers as kernel modules

Related Links