Перейти до основного вмісту

LTDC MCAL Module

Supported STM32 families: H5
Not supported: F4, F7, G4, H7, L4, U3, U5

This module provides an abstraction layer for the LCD-TFT display controller (LTDC) of STM32 MCUs: the parallel RGB interface to a TFT panel - the generation of the pixel clock, the horizontal and the vertical synchronization and the data enable from the timing of the panel, the layers read from the frame buffers in the memory with the blending, the color look-up table, the color keying and the dithering, and the synchronized switching of the frame buffers. It offers the panel and the layer configuration in the user units (pixels, Hz, the pixel format), the double buffering and the line and error events. It is a low-level MCAL module: it owns the LTDC hardware, the application and the other modules never touch the registers.

The public interface (Ltdc_Port.h, Ltdc_Types.h) is identical for all supported families. The implementation for a family lives in its own branch (Dev/<Family> for development, Releases/<Family> for the released versions), so a module or an application written against the interface does not change when the MCU family changes.

This README is the landing page and the specification of the interface (master). The family branches contain their own README with everything that is specific to the family: the instances of the device, their settings and the status of the implementation.

Status: design. No implementation exists yet, the interface below is a proposal. Stories and branches follow.


Intent and purpose​

  • A TFT panel needs a continuous stream of pixels with a precisely timed frame: the synchronization pulses, the front and the back porch, the active area, the pixel clock. The LTDC generates all of it by itself and reads the pixels from the memory with its own DMA, so that the CPU only draws into a frame buffer. The module turns the panel datasheet (the resolution, the porches, the polarities, the pixel clock) into the configuration of the controller, calculates the clock the kernel clock source has to give and reports the refresh rate.
  • The controller composes up to two layers in the hardware: a background layer (the user interface) and a foreground layer (the video or the cursor) with the per-pixel or the constant alpha blending and the color keying (transparency), each with its own frame buffer, window position and size and pixel format (ARGB8888, RGB888, RGB565, ARGB1555, ARGB4444, L8 with the color look-up table, AL44, AL88).
  • The pictures must not tear: the frame buffer is switched at the vertical blanking (the shadow registers are reloaded on the vertical blanking), so the module offers Ltdc_Set_LayerFrameBuffer with the reload mode "at the next vertical blank" and the callback that tells when the previous buffer is free (the double buffering).
  • The module hides the differences between the families: the number of the layers, the pixel formats, the clock, the interrupts and the flexible-layer features differ, the interface stays the same.

What the module is not: it does not draw (the graphics library and the Dma2D module do), it does not turn the panel and the backlight on (the application / a panel driver sequences the power, the reset and the backlight with the Gpio / Tim modules) and it does not configure the memory of the frame buffer (the Fmc / Ospi modules).


Concept​

ItemMeaning
Panel (ltdc_PanelConfig_t)The active width and height, the horizontal and the vertical synchronization width, back porch and front porch (in pixels / lines), the polarities of HSYNC, VSYNC, data enable and the pixel clock, the pixel clock frequency (Hz), the background color.
Layer (ltdc_LayerId_t, ltdc_LayerConfig_t)The window (x, y, width, height) on the screen, the pixel format, the frame buffer address, the line pitch, the constant alpha, the blending factors, the default color, the color key, the CLUT.
ReloadLTDC_RELOAD_IMMEDIATE or LTDC_RELOAD_VBLANK - when the new layer parameters take effect.
DitheringThe pseudo-random dithering of the lower bits for the panels with fewer bits per channel.
EventsThe line interrupt (a programmable line), the register reload done, the FIFO underrun, the transfer error.

Rules:

  1. Ltdc_Init calculates the pixel clock divider and the timing registers from the panel, requests the pixel clock from the RCC module (the kernel clock source and the frequency) and leaves the output disabled; it returns an error when the clock cannot be made within the tolerance of the panel.
  2. Ltdc_Set_LayerConfig writes the shadow registers of the layer; the new parameters take effect at the reload (immediate, or at the next vertical blanking, as chosen); Ltdc_Set_LayerFrameBuffer( layer, address ) is the quick form for the buffer switch with the FrameBufferFreeCallback when the old buffer is released by the hardware.
  3. Ltdc_Set_Active starts the output of the pixels; the application powers the panel on after the first valid frame is on the pins and powers it off before Ltdc_Set_Inactive.
  4. The bandwidth is checked: the module calculates the memory bandwidth of the active layers (pixels x bytes x refresh rate) and warns with an error when it exceeds the configured limit of the memory (an optional check).
  5. The FIFO underrun (the memory did not deliver the pixels in time) and the transfer error (a bus error of the frame buffer read) are reported by the error callback; the controller keeps running, the application reduces the load.
  6. All parameters are checked before a register is written; a window beyond the active area is rejected.

Supported families​

Every family gets its own story, its own tasks and its own branches Dev/<Family> and Releases/<Family> cut from this master.

FamilyBranchControllerStatus
STM32H5Dev/STM32H5LTDC on the STM32H5E / H5F lines: 24-bit RGB output, 2 layers with a 64 x 32-bit FIFO each, a 256-entry CLUT per layer, the eight pixel formats, blending, color keying, dithering, programmable window, line interruptplanned (first)
STM32U5Dev/STM32U5LTDC on the lines with the graphics (U5G / U5F)planned
STM32H7Dev/STM32H7LTDCplanned
STM32F7Dev/STM32F7LTDCplanned
STM32F4Dev/STM32F4LTDC on the F429 / F439 / F469 / F479 linesplanned
STM32L4Dev/STM32L4LTDC on the L4R / L4S linesplanned
STM32G4, STM32U3Dev/STM32G4, Dev/STM32U3no LTDC on the device - the module is a stub that returns LTDC_REQUEST_ERRORplanned

A function without a meaning in a family stays in the interface, returns LTDC_REQUEST_ERROR and suppresses the unused parameters (for example the second layer on a device with one, a pixel format or a flexible-layer feature the device does not have).


Public interface in short (proposal)​

GroupFunctions
Module managementLtdc_Get_ModuleVersion, Ltdc_Init, Ltdc_Deinit, Ltdc_Task, Ltdc_Get_DefaultConfig
OutputLtdc_Set_Active, Ltdc_Set_Inactive, Ltdc_Get_State, Ltdc_Get_RefreshRate
LayersLtdc_Set_LayerConfig, Ltdc_Set_LayerFrameBuffer, Ltdc_Set_LayerActive, Ltdc_Set_LayerInactive, Ltdc_Set_LayerAlpha, Ltdc_Set_LayerColorKey, Ltdc_Set_LayerClut
DisplayLtdc_Set_BackgroundColor, Ltdc_Set_Dithering, Ltdc_Set_Reload
EventsLtdc_Set_LineInterrupt, Ltdc_Get_Position
InterruptsLtdc_Set_IrqPriority / Get, the callbacks are a part of the configuration
PinsLtdc_InitDataGpio, Ltdc_InitSyncGpio, Ltdc_InitClockGpio
ltdc_ModuleVersion_t Ltdc_Get_ModuleVersion ( void );

ltdc_RequestState_t Ltdc_Init ( const ltdc_Config_t * const ltdcConfig );
ltdc_RequestState_t Ltdc_Deinit ( void );
void Ltdc_Task ( void );
ltdc_RequestState_t Ltdc_Get_DefaultConfig ( ltdc_Config_t * const ltdcConfig );

ltdc_RequestState_t Ltdc_Set_Active ( void );
ltdc_RequestState_t Ltdc_Set_Inactive ( void );
ltdc_RequestState_t Ltdc_Get_RefreshRate ( ltdc_Frequency_mHz_t * const refreshRate );

ltdc_RequestState_t Ltdc_Set_LayerConfig ( ltdc_LayerId_t layerId, const ltdc_LayerConfig_t * const layerConfig, ltdc_Reload_t reload );
ltdc_RequestState_t Ltdc_Set_LayerFrameBuffer ( ltdc_LayerId_t layerId, ltdc_Address_t frameBuffer );
ltdc_RequestState_t Ltdc_Set_LayerAlpha ( ltdc_LayerId_t layerId, ltdc_Alpha_t alpha );
ltdc_RequestState_t Ltdc_Set_LayerClut ( ltdc_LayerId_t layerId, const ltdc_Color_t * const clut, ltdc_ClutCnt_t clutCnt );
ltdc_RequestState_t Ltdc_Set_LineInterrupt ( ltdc_Line_t line );

Every function returns LTDC_REQUEST_OK / LTDC_REQUEST_ERROR and checks its parameters and the state of the module before it touches a register.

TypeMeaning
ltdc_Config_tThe panel, the kernel clock source, the dithering, the background color, the layer table, the pins, the callbacks, the interrupt priority
ltdc_LayerConfig_tWindow, pixel format, frame buffer, pitch, alpha, blending, default color, color key
ltdc_PixelFormat_tLTDC_FORMAT_ARGB8888, _RGB888, _RGB565, _ARGB1555, _ARGB4444, _L8, _AL44, _AL88 - the ones of the device
ltdc_Reload_tLTDC_RELOAD_IMMEDIATE, LTDC_RELOAD_VBLANK
CallbacksLineCallback, ReloadCallback, FrameBufferFreeCallback, ErrorCallback( errorMask )

Usage​

An 800 x 480 RGB565 panel with a double-buffered layer​

#include "Ltdc_Port.h"

ltdc_Config_t ltdcConfig;
ltdc_LayerConfig_t layer;

(void)Ltdc_Get_DefaultConfig( &ltdcConfig );

ltdcConfig.Panel.ActiveWidth = 800u;
ltdcConfig.Panel.ActiveHeight = 480u;
ltdcConfig.Panel.HorizontalSync = 4u; ltdcConfig.Panel.HorizontalBackPorch = 8u; ltdcConfig.Panel.HorizontalFrontPorch = 8u;
ltdcConfig.Panel.VerticalSync = 4u; ltdcConfig.Panel.VerticalBackPorch = 8u; ltdcConfig.Panel.VerticalFrontPorch = 8u;
ltdcConfig.Panel.PixelClockHz = 33000000u;
(void)Ltdc_Init( &ltdcConfig );

layer.Format = LTDC_FORMAT_RGB565;
layer.WindowWidth = 800u; layer.WindowHeight = 480u;
layer.FrameBuffer = frameBuffer0;
layer.Alpha = LTDC_ALPHA_OPAQUE;
(void)Ltdc_Set_LayerConfig( LTDC_LAYER_1, &layer, LTDC_RELOAD_IMMEDIATE );
(void)Ltdc_Set_LayerActive( LTDC_LAYER_1 );
(void)Ltdc_Set_Active();

/* draw into frameBuffer1, then show it without tearing: */
(void)Ltdc_Set_LayerFrameBuffer( LTDC_LAYER_1, frameBuffer1 ); /* FrameBufferFreeCallback: frameBuffer0 is free */

Behaviour and limits​

  • Bandwidth. The refresh needs width x height x bytes per pixel x rate of the memory bandwidth continuously (about 46 MB/s for 800 x 480 RGB565 at 60 Hz, more with two layers); a frame buffer in a slow memory produces the FIFO underrun. The internal RAM or a fast external memory is chosen to match.
  • Pixel clock. The achievable pixel clock is the kernel clock divided by an integer; the module reports the real refresh rate. The panel tolerance decides whether the result is accepted.
  • Reload. The layer parameters are shadowed; a change without the reload does nothing visible. The vertical blanking reload is the tear-free way.
  • Power sequence. The panel and the backlight are sequenced by the application relative to the output enable (the first valid frame before the backlight).
  • Not part of the first version: the MIPI DSI output of the other devices, the gamma correction tables where the controller has them, the YCbCr layer conversion, the Dma2D integration (the drawing library does it).

Dependencies​

  • Rcc - peripheral clock, the pixel kernel clock source and its frequency
  • Nvic - interrupt
  • Gpio - the RGB data, the synchronization and the pixel clock pins
  • Fmc, Ospi - the external memory of the frame buffer (configured by their modules)
  • RAL (Register Abstraction Layer) - used internally to access the registers

All mandatory RCC, NVIC and GPIO configurations are handled internally.


Testing​

  • Unit tests (host, Unity + CMock + RegMem): the conversion of the panel timing to the registers (the limits, the porch sums), the pixel clock divider and the refresh rate, the layer configuration and the window checks, the reload modes, the frame buffer switch with the callback, the CLUT load, the error callbacks.
  • Integration tests (target, probe-rs): a test pattern on a real panel (the visual check on the bench) or the capture of the pixel bus by a logic analyser for the timing, the tear-free buffer switch, the FIFO underrun with a slowed memory.

Interface conventions​

The module follows the common rules of the MCAL layer, so that it behaves like the other modules:

  • Lists instead of free members. Everything that the hardware restricts (the pins, the kernel clock sources, the DMA channels, the triggers and the other selectable sources) is a typedef enum list with exactly the items that are valid for the device line; a pin is an item LTDC_<SIGNAL>_PIN_<INSTANCE>_P<port><pin> and there is an *_UNUSED item. A choice that is not in the list cannot be written.
  • Own peripheral only. The module calls only the registers / LL functions of its own peripheral. The clocks, the interrupts, the pins, the DMA and the EXTI lines go through the API of the Rcc, Nvic, Gpio, Gpdma and Exti modules; a missing function is added to that module, it is not bypassed.
  • Init verifies itself. Ltdc_Init checks the result at the end; when it is not as required, the module is deinitialized and an error is returned. The waiting for the hardware is a loop on the register state with a timeout, never a blind delay.
  • Transfer modes. Where the module moves data, the POLL (served by Ltdc_Task), ISR and DMA modes have the same configuration structure, the same request and the same callbacks (error, half transfer, transfer complete).
  • Flags and states are enums of the module (ltdc_FunctionState_t, ltdc_FlagState_t), the limits and the constants are named, there are no magic numbers in the interface.
  • Unsupported functions stay. A function without a meaning in a family keeps its signature, suppresses the unused parameters and returns LTDC_REQUEST_ERROR.
  • Documentation. Every function and type has a Doxygen description, the main header has the \defgroup.

Repository layout and branches​

The master holds this README and the license. The family branches (Dev/<Family>, Releases/<Family>) hold:

PathContent
README.mdREADME of the family: the instances of the device, specifics, errata, status
Ltdc_Port.h, Ltdc_Types.hPublic interface (identical in all families)
Ltdc*.c, Ltdc.hImplementation of the family
CMakeLists.txtLibrary Ltdc_Lib of the EmBi platform
Tests/UnitTestsUnit tests (Unity + CMock + RegMem)
Tests/IntegrationTestsIntegration tests on the target (probe-rs)

A change of the public interface is made in all families.


CMake integration​

target_link_libraries( User_Lib PRIVATE Ltdc_Lib )
  1. Link Ltdc_Lib to your CMake library.
  2. Include Ltdc_Port.h in your project.
  3. Configure the module as needed for your hardware.

License​

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).

You are free to use, modify, and share this work for non-commercial purposes, provided appropriate credit is given.

See LICENSE.md for full terms or visit creativecommons.org/licenses/by-nc/4.0.


Authors​

Contributions are welcome! Please open a pull request.