3.6.5. Display

TI SoCs with Display Sub-System (DSS) hardware offer hardware acceleration for alpha blending of overlays and color conversion. The libdrm module exposes DSS hardware through the software Direct Render Management (DRM) API. Through this DRM interface, a user space program can perform mode setting of the display.

The DRM module models the display hardware as a series of abstract hardware blocks and manages them through the API. The blocks are:

  • CRTC[1]: represents a scanout engine that generates video timing signal from the data pointed to by the scanout buffer

  • Connector: represents where the video timing signal goes and how it gets there

  • Encoder: transforms the video timing signal from the CRTC to a format that is suitable for sending to the connector

  • Plane: represents the overlay buffer that will feed a CRTC

The list of available DRM blocks is viewable using the application modetest.

3.6.5.1. Finding the connector ID

Run the following modetest command:

# modetest -M tidss -c

Look for the required display device’s connector ID - such as High-Definition Multimedia Interface (HDMI), DisplayPort (DP), and so on.

Connectors:
id      encoder status          type    size (mm)       modes   encoders
4       3       connected       HDMI-A  480x270         20      3
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  1920x1080 60 1920 2008 2052 2200 1080 1084 1089 1125 flags: phsync, pvsync; type: preferred, driver
...
16      15      connected       unknown 0x0             1       15
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  800x480 60 800 1010 1040 1056 480 502 515 525 flags: nhsync, nvsync; type: preferred, driver

The modes displayed are the various resolutions supported by the connected display.

3.6.5.2. Finding the plane ID

To find the Plane ID, run the modetest command:

# modetest -M tidss -p

Which should show something similar to the following:

Planes:
id      crtc    fb      CRTC x,y        x,y     gamma size
19      0       0       0,0             0,0     0
 formats: RG16 RX12 XR12 RA12 AR12 XR15 AR15 RG24 RX24 XR24 RA24 AR24 NV12 YUYV UYVY
 props:
 ...
20      0       0       0,0             0,0     0
 formats: RG16 RX12 XR12 RA12 AR12 XR15 AR15 RG24 RX24 XR24 RA24 AR24 NV12 YUYV UYVY
 props:
 ...

3.6.5.3. Using the connector ID and plane ID

The earlier information is useful when attempting to select what display to render to. Some user space applications have command line switches to easily show this. These applications are using Kernel Mode Setting (KMS). For more information about KMS see the upstream kms documentation. For now, you only need to keep 2 things in mind:

  1. Applications that intend to interact with the KMS interface usually do not need any user input. They can query device info through the interface and will normally pick the first connected display automatically.

  2. Only one application can manage the KMS interface at a time. Weston is normally the first graphical application started by default and as such it will prevent you from starting any other KMS applications. See Stopping Weston if you want to use another KMS application.

If you want to change rendering behavior for an application check with that applications documentation for a way to specify a connector, plane, and / or CRTC information. One KMS application we include is kmscube. Below are some examples on how to avoid the default behavior of automatically choosing a display to render to.

Run kmscube on the default display:

# kmscube

Run kmscube on the secondary display:

# kmscube -n <connector_id>

For example, if the connector id for the secondary display is 16:

# kmscube -n 16