DRM Implementation Overview
The Linux driver is an implementation of the Direct Rendering Manager (DRM) framework. The Video Mixer IP is modeled as a DRM CRTC object and each Mixer layer (including the video output stream layer) is a DRM Plane. DRM Planes can assume one of three logical roles:
- Primary: this serves as the mode-setting layer and determines the background screen image
- Overlay: a layer designed to be superimposed over the primary layer. It can be a streaming or memory interface
- Cursor: a special layer designed to represent a screen pointer or equivalent
By default, the Mixer’s various layers will be mapped to the above DRM Plane roles as follows:
|Mixer IP Layer||DRM Plane Type|
|Output stream layer||Primary|
|Layer 1-8 (2018.1/2018.3)|
The default assignment of the layer serving as DRM Primary can be overridden in the device tree with the optional property xlnx,layer-primary. This property can be used to assign the role of “primary” to any one of the Mixer layers(except logo) present in the design. Other hardware layers will be assigned the role of “overlay” layer.
As an overlay plane, the output stream layer will only respond to video format changes; its size will always correspond to the current size of the assigned primary layer. There are several cases wherein assignment of the primary layer to a mixer overlay layer might be advantageous:
- Your mixer instance is configured to stream out YUV 4:2:2 but you wish to present user space drivers with an ARGB memory interface. You could configure the Mixer with an overlay layer that accepts ARGB memory formatted data and assign this as the DRM primary layer. User space is able to write ARGB and conduct normal mode setting/resolution changes through this layer yet the final output, via the Mixer, will be transformed into YUV 4:2:2.
- Your use case is such that using overlays superimposed over a background primary plane does not work. Instead, you wish the background layer to be the top layer( in z-order position and utilize per-pixel alpha values to create open regions in the background through which content can be framed underneath. This might be done in the case where the primary plane is used to render video/audio controls and the video is displayed beneath this superimposed gui background. By assigning the primary plane to be the uppermost layer, the remaining layers can be used, effectively, as underlays.
From within Vivado, Mixer layers can be configured with the following optional properties:
- layer alpha
- layer scaling (1x, 2x or 4x)
These properties, if described in the device tree, will be represented as DRM plane properties. To understand more about these capabilities, please refer to the Video Mixer Product Guide [PG243].
Additionally, the Video Mixer supports generation of solid background color when either the AXI streaming input is not connected or the layer is otherwise disabled. On initialization, this color is programmed to default to blue. The color may be configured using a value representing packed RGB little-endian format via the DRM plane property bg_color. This property is attached to the primary plane.
CSC coefficients programming
IP version 5.0, provides option to enable CSC coefficient registers to be applied on primary layer.
Driver adds the COLOR_ENCODING and COLOR_RANGE properties to support BT601/709/2020 color encoding schemes with limited and full range.
driver by default configures to BT709 with Limited range.
For more details about DRM framework supported encoding schemes, please refer drm_color_mgmt.h
To verify the proper configuration and operation of the IP, a suitable hardware design will need to include at a minimum:
- Video DMA IP to supply an input stream to the Mixer IP (layer 0) (e.g. VDMA or Framebuffer Read DMA)
- Video Mixer IP
- Encoder driver(HDMI-TX / SDI-TX / MIPI DSI-TX)
Modetest is a test tool which can be found as part of the libdrm suite of test tools. We will use this tool to ensure proper configuration and operation of the Mixer IP. Modetest can be used to activate overlay layers and alter layer properties (e.g. layer alpha, layer scaling, background color) & coefficient register programming for csc by passing color encoding and range properties. Following table captures the property values of encoding and range .
Test 1 - Ensure DRM driver has been properly loaded and is configured
Output should include information about the Encoder, Connector, CRTC (the Mixer), Planes (Mixer layers). All Mixer layers will be deactivate by invoking modetest so the screen should become a solid hue of blue (the default background color).
Below is a Sample output of 2019.1 SDI-Tx with 10bpc as the encoder (edited for brevity and clarity):
Test 2 - Activate an overlay layer
We will activate an overlay plane (RGB in this case) and position it to the top left corner while the background color is being generated using the following command:
Output should indicate the plane id that was activated:
Additionally, the plane should be presented with diagonally stripped color pattern on screen.
Test 3 - Scale the layer (if enabled for the layer)From within another console window (and/or if the previous test was run in the background), adjust the layer scale property using modetest. The plane id (33 in case of the example above) will be needed to adjust overlay properties like scale, alpha or background color
Note that the range of possible values for a property appears in the output of modetest. For example, in the case of plane id 33:
Assuming the up-scaled version of the plane image will fit within the screen, the plane data should be doubled in size by setting the scale property to '1'.
Test 4 - Change layer alpha (if enabled for the layer)Changing the layer alpha will make an existing overlay layer appear more or less transparent. An alpha value of '0' will render the overlay invisible and a value of '256' will be completely opaque. With an existing layer being displayed (see test 2), change the alpha property to '0' to render the layer invisible.
The layer should disappear.
Changing the alpha property back to 256 by repeating the above command with a value of 256 should render it visible again.
Test 5 - Change the background color
The Mixer generates a background color when the primary layer is inactive. By default, this is blue. The color is controlled by an internal RGB-based register and is represented by modetest as a decimal value. The most significant bits represent 'blue' and the least 'red'. As such, by default, only the upper 8 bits are set to generate a solid blue (0xFF0000) resulting in a default value of 16711680.
The background color should be a pure red and the new value of the bg_color property will be 255 (0x0000FF).
Test 6 - Change the output resolution
To change Mixer output to a new resolution, modetest must be invoked with the connector id and new resolution. In this example, we change to output 1920x1080:
The output should be an SMPTE color bar pattern on the screen in the new resolution specified (note: an optional refresh rate can be added to the above command when multiple options are available via the monitor's EDID).
vbltest is a test tool which is part of the libdrm suite of test tools. It is used to ensure vertical blanking interrupts are properly sent by the DRM driver.
Test 7- Vbltest - Testing vertical blanking interrupts
The exact frequency output reported should correspond to the display refresh rate (60 Hz in this example). Simply terminate the test when satisfied.
- AR66753 - LogiCORE Video Mixer - Release Notes and Known Issues for the Vivado 2016.1 tool and later versions