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

CEC MCAL Module

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

This module provides an abstraction layer for the HDMI-CEC controller (CEC) of STM32 MCUs: the single-wire consumer electronics control bus of the HDMI connectors (the remote control of the TV, the volume, the standby of the whole chain). It offers the logical address of the device, the transmission and the reception of the messages (the header, the opcode and up to 14 operand bytes), the listen-only mode, the signal-free time and the error handling according to the HDMI-CEC 1.4 specification. It is a low-level MCAL module: it owns the CEC hardware, the application and the other modules never touch the registers.

The public interface (Cec_Port.h, Cec_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​

  • CEC lets the devices on an HDMI link control one another over one wire at 400 bit/s: the player switches the TV on, the TV forwards the remote control keys, the amplifier follows the volume. The bit timing is very slow and strict (the start bit, the data bits with the pulse widths, the acknowledge bit that is driven by the receiver, the end-of-message bit), and the bus is shared between several devices with the arbitration. The hardware takes care of the bit level; the module owns the message level.
  • A message is the header (the initiator and the destination logical addresses), the opcode and the operands. The module sends it as a unit (Cec_Set_TxMessage) and delivers the received messages with the source, the destination and the broadcast flag to the callback; the CEC protocol (the physical and logical address discovery, the device menu, the feature opcodes) is a middleware above it.
  • The device may be a sniffer: the listen mode receives the messages not addressed to it without touching the line (no acknowledge).
  • The kernel of the CEC runs from a 32 kHz clock and can work in the Stop mode, so a TV can be woken by a CEC message.
  • The module hides the differences between the families: the kernel clock source, the number of the pins and the wake-up options differ, the interface stays the same.

What the module is not: it does not implement the CEC protocol above the messages, it does not read the EDID or the physical address of the HDMI port (the application provides the physical address) and it does not drive the HDMI hot-plug signals.


Concept​

ItemMeaning
Own addressA bit mask of the logical addresses (0 ... 14) that the device accepts as the destination (Cec_Set_OwnAddress), the broadcast is always accepted.
Signal-free timeThe idle time before the transmission (automatic by the hardware according to the history of the line, or one of the fixed values 1 ... 7 bit periods).
ToleranceThe standard or the extended tolerance of the bit timing of the received bits.
Error handlingThe detection of the bit rising error, the short and the long bit period error; the optional error bit generation and the stop of the reception on the error.
ModeNormal, listen-only.
MessageThe initiator, the destination, the opcode and the operands (cec_Message_t), the length 1 ... 16 bytes including the header, the end-of-message mark.

Rules:

  1. Cec_Init configures the kernel clock, the addresses, the timing and the error handling and enables the controller.
  2. Cec_Set_TxMessage( message ) is a request: it returns at once and the TxCallback reports the result - sent and acknowledged, the not acknowledged (the destination did not answer), the arbitration lost, the underrun, the transmit error. A new request while one runs returns an error.
  3. The reception is continuous after the enable; the RxCallback delivers a complete message (the end-of-message bit) or the error callback reports the receive error with the part received so far. The module stores one received message until it is read (Cec_Get_RxMessage).
  4. A broadcast message has the destination 15 (CEC_ADDRESS_BROADCAST); a message in the listen mode is delivered with the not for me flag.
  5. The callbacks are called from the interrupt; the flags are cleared by the module.
  6. All parameters are checked before a register is written (the length, the addresses, the state).

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/STM32H5CEC on the STM32H5E / H5F lines: HDMI-CEC 1.4, an independent 32 kHz kernel clock, operation in Stop mode, the signal-free time, the listen mode, the tolerance and the error generationplanned (first)
STM32H7Dev/STM32H7CEC on the lines that have itplanned
STM32F7Dev/STM32F7CEC on the lines that have itplanned
STM32F4Dev/STM32F4CEC on the lines that have it (STM32F446)planned
STM32G4, STM32L4, STM32U5, STM32U3Dev/STM32G4 ...device dependent; the module is a stub that returns CEC_REQUEST_ERROR where the peripheral is missingplanned

A function without a meaning in a family stays in the interface, returns CEC_REQUEST_ERROR and suppresses the unused parameters (for example the wake-up from Stop on a device without it).


Public interface in short (proposal)​

GroupFunctions
Module managementCec_Get_ModuleVersion, Cec_Init, Cec_Deinit, Cec_Task, Cec_Get_DefaultConfig
SettingsCec_Set_OwnAddress / Get, Cec_Set_SignalFreeTime / Get, Cec_Set_ListenMode, Cec_Set_Tolerance, Cec_Set_ErrorHandling
MessagesCec_Set_TxMessage, Cec_Set_TxAbort, Cec_Get_TxState, Cec_Get_RxMessage
InterruptsCec_Set_IrqPriority / Get, the callbacks are a part of the configuration
PinsCec_InitGpio
cec_ModuleVersion_t Cec_Get_ModuleVersion ( void );

cec_RequestState_t Cec_Init ( const cec_Config_t * const cecConfig );
cec_RequestState_t Cec_Deinit ( void );
void Cec_Task ( void );
cec_RequestState_t Cec_Get_DefaultConfig ( cec_Config_t * const cecConfig );

cec_RequestState_t Cec_Set_OwnAddress ( cec_AddressMask_t addressMask );
cec_RequestState_t Cec_Set_SignalFreeTime ( cec_SignalFreeTime_t signalFreeTime );
cec_RequestState_t Cec_Set_ListenMode ( cec_FunctionState_t listenMode );

cec_RequestState_t Cec_Set_TxMessage ( const cec_Message_t * const message );
cec_RequestState_t Cec_Set_TxAbort ( void );
cec_RequestState_t Cec_Get_RxMessage ( cec_Message_t * const message );

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

TypeMeaning
cec_Config_tKernel clock source, own address mask, signal-free time, tolerance, error handling, listen mode, wake-up, pin, callbacks, interrupt priority
cec_Message_tInitiator, destination, opcode (optional for the ping), the operands and their count
cec_TxResult_tCEC_TX_OK, CEC_TX_NOT_ACKNOWLEDGED, CEC_TX_ARBITRATION_LOST, CEC_TX_UNDERRUN, CEC_TX_ERROR
CallbacksTxCallback( result ), RxCallback, ErrorCallback( errorMask )

Usage​

A playback device that answers on the logical address 4​

#include "Cec_Port.h"

static void App_CecRx( void )
{
cec_Message_t message = { 0u };
cec_RequestState_t reqState = CEC_REQUEST_ERROR;

reqState = Cec_Get_RxMessage( &message );

if( CEC_REQUEST_OK == reqState )
{
/* hand the message to the CEC protocol middleware */
}
else
{
/* No message is waiting */
}
}

cec_Config_t cecConfig;

(void)Cec_Get_DefaultConfig( &cecConfig );
cecConfig.OwnAddress = CEC_ADDRESS_MASK( 4u );
cecConfig.RxCallback = App_CecRx;

(void)Cec_Init( &cecConfig );

const cec_Message_t standby = { .Initiator = 4u, .Destination = CEC_ADDRESS_BROADCAST, .Opcode = CEC_OPCODE_STANDBY, .OperandCnt = 0u };
(void)Cec_Set_TxMessage( &standby );

Behaviour and limits​

  • Slow bus. A message of 16 bytes takes about 0.4 s on the line (24 ms per byte: 10 bits of 2.4 ms); the transmission request must not be repeated before the result callback.
  • Acknowledge. In a directly addressed message the receiver drives the acknowledge bit: no answer means CEC_TX_NOT_ACKNOWLEDGED (the destination is not there); the broadcast message is acknowledged by the absence of a negative acknowledge.
  • Kernel clock. The 32 kHz clock must run (the LSE, or the divided HSI / CSI of the family); the accuracy of the clock sets the bit timing tolerance.
  • Wake-up. The reception in the Stop mode needs the kernel clock that runs in the Stop mode; the wake-up on a message addressed to the device is configured by the module.
  • Not part of the first version: the CEC protocol (the address allocation, the device discovery, the menus), the physical address, the arbitration retries policy beyond the hardware.

Dependencies​

  • Rcc - peripheral clock, kernel clock selection and frequency, request of the clock in Stop mode
  • Nvic - interrupt
  • Gpio - the CEC line pin
  • 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 address mask handling, the message validation (the length, the addresses, the broadcast), the transmit flow with every result (acknowledged, not acknowledged, arbitration lost, underrun), the receive flow with the error cases, the listen mode, the rejected requests.
  • Integration tests (target, probe-rs): two CEC nodes (two boards or a CEC analyser) exchanging messages, the not-acknowledged destination, the broadcast, the wake-up from Stop mode by a message.

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 CEC_<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. Cec_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 Cec_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 (cec_FunctionState_t, cec_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 CEC_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
Cec_Port.h, Cec_Types.hPublic interface (identical in all families)
Cec*.c, Cec.hImplementation of the family
CMakeLists.txtLibrary Cec_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 Cec_Lib )
  1. Link Cec_Lib to your CMake library.
  2. Include Cec_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.