The purpose of this page is to describe the Linux DRM driver for The HDMI 1.4/2.0 Transmitter Subsystem soft IP.

For the HDMI 2.1 Transmitter Subsystem Driver, please see Xilinx DRM KMS HDMI 2.1 TX Subsystem Driver.

Introduction

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 Feature	2018.1 hdmi-modules	2018.3 and onward hdmi-modules
compatible string	xlnx,v-hdmi-tx-ss-3.1	xlnx,v-hdmi-tx-ss-3.1
IP Version Supported	3.1	3.1
HDMI 2.0 and 1.4 compatible	Y	Y
pixel per clock	IP supports 2 or 4 ppc Driver tested for 2 ppc only.	IP supports 2 or 4 ppc Driver tested for 2 ppc only.
Supports resolutions up to 4,096 x 2,160 @60 fps	Y	Y
8, 10, 12, and 16-bit Deep-color support	8 & 10-bit Only	8 & 10-bit Only
Support color space for RGB, YUV 4:4:4, YUV 4:2:2, YUV 4:2:0	Support all color spaces	Support all color spaces
Support AXI4-Stream Video output stream and Native Video output stream	Axi-Stream Video Only	Axi-Stream Video Only
Optional High Bandwidth Digital Copy Protection (HDCP) 1.4 support	Y	Y
Optional HDCP 2.2 support	Y	Y
Optional Video over AXIS compliant NTSC/PAL Support	Y	Y
Optional Video over AXIS compliantYUV420 Support	Y	Y
Xilinx DRM bridge support	N	Y (from 2022.1)

Note:

DRM bridge support verified with the display pipeline Framebuffer_read → VPSS (scaler_only) → HDMI-Tx

Missing Features / Known issues / Limitations in Driver

This driver support Xilinx DRM bridge, but verified when VPSS is connected as "Scaler_only" mode and without mixer.

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.

The driver sources can be found here: https://github.com/Xilinx/hdmi-modules/tree/master/hdmi/xilinx-hdmi-tx

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

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

CONFIG_kernel-module-hdmi

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

IMAGE_INSTALL_append = " kernel-module-hdmi"

Next include the driver in the rootfs

% petalinux-config -c rootfs

Select "user-pakages->modules->kernel-module-hdmi", save and exit
Build the project

%petalinux-build

Device Tree Binding

The dts node should be defined with correct hardware configuration. How to define the node is documented in

2024.2: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.yaml

2022.1: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

2021.2: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

2021.1: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

2020.2: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

2020.1: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

2019.2: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

2019.1: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

2018.3: Documentation/devicetree/bindings/xlnx,v-hdmi-tx-ss.txt

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_info	Read-Only by all	Shows detected stream properties
hdmi_log	Read-Only by all	Shows event logs captured by the driver
hdcp_log	Read-Only by all	Shows event logs captured by the driver
hdcp_debugen	Write-Only by group and owner	1: Enable detailed logging of hdcp events 0: Disable detailed logging of hdcp events (0 is the default)
hdcp_authenticate	Write by group and owner Read by all	1: enable authentication upon stream up 0: disable
hdcp_encrypt	Write 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_protect	Write 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_key	R/W by owner only	Allows owner to write the HDCP key binary data (read from EEPROM) to IP
hdcp_password	R/W by owner only	Allows 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_info	Read-Only by all	Shows video_phy status for both Rx and Tx
vphy_log	Read-Only by all	Shows 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

%> cat /sys/devices/platform/amba_pl\@0/<device_addr>/hdmi_info

To enable detailed logging of hdcp events

%> echo 1 > /sys/devices/platform/amba_pl\@0/<device_addr>/hdcp_debug

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

%> modetest -M xlnx -s <connector_id>[@<crtc_id>]:<mode>[-<vrefresh>][@<format>

For ex:

%> modetest -M xlnx -s 30@28:1920x1080-60@YUYV &

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

root@zcu102:~# modetest -M xlnx
Encoders:
id      crtc    type    possible crtcs  possible clones
29      28      TMDS    0x00000001      0x00000000
 
Connectors:
id      encoder status          name            size (mm)       modes   encoders
30      29      connected       HDMI-A-1        600x340         28      29
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  3840x2160 60 3840 4016 4104 4400 2160 2168 2178 2250 594000 flags: phsync, pvsync; type: preferred, driver
  3840x2160 60 3840 4016 4104 4400 2160 2168 2178 2250 593407 flags: phsync, pvsync; type: driver
  3840x2160 50 3840 4896 4984 5280 2160 2168 2178 2250 594000 flags: phsync, pvsync; type: driver
  3840x2160 30 3840 4016 4104 4400 2160 2168 2178 2250 297000 flags: phsync, nvsync; type: driver
  3840x2160 30 3840 4016 4104 4400 2160 2168 2178 2250 297000 flags: phsync, pvsync; type: driver
  3840x2160 30 3840 4016 4104 4400 2160 2168 2178 2250 296703 flags: phsync, pvsync; type: driver
  3840x2160 25 3840 4896 4984 5280 2160 2168 2178 2250 297000 flags: phsync, pvsync; type: driver
  3840x2160 24 3840 5116 5204 5500 2160 2168 2178 2250 297000 flags: phsync, pvsync; type: driver
  3840x2160 24 3840 5116 5204 5500 2160 2168 2178 2250 296703 flags: phsync, pvsync; type: driver
  1920x1080 60 1920 2008 2052 2200 1080 1084 1089 1125 148500 flags: phsync, nvsync; type: driver
  1920x1080 60 1920 2008 2052 2200 1080 1084 1089 1125 148500 flags: phsync, pvsync; type: driver
  1920x1080 60 1920 2008 2052 2200 1080 1084 1089 1125 148352 flags: phsync, pvsync; type: driver
  1920x1080 30 1920 2008 2052 2200 1080 1084 1089 1125 74250 flags: phsync, pvsync; type: driver
  1920x1080 30 1920 2008 2052 2200 1080 1084 1089 1125 74176 flags: phsync, pvsync; type: driver
  1920x1080 24 1920 2558 2602 2750 1080 1084 1089 1125 74250 flags: phsync, pvsync; type: driver
  1920x1080 24 1920 2558 2602 2750 1080 1084 1089 1125 74176 flags: phsync, pvsync; type: driver
  1600x900 60 1600 1624 1704 1800 900 901 904 1000 108000 flags: phsync, pvsync; type: driver
  1280x1024 60 1280 1328 1440 1688 1024 1025 1028 1066 108000 flags: phsync, pvsync; type: driver
  1280x800 60 1280 1328 1360 1440 800 803 809 823 71000 flags: phsync, nvsync; type: driver
  1152x864 60 1152 1216 1336 1520 864 865 868 895 81579 flags: nhsync, pvsync; type:
  1280x720 60 1280 1390 1430 1650 720 725 730 750 74250 flags: phsync, pvsync; type: driver
  1280x720 60 1280 1390 1430 1650 720 725 730 750 74176 flags: phsync, pvsync; type: driver
  1024x768 60 1024 1048 1184 1344 768 771 777 806 65000 flags: nhsync, nvsync; type: driver
  800x600 60 800 840 968 1056 600 601 605 628 40000 flags: phsync, pvsync; type: driver
  720x480 60 720 736 798 858 480 489 495 525 27027 flags: nhsync, nvsync; type: driver
  720x480 60 720 736 798 858 480 489 495 525 27000 flags: nhsync, nvsync; type: driver
  640x480 60 640 656 752 800 480 490 492 525 25200 flags: nhsync, nvsync; type: driver
  640x480 60 640 656 752 800 480 490 492 525 25175 flags: nhsync, nvsync; type: driver
  props:
        1 EDID:
                flags: immutable blob
                blobs:
 
                value:
                        00ffffffffffff001e6d085b92a10400
                        031a0103803c2278ea3035a7554ea326
                        0f50542108007140818081c0a9c0d1c0
                        81000101010108e80030f2705a80b058
                        8a0058542100001e04740030f2705a80
                        b0588a0058542100001a000000fd0038
                        3d1e873c000a202020202020000000fc
                        004c4720556c7472612048440a2001d9
                        020330714d902220050403020161605d
                        5e5f230907076d030c001000b83c2000
                        6001020367d85dc401788003e30f0003
                        023a801871382d40582c450058542100
                        001a0000000000000000000000000000
                        00000000000000000000000000000000
                        00000000000000000000000000000000
                        00000000000000000000000000000026
        2 DPMS:
                flags: enum
                enums: On=0 Standby=1 Suspend=2 Off=3
                value: 0
        5 link-status:
                flags: enum
                enums: Good=0 Bad=1
                value: 0
 
CRTCs:
id      fb      pos     size
28      47      (0,0)   (3840x2160)
  3840x2160 60 3840 4016 4104 4400 2160 2168 2178 2250 594000 flags: phsync, pvsync; type: preferred, driver
  props:
 
Planes:
id      crtc    fb      CRTC x,y        x,y     gamma size      possible crtcs
27      28      47      0,0             0,0     0               0x00000001
  formats: XB24 XB30 XR24 XV24 VU24 XV30 YUYV UYVY NV16 NV12 XV15 XV20 BG24 GREY Y10  RG24
  props:
        6 type:
                flags: immutable enum
                enums: Overlay=0 Primary=1 Cursor=2
                value: 1
 
Frame buffers:
id      size    pitch

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

How to test DRM bridge with HDMI-Tx:

To support bridge functionality HDMI-Tx driver requires few DRM connector properties like height, width, aspect ratio and color format of input and output.

Following is the table of color formats and its equivalent media bus format value to be passed as DRM properties.

Refer the media bus formats here

Format	Media Bus Value
RGB	4106
YUV444	8228
YUV420	8448
YUV422	8207

Sample command to perform upscale 720p@60(1280x720) to 1080p@60(1920x1080) :

%> modetest -D amba_pl@0:drm-dmaengine-drv -s 37:1280x720-60@BG24 -w 37:height_out:1080 -w 37:width_out:1920 -w 37:in_fmt:4106 -w 37:out_fmt:4106 -w 37:aspect_ratio:1

Sample command to perform downscale 1080p@60(1920x1080) to 720p@60(1280x720)

%> modetest -D amba_pl@0:drm-dmaengine-drv -s 37:1920x1080-60@BG24 -w 37:height_out:720 -w 37:width_out:1280 -w 37:in_fmt:4106 -w 37:out_fmt:4106 -w 37:aspect_ratio:1

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

2024.2

Summary:
- <No change>

2024.1

Summary:
- dp159: use simple i2c probe function
- hdmirx: Update Audio status based on audio infoframes

2023.2

Summary:

2023.1

Summary
- hdmitx: Fixed hdmi compilation with kernel 6.1
commits
- hdmitx: Fixed hdmi compilation with kernel 6.1

2022.2

Summary
- Set have_edid flag when HDMI-Tx connected
commits
- Set have_edid flag when HDMI-Tx connected

2022.1

Summary
- Added gitignore file
- Fixed clean path in Makefile
- Add VPSS scaler only bridge support
- Added new attributes to VIC table
- Added 64:27 and 256:135 aspect ratio
- Add error check for connector state
- Merge 5.15 kernel
- Fix Comments for setting VSWING_DATA/CLK
- hdmitx: Remove registring with hdmi-audio-codec driver
Commits

2021.2

Summary
- Add support for YUV 444 3 planar color format
- Fix multiple instance of audio driver registration
Commits
- hdmitx: Add support for 3 planar YUV444 8 BPC
- hdmitx: Fix multiple instance audio driver registration

2021.1

Summary
- Update linux driver as per bare metal driver updates
- Fix for 720x480i60 and 720x576i50 resolutions
- Add support for Native video interface
- Upgrade driver to kernel v5.10
Commits

2020.2

Summary
- Add support for HDR
- Add AR24 and AB24 as known DRM formats
- Fix bridge enable sequence
- Set the number of audio channels based on hw_params
- Parse and store EDID like data
- Fix coverity warnings
- Add support for V4L2 style colorimetry
Commits

2020.1

Summary
- Driver is updated to work with v5.4 kernel
- Minor bug fix in HDMI Tx
- Update the license for 2020.1
- Update to use unified phy driver
Commits

2019.2

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

2019.1

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

2018.3

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

2018.1

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

Table of Contents