Skip to content

README.md

Latest commit

 

History

History
147 lines (106 loc) · 4.28 KB

README.md

File metadata and controls

147 lines (106 loc) · 4.28 KB
Raw

dc_generic

Generic display controller abstraction layer for bare-metal Ada applications.

Overview

dc_generic provides a hardware-independent display controller interface for embedded systems. It abstracts LCD/LTDC controllers through generic instantiation, separating control plane (initialization, configuration) from data plane (layer management, framebuffer updates) operations.

Features

  • Hardware-agnostic display controller abstraction
  • Separate control and data operation packages
  • Combined interface package for convenience
  • Multi-layer support (Layer_1, Layer_2)
  • Multiple pixel format support
  • Reload modes (Immediate, On_VSync)
  • Blending factor configuration
  • Background color control
  • Zero runtime overhead through generic instantiation

Architecture

The package is organized into three layers:

  • DC_Types - Common types (layers, pixel formats, reload modes, blending factors)
  • DC_Control - Display initialization, start/stop, background color
  • DC_Data - Layer initialization, framebuffer management, reload operations
  • DC_Interface - Combined control and data interface

API

DC_Types

package DC_Types is
   type LCD_Layer is (Layer_1, Layer_2);
   
   type Pixel_Format is
     (ARGB8888, RGB888, RGB565, ARGB1555, ARGB4444, L8, AL44, AL88);
   
   type Reload_Mode is (Immediate, On_VSync);
   
   type Blending_Factor is
     (BF_Constant_Alpha,
      BF_Pixel_Alpha_X_Constant_Alpha);
end DC_Types;

DC_Interface

generic
   --  Lifecycle
   with procedure Driver_Initialize;
   with function  Driver_Is_Initialized return Boolean;
   with procedure Driver_Start;
   with procedure Driver_Stop;
   with procedure Driver_Set_Background (R, G, B : UInt8);
   with procedure Driver_Reload (Mode : Reload_Mode);
   with procedure Driver_Reload_Async;
   with procedure Driver_Wait_For_Reload;
   
   --  Layer operations
   with procedure Driver_Layer_Init
     (Layer          : LCD_Layer;
      Format         : Pixel_Format;
      Buffer         : System.Address;
      X, Y           : Natural;
      W, H           : Positive;
      Constant_Alpha : UInt8;
      BF             : Blending_Factor);
   
   with procedure Driver_Set_Frame_Buffer
     (Layer : LCD_Layer;
      Addr  : System.Address);
   
   with function Driver_Get_Frame_Buffer
     (Layer : LCD_Layer) return System.Address;
   
   with procedure Driver_Set_Layer_State
     (Layer   : LCD_Layer;
      Enabled : Boolean);

package DC_Interface is
   procedure Initialize;
   function Initialized return Boolean;
   procedure Start;
   procedure Stop;
   procedure Set_Background (R, G, B : UInt8);
   procedure Reload (Mode : Reload_Mode := On_VSync);
   procedure Reload_Async;
   procedure Wait_For_Reload;
   
   procedure Layer_Init
     (Layer          : LCD_Layer;
      Format         : Pixel_Format;
      Buffer         : System.Address;
      X, Y           : Natural;
      W, H           : Positive;
      Constant_Alpha : UInt8           := 255;
      BF             : Blending_Factor := BF_Pixel_Alpha_X_Constant_Alpha);
   
   procedure Set_Frame_Buffer (Layer : LCD_Layer; Addr : System.Address);
   function Get_Frame_Buffer (Layer : LCD_Layer) return System.Address;
   procedure Set_Layer_State (Layer : LCD_Layer; Enabled : Boolean);
end DC_Interface;

Usage

See gpio_generic README for the standard instantiation pattern. Display controllers follow the same architecture: hardware driver → generic instantiation → board-level facade.

Design Rationale

Idempotent Initialization

The Driver_Is_Initialized formal allows the display controller to be initialized once even if multiple packages attempt initialization. State is owned by the board crate.

Separate Reload Operations

Reload_Async + Wait_For_Reload enable double-buffering patterns where rendering continues while waiting for VSync.

Layer-Based Architecture

Two-layer support enables overlay graphics (e.g., UI elements over video) with independent pixel formats and blending.

Integration

Add to your alire.toml:

[[depends-on]]
dc_generic = "^0.1.0"

Dependencies

  • machine_types - Provides MT.UInt8 type

Used By

  • fb_generic - Framebuffer interface (builds on dc_generic)
  • stm32f746 - STM32F7 LTDC driver

License

MIT OR Apache-2.0 WITH LLVM-exception