1. Why HDMI Driver Knowledge Matters in Embedded Display Projects

In an embedded display project, connecting an HDMI cable does not always mean the screen will light up immediately. A display may stay black because of a missing hot-plug signal, failed EDID reading, an incorrect pixel clock, a disabled encoder, a PHY configuration issue, or even an HDCP authentication problem.

For display module development, HDMI driver debugging is often where hardware design, Linux kernel configuration, and display timing knowledge meet. A clear understanding of the Linux HDMI display path can help engineers locate problems faster, especially when working with custom boards, HDMI display modules, controller boards, and industrial display solutions.

PanoxDisplay works with different display interfaces and display control boards, including HDMI-based display solutions. This article explains the HDMI driver framework in Linux from a practical engineering perspective: DRM/KMS architecture, HDMI connector logic, encoder and PHY setup, HDCP handling, audio transmission, and a step-by-step black screen debugging workflow.

 

hdmi connector flow

2. Linux Display Subsystem: DRM and KMS

Linux uses the DRM subsystem, short for Direct Rendering Manager, to manage graphics and display output. Within DRM, KMS, or Kernel Mode Setting, is responsible for setting display modes such as resolution, refresh rate, timing, framebuffer format, and output routing. The Linux kernel documentation describes the KMS display pipeline as a structure where framebuffers feed into planes, planes feed pixel data into a CRTC, and the output path continues through encoders and connectors.

For HDMI display output, the key point is simple: the screen does not receive an image from only one driver function. It depends on a complete display pipeline.

A typical DRM/KMS path looks like this:

Framebuffer → Plane → CRTC → Encoder → Bridge → Connector → HDMI Display

Each component has a different role.

2.1 Plane: The Image Layer

A plane manages the image buffer that will be scanned out to the display. It can be a primary plane, cursor plane, or overlay plane.

In simple display applications, the primary plane carries the main screen image. In more complex systems, overlay planes can be used for video layers, UI elements, or hardware composition.

2.2 CRTC: The Timing Controller

The CRTC controls the display scanout process. It handles timing parameters such as resolution, horizontal sync, vertical sync, refresh rate, and pixel clock.

If the CRTC is not configured with a valid display mode, the HDMI output cannot generate a stable image.

2.3 Encoder: The Signal Converter

The encoder connects the internal display pipeline to a physical output type. In an HDMI system, it prepares the display stream for HDMI transmission.

The Linux DRM documentation notes that encoders are part of the KMS output routing model and are connected between the CRTC and connector.

2.4 Bridge: The Optional Conversion Stage

A bridge is an intermediate chip or IP block used to convert one display interface into another.

Common examples include:

Not every HDMI design uses a bridge. Some SoCs integrate HDMI output directly.

2.5 Connector: The Physical Output Interface

The connector represents the actual output interface, such as HDMI-A, DisplayPort, VGA, or eDP.

For HDMI, the connector is responsible for:

In practical debugging, the HDMI connector is usually the first place to check.
 

3. Atomic Commit: Applying Display State Safely

Modern DRM drivers use atomic mode setting. The idea is that multiple display changes are checked and applied together.

For example, a mode change may include:

With atomic commit, the kernel checks whether the complete configuration is valid before applying it. If the configuration cannot work, it should fail as a whole instead of leaving the display pipeline in a half-configured state.

Typical helper functions include:

drm_atomic_helper_check();
drm_atomic_helper_commit();

For HDMI debugging, this means a black screen may not be caused by only the final HDMI output stage. The atomic check may fail earlier because the mode, plane format, bridge chain, or connector routing is invalid.

drm kms architecture

4. HDMI Connector Driver: Detecting the Display

The HDMI connector is the external-facing part of the driver. It detects cable insertion, reads EDID, reports connection status, and exposes supported display modes.

4.1 HPD: Hot Plug Detection

HPD stands for Hot Plug Detect. When an HDMI cable is connected or disconnected, the HPD pin changes state. The Linux driver usually captures this event through GPIO interrupt handling or an SoC-specific HDMI interrupt.

A typical HPD flow looks like this:

1. HDMI cable is inserted.

2. HPD pin level changes.

3. GPIO or HDMI interrupt is triggered.

4. The driver calls the DRM hot-plug event handler.

5. The connector detect callback is executed.

6. The kernel reports the connector as connected.

7. EDID is read through the DDC channel.

8. Display modes are created and exposed to user space.

A common DRM helper call is:

drm_helper_hpd_irq_event(dev);

If HPD never triggers, check these points first:

For many embedded boards, HPD problems are among the most common reasons why an HDMI monitor is not detected.

4.2 EDID Reading Through DDC

After HDMI connection is detected, the system reads EDID from the display device. EDID stands for Extended Display Identification Data. It tells the source device what resolutions, refresh rates, color formats, audio formats, and other capabilities the display supports.

EDID is usually read through the DDC channel, which is based on I2C. The EDID device address is commonly 0x50.

A simplified EDID reading flow:

drm_get_edid(connector, adapter);
i2c_transfer();
drm_edid_block_valid();
drm_add_edid_modes();

Useful debug commands:

cat /sys/class/drm/card0-HDMI-A-1/edid | edid-decode

Or view the raw data:

hexdump -C /sys/class/drm/card0-HDMI-A-1/edid | head -20

If EDID cannot be read, check:

DDC lines usually require proper pull-up resistors. On many hardware designs, SCL and SDA use pull-ups such as 4.7 kΩ, but the actual value should follow the board design and chip vendor recommendation.

4.3 Connector Callback Functions

In a Linux DRM HDMI driver, the connector communicates with the DRM core through callback functions.

Common connector callbacks include:

A typical connector function structure may look like this:

static const struct drm_connector_funcs hdmi_connector_funcs = {
    .detect = hdmi_connector_detect,
    .fill_modes = drm_helper_probe_single_connector_modes,
    .destroy = drm_connector_cleanup,
    .atomic_get_property = hdmi_atomic_get_property,
    .atomic_set_property = hdmi_atomic_set_property,
};

For debugging, the detect() and EDID-related functions are especially important because they determine whether user space can even see the HDMI display as an available output.
 

5. HDMI Encoder and PHY Configuration

After the connector detects a display and the DRM pipeline chooses a mode, the HDMI encoder and PHY must generate the correct signal.

The encoder prepares the video data for HDMI transmission. The PHY converts internal digital signals into high-speed differential electrical signals.

5.1 Clock Path: From Reference Clock to TMDS Clock

HDMI output depends heavily on clock accuracy. If the pixel clock is wrong, the monitor may show a black screen, flickering, unstable image, or “out of range” warning.

A typical HDMI clock path includes:

1. Reference oscillator

2. PLL multiplier

3. Clock divider

4. Pixel clock

5. TMDS character clock

6. PHY serial clock

7. Differential HDMI output

Common pixel clock examples:

In real projects, the exact clock depends on timing parameters, blanking intervals, color depth, and the selected video standard.

For custom display solutions, clock configuration should not be guessed. It must match the mode timing, the SoC HDMI IP capability, the PHY capability, and the display sink capability.

5.2 TMDS and FRL

HDMI 2.0 and earlier systems commonly use TMDS transmission. TMDS uses differential pairs to send video data and clock information.

Newer HDMI specifications introduce FRL, or Fixed Rate Link, for higher-bandwidth modes. HDMI Licensing describes FRL as a signaling technology used for higher bandwidth HDMI specifications, with HDMI 2.2 supporting up to 96 Gbps and the Ultra High Speed HDMI Cable from HDMI 2.1 supporting up to 48 Gbps maximum bandwidth.

A practical comparison:

For many embedded HDMI display modules and industrial display projects, TMDS is still the most common mode. FRL becomes more important when the application requires very high resolution, high refresh rate, deep color, or advanced HDMI 2.1/2.2 features.

5.3 HDMI PHY Configuration

The PHY is where digital display configuration becomes real electrical output.

Important PHY parameters include:

PHY debugging often requires both software and hardware tools. Kernel logs may show whether the PLL is locked, but a high-speed oscilloscope or eye diagram test may be needed to confirm signal quality.

5.4 Common HDMI Driver Blocks

Different SoC platforms use different HDMI drivers or IP blocks. Common examples include:

The exact debug path depends on the SoC, kernel version, device tree, and board design. However, the general logic remains similar: connector detection, EDID reading, mode selection, encoder enable, PHY configuration, and signal output.

phy clock config

6. HDCP in Linux HDMI Output

HDCP stands for High-bandwidth Digital Content Protection. It is used to protect video content transmitted through digital display interfaces such as HDMI and DisplayPort.

In Linux DRM, content protection is exposed through connector properties. The DRM content protection property is attached to a connector and allows user space to request link protection. The property can report states such as Undesired, Desired, and Enabled.

6.1 Content Protection States

A simplified explanation:

Only the driver can report the final protected state. If the link fails authentication, the connector may remain in the Desired state instead of becoming Enabled.

6.2 HDCP 2.2 Authentication Flow

HDCP 2.2 authentication is more complex than HDCP 1.4. A simplified flow includes:

1. Authentication and key exchange starts.

2. The source verifies the receiver.

3. Locality check confirms that the receiver is physically connected.

4. A session key is exchanged.

5. Encryption starts.

6. If repeaters are used, topology verification is performed.

In kernel driver debugging, HDCP failures are usually related to:

Useful command:

cat /sys/class/drm/card0-HDMI-A-1/properties/content_protection

Typical kernel log patterns:

dmesg | grep -i hdcp

Possible logs may include:

hdcp: authentication failed
hdcp: authenticated successfully
hdcp: link check failed

In industrial or embedded display applications, HDCP is not always required. If the screen is used for UI, HMI, instrumentation, or machine control, HDCP may not be involved. However, for media playback, protected video content, set-top boxes, or consumer HDMI products, HDCP support may become important.
 

7. HDMI Audio Configuration

HDMI can transmit both video and audio. In Linux, HDMI audio usually involves cooperation between the ALSA audio subsystem and the DRM display framework.

A simplified HDMI audio path:

1. The application outputs PCM audio through ALSA.

2. The audio driver writes data into DMA or FIFO buffers.

3. The HDMI controller packages audio data into HDMI data islands.

4. Audio InfoFrame packets describe the audio format.

5. The receiving device decodes and plays the audio.

7.1 Audio InfoFrame

The Audio InfoFrame works like a small description packet. It tells the HDMI sink what kind of audio data is being transmitted.

Common fields include:

If the video works but audio is missing, Audio InfoFrame configuration should be checked together with ALSA device selection and HDMI sink capability.

7.2 ARC and eARC

ARC means Audio Return Channel. It allows a TV to send audio back to an audio device such as a soundbar through the HDMI cable.

eARC, or Enhanced Audio Return Channel, is a newer version with higher audio bandwidth and better support for advanced audio formats.

For embedded display modules and industrial monitors, ARC and eARC are usually not the core requirement. For consumer display systems, smart displays, and multimedia products, they may become part of the total HDMI solution.

7.3 Common HDMI Audio Problems

audio subsystem

8. Practical Debugging: From Black Screen to Display Output

When a new board is connected to an HDMI display and the screen stays black, debugging should follow a structured path. Randomly changing kernel settings often wastes time and may introduce new problems.

The following seven-step workflow can help narrow down the issue.

8.1 Step 1: Check HPD Detection

Run:

dmesg | grep -i hpd

Also check connector status:

cat /sys/class/drm/card0-HDMI-A-1/status

Expected result:

connected

If the result is:

disconnected

Check:

8.2 Step 2: Read EDID

Run:

cat /sys/class/drm/card0-HDMI-A-1/edid | edid-decode

If edid-decode is not installed, use:

hexdump -C /sys/class/drm/card0-HDMI-A-1/edid | head -20

If EDID reading fails, check:

If EDID is valid, the system should be able to generate a list of supported display modes.

8.3 Step 3: Inspect DRM Connectors and Modes

modetest is a useful DRM/KMS diagnostic tool. It can list connectors, encoders, CRTCs, planes, and supported modes, and it can also set display modes directly.

List connectors:

modetest -M <driver_name> -c

Example:

modetest -M rockchip -c

Look for:

If no modes appear, EDID or connector detection is still not working correctly.

8.4 Step 4: Check CRTC Binding

List CRTCs and planes:

modetest -M <driver_name> -p

The goal is to confirm that a valid CRTC is available and can be routed to the HDMI connector.

Possible issues:

8.5 Step 5: Confirm Encoder Enable

Check encoder-related logs:

dmesg | grep -i encoder

Also check DRM logs if dynamic debug is enabled.

If the encoder is not enabled, possible causes include:

8.6 Step 6: Check PHY and Signal Output

If HPD and EDID work, and the encoder is enabled, but the display is still black, the PHY becomes a key debug area.

Check:

A screen that flickers or shows random noise often points to clock accuracy or signal integrity rather than pure software configuration.

8.7 Step 7: Force a Display Mode with modetest

When the basic path looks correct, force a mode directly through DRM/KMS.

Example:

sudo modetest -M <driver_name> -s <connector_id>:1920x1080-60

Some platforms also support atomic mode setting through:

sudo modetest -M <driver_name> -a -s <connector_id>:1920x1080-60

This bypasses a full desktop environment and tests the DRM driver more directly.

If forced mode setting works, but the normal system UI does not display, the issue may be in user space, such as Wayland, X11, framebuffer configuration, Qt, or application-level display selection.
 

9. Quick Troubleshooting Table

10. Design Notes for HDMI Display Solutions

For HDMI display products, driver debugging should not be separated from hardware design. A stable HDMI display solution depends on the full chain.

Important design points include:

For projects using custom display sizes, high-brightness LCD modules, long strip displays, OLED panels, or HDMI controller boards, early verification is important. A display may look like a simple output device, but the actual signal path includes hardware timing, kernel driver state, and user-space display configuration.

PanoxDisplay can support display module selection and HDMI-based display solution matching for embedded devices, industrial control systems, smart hardware, portable monitors, and custom display applications.
 

11. Conclusion

HDMI display output on Linux is not a single switch. It is a complete display pipeline built from DRM/KMS objects, connector detection, EDID reading, encoder routing, PHY signal output, optional HDCP protection, and audio configuration.

When a screen does not light up, the most efficient method is to debug in order:

1. Confirm HDMI connection and HPD.

2. Read and decode EDID.

3. Inspect DRM connector modes.

4. Check CRTC and encoder routing.

5. Verify PHY clock and signal output.

6. Check HDCP if protected content is involved.

7. Use modetest to force a known display mode.

For embedded display development, this workflow turns “the screen is black” from a vague problem into a traceable engineering path. A clear HDMI driver framework also helps hardware engineers, Linux driver developers, and display solution providers work from the same map instead of debugging in separate directions.

Learn more: HDMI Display Interface Explained: Signal Principles, Bandwidth, Versions, and Display Solution Selection