Bringing a custom panel up on Linux is mostly a configuration task, and the configuration is spread across more places than most engineers expect: a panel description, a controller driver, a device tree entry and sometimes a firmware blob. Understanding which layer owns which value is what turns a week of trial and error into an afternoon.

This article covers how that structure works in practice, how datasheet timings map into software, and how to keep the result maintainable across kernel versions.

How panel support is structured in DRM/KMS

The distinction between a panel description and a bridge matters when the interface changes. If the platform’s output is a different format from the panel’s input, a bridge driver does the conversion, and the panel description describes only what the panel needs. Debugging a display that never lights is therefore two questions: does the bridge produce output, and does the panel description match the panel.

The distinction between a panel description and a bridge matters when the interface changes. If the platform’s output is a different format from the panel’s input, a bridge driver does the conversion, and the panel description describes only what the panel needs. Debugging a display that never lights is therefore two questions: does the bridge produce output, and does the panel description match the panel.

The distinction between a panel description and a bridge matters when the interface changes. If the platform’s output is a different format from the panel’s input, a bridge driver does the conversion, and the panel description describes only what the panel needs. Debugging a display that never lights is therefore two questions: does the bridge produce output, and does the panel description match the panel.

The distinction between a panel description and a bridge matters when the interface changes. If the platform’s output is a different format from the panel’s input, a bridge driver does the conversion, and the panel description describes only what the panel needs. Debugging a display that never lights is therefore two questions: does the bridge produce output, and does the panel description match the panel.

The display subsystem separates three responsibilities. A panel description states what the display is: its timing, its bus format, its power and reset behaviour. A controller or bridge driver knows how to drive a particular interface on the system-on-chip. The device tree, or an equivalent board description, connects the two and tells the system which panel is attached.

That separation is useful because it means a new panel usually needs a new description rather than a new driver. Where a panel is electrically compatible with an existing controller path, the work is confined to the description and the board wiring.

Where timing parameters are defined

Timing lives in the panel description. The values that appear there correspond directly to the panel’s datasheet: the pixel clock, horizontal and vertical active and blanking periods, and the sync polarities. The controller driver reads those values and programs its own registers accordingly.

The most common mistake is to put a value in the board file because that is where it worked first, creating two sources of truth. When the panel is replaced or the board is revised, the duplicated value becomes a debugging trap. Keep timing where the panel is described.

Translating datasheet timings into software values

Pixel-clock tolerance is worth checking at the same time. Panels specify a range rather than a single value, and a clock at the edge of that range may work at room temperature and fail when the panel is cold or hot. Choosing a value near the centre of the permitted range costs nothing and leaves margin for later.

Pixel-clock tolerance is worth checking at the same time. Panels specify a range rather than a single value, and a clock at the edge of that range may work at room temperature and fail when the panel is cold or hot. Choosing a value near the centre of the permitted range costs nothing and leaves margin for later.

Pixel-clock tolerance is worth checking at the same time. Panels specify a range rather than a single value, and a clock at the edge of that range may work at room temperature and fail when the panel is cold or hot. Choosing a value near the centre of the permitted range costs nothing and leaves margin for later.

Pixel-clock tolerance is worth checking at the same time. Panels specify a range rather than a single value, and a clock at the edge of that range may work at room temperature and fail when the panel is cold or hot. Choosing a value near the centre of the permitted range costs nothing and leaves margin for later.

Datasheet timing tables describe the same waveform the software needs, but they express it in the panel’s own convention. Three translation problems recur.

The first is the reference point: some tables measure blanking from the end of the active area, others from the start of the sync pulse. The difference shows up as a small horizontal or vertical offset rather than as a failure. The second is total versus active: the software usually needs the total period, which is the sum of active and blanking. The third is polarity: sync signals are described as active-high or active-low in the datasheet, and inverted in some drivers.

Work through the table term by term against the software values, and record the mapping in the commit message. That note is what makes the next panel’s bring-up faster.

Bus, reset and power sequencing hooks

Most panels require a specific order of events: supply stable, reset released after a delay, then the interface enabled. In the software model these become hooks on the panel description – a regulator reference, a reset line with its delay, and an enable signal where the panel needs one.

Where the panel is used in a handheld or vehicle product, the integration work overlaps with porting Linux and Android touch drivers. These hooks matter more than they appear to. A reset released too early produces a panel that latches before its internal circuits are ready, which typically shows as a blank screen that works after a second power cycle. The sequencing description belongs with the panel, for the same reason the timing does.

Backlight and brightness integration

The backlight is usually a separate device from the panel: a pulse-width-modulated output, a regulator with a control input, or a dedicated driver over a serial bus. It is described separately and linked to the panel so that brightness control reaches the right hardware.

Two integration details are worth checking. The polarity and frequency of the brightness control determine whether the panel flickers or the range is compressed at one end. And the mapping between the user’s brightness setting and the hardware value determines whether the control feels linear; a naive linear mapping is often perceptually wrong, with most of the visible change happening at the low end.

Rotation, pixel format and scaling

Rotation and pixel format belong to the panel description, and getting them wrong produces the two most distinctive symptoms: colours that are swapped or missing, and geometry that is correct but mirrored or transposed.

Scaling is a separate matter. If the panel’s resolution does not match what the application renders, the graphics stack has to scale, and the result is usually softer than native rendering. Where the platform supports integer scaling, use it; otherwise design the interface for the panel’s resolution rather than accepting a scaled image.

Debugging tools that show what the panel receives

The subsystem exposes information about the modes it has configured, the state of the connector and the panel’s current timing. Reading that state before changing anything tells you whether the software believes it has a valid mode, which is a different question from whether the panel is receiving it.

For the second question, an oscilloscope on the clock and data lines answers what no software tool can: whether the source is actually transmitting, and whether the timing matches what the configuration claims.

Symptoms of a wrong timing configuration

Symptom	Likely configuration cause
Image stable but shifted on the screen	Blanking reference point or polarity mismatch
Image displayed but torn or unstable	Pixel clock outside the panel’s range
Colours wrong, geometry correct	Pixel format or lane mapping
Image mirrored or transposed	Rotation or scan direction setting
Blank screen that works after a second power cycle	Reset or supply sequencing
Works at boot, fails after a mode change	Duplicate timing values in two places

Keeping the configuration maintainable

Decide early whether the panel description lives in the vendor’s tree or upstream. A description kept locally survives until the next kernel update and then disappears from the build; one submitted upstream takes effort but stops being a maintenance item. Whichever route is chosen, record where the description lives alongside the board revision it was verified on.

Decide early whether the panel description lives in the vendor’s tree or upstream. A description kept locally survives until the next kernel update and then disappears from the build; one submitted upstream takes effort but stops being a maintenance item. Whichever route is chosen, record where the description lives alongside the board revision it was verified on.

Decide early whether the panel description lives in the vendor’s tree or upstream. A description kept locally survives until the next kernel update and then disappears from the build; one submitted upstream takes effort but stops being a maintenance item. Whichever route is chosen, record where the description lives alongside the board revision it was verified on.

Decide early whether the panel description lives in the vendor’s tree or upstream. A description kept locally survives until the next kernel update and then disappears from the build; one submitted upstream takes effort but stops being a maintenance item. Whichever route is chosen, record where the description lives alongside the board revision it was verified on.

Three habits keep a panel configuration usable across kernel versions and board revisions.

Keep values in one place: the panel description. Record the mapping from the datasheet to the software values in a comment or a commit message, so the next engineer does not have to re-derive it. And note the board revision the configuration was verified against, because a hardware change that moves a reset line or changes a regulator will invalidate part of the description without changing the panel.

Bring-up sequence

The sequence that works: start from a known-good configuration for a panel of the same class, change one value at a time, verify after each change, and write down what changed. Check power and reset before the interface, and check the interface before the image.

When a panel will not come up, the fastest route is usually to establish whether the software has accepted the mode and whether the hardware is transmitting – two different questions with two different tools. For the platform-level view of the same problem, the interface selection guidance in choosing a TFT LCD module interface explains why some panels are easier to integrate than others.

Frequently asked questions

Do we need to write a kernel driver for a custom panel?

Usually not. Most panels can be described with an existing driver plus a panel description, provided the interface is supported by the platform.

Why does the image look correct but slightly offset?

Typically a blanking or polarity convention mismatch rather than an incorrect value. Check how the datasheet defines the reference point.

Where should timing values live?

In the panel description, in one place. Duplicated values in a board file create failures that appear only after a revision change.