Changes to the driver should be reviewed against the documentation for the following hardware.
Datasheets for other models may be used to correct gaps and errors in the datasheets for the target models. All information obtained in this manner must be confirmed experimentally, especially when the datasheet we use applies to a different design generation. For example, the AMLogic S912 datasheet fills a few gaps, but the S912 chip uses the GXM design.
AMLogic's documentation makes heavy use of acronyms. This section goes over the acronyms for the top-level modules, and briefly describes their functionality.
The entire display engine is generally called the VPU (Video Processing Unit). It is also called the Video Output Unit in the high-level overview (A311D datasheet Section 2.2 “Features”).
The display engine is split into the VIU (Video Input Unit), which is the engine‘s frontend, and the VOUT (Video Output), which is the engine’s backend.
The display engine can have multiple VIU instances. The AMLogic A311D has two VIUs (VIU1, VIU2), so it can drive two displays at once.
Each VIU has multiple input channels that retrieve pixel data (scanout) and feed it into a VPP (Video Post-Processing) unit, which performs image processing such as scaling, blending, and CSC (color space conversion, including color and gamma correction). In other display engines, the input channels are called planes or layers, and the entire VIU is called a pipe.
The VIU has two types of input channels, listed below.
The VD channels support Chroma-downsampled planar formats, such as YUV 4:2:0. The channels do Chroma upsampling before feeding the data to VPP.
Each VIU has multiple VD channels and OSD channels. The VIUs in AMLogic A311D have two VD channels (VD1, VD2) and four OSD channels (OSD1, OSD2, OSD3, OSD4).
This subsection is speculation, as there is no documentation explaining the reasoning behind names. With that being said, a plausible explanation for the input channel naming scheme points to the STB (TV set-top box) use case, which is prominently mentioned in the AMLogic datasheets and quick start manuals.
The typical setup uses a VD channel to display the TV video, sourced from a video decoder that produces YUV data. The second VD plane may be used for picture-in-picture or to display two TV channels side-by-side.
The OSD planes display “control panels”, which are rendered by software running on the AMLogic processor. RGB is the preferred pixel format for rendering.
All documented display engines have a single VOUT instance.
Conceptually, the VOUT consists of a VENC (Video Encoder) stage that converts processed image data into a video signal, and an analog front-end stage that contains PHYs (physical layer) for transmitting the video signal via various connectors.
The VOUT hosts a few encoder blocks. Each encoder is unique in terms of the properties of its output signal. Each VIN can be connected to an encoder. There is very little flexibility in connecting encoders to PHYs, because display connectors require specific signals.
The VENC stage has the encoders below.
The ENCI and ENCP encoders output the pixel color signal and timing signals, including Display Enabled (DE), Vertical Sync (VSYNC) and Horizontal Sync (HSYNC). These signals are compatible with the HDMI / DVI transmitter.
The analog front-end stage contains PHY (physical layer) transmitters for the following display connectors.
The HDMI block embeds a Synopsis DWC (DesignWare Core) HDMI Transmitter Controller IP, which transcodes the encoder output to TMDS signals and sends them to the HDMI PHY.
The AMLogic documentation refers to the DesignWare IP as “HDMI TX Controller IP”, and to the integration glue as “HDMITX Top-Level” (HDMI_TOP and HDMITX_TOP). Driving the HDMI block entails configuring registers in both the AMLogic TOP and in the DesignWare IP.
The MIPI DSI block follows a similar structure.
The analog frontend conceptually belongs to the HHI (undocumented acronym), which hosts a variety of analog-digital circuits including PHYs, power gates, and PLLs (Phased Lock Loops) used by the clock tree.
The VPU accesses DRAM using the on-chip DMC (DRAM Memory Controller). The VPU is connected to the DMC via AMBus, a specialized bus optimized for burst transfers. For example, on A311D, the VPU has 5 dedicated AMBus channels (3 for read requests, 2 for write requests) to the DMC.
AMBus transactions to the DMC use the canvas table for address translation. Each entry in the canvas table describes a canvas, which is a contiguous region in DRAM designated for storing pixel data, associated with metadata describing a specific pixel format. Each AMBus transaction executes in the context of a canvas table entry, identified by a canvas index.
The canvas table is accessed using registers in the DMC's MMIO address space. The table is likely stored in SRAM inside the DMC, because AMLogic datasheets state that canvas translation is latency-free.
The RDMA (Register Direct Memory Access) engine accelerates flips (configuring the VPU for displaying the next frame, after a VSync), which entail writing a block of VPU registers. The RDMA engine out-performs a sequence of MMIO writes because it has a direct access path to the VCBus (Video Controller Bus) that the VPU registers are attached to.
For historical reasons, many Fuchsia developers are familiar with Intel's display engines. The following mapping may give a head start to these developers.
Just like “no model is entirely correct, but some models are useful”, this mapping is not perfect, as the display engines don't have identical structures.
The code contains references to the following documents.
The code also contains references to the following documents covering display panels. These documents will likely move to different drivers in the future.
The code also contains references to the following documents covering DDICs (Display Driver ICs). These documents will likely move to different drivers in the future.