Preskočiť na hlavný obsah

PLAY MCAL Module

This module provides an abstraction layer for the programmable logic array (PLAY) of STM32 MCUs: a small array of the glitch-free logic elements - each a 4-input look-up table with an optional register - with the configurable input and output interconnects, the synchronization and filtering of the inputs, the software controlled inputs and the flags with the interrupts. It lets the application build a piece of custom glue logic in the hardware (a state machine, a gating of signals, a pulse stretcher, a debouncer, an encoder decoder) that works without the CPU, in the low-power modes and with a deterministic nanosecond timing. It is a low-level MCAL module: it owns the PLAY hardware, the application and the other modules never touch the registers.

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

  • Between the peripherals of a microcontroller there is always a little logic missing: "start the ADC when the timer output is high and the input is low", "stretch this pulse to 10 us", "generate the break when either comparator fires and stay latched until the software releases", "decode the three Hall sensors to the commutation state". A software ISR does this with a jitter of microseconds and wakes the CPU; an external CPLD costs a component. The PLAY has 16 logic elements whose inputs can be connected to the pins, to the peripheral signals of the chip (timer outputs, comparator outputs ...) and to the outputs of the other elements, and whose outputs can be routed to the pins and the peripheral trigger inputs.
  • A logic element is described by the truth table (16 bits for the 4 inputs) and by the choice whether the output goes through a register (the flip-flop clocked by a selected clock). The module takes the whole array as one constant description (play_Config_t: the elements, the input interconnect, the output interconnect, the input filters) and applies it in the right order - the elements are configured disabled, then the interconnect, then the array is enabled - so that no glitch reaches the outputs while it is being loaded.
  • The module also helps to write the truth tables: it provides named constants for the common functions (PLAY_LUT_AND2, PLAY_LUT_OR2, PLAY_LUT_XOR2, PLAY_LUT_MUX ...) and documents the bit order of the table, so that the logic is readable in the source.
  • The module hides the differences between the families: the number of the elements, the signal lists of the interconnects and the clock sources differ, the interface stays the same.

What the module is not: it is not a logic synthesis tool (the truth tables are given), and it does not simulate the logic (the unit tests evaluate the tables on the host).


Concept​

ItemMeaning
Element (play_ElementId_t)One of the logic elements PLAY_ELEMENT_0 ... _15.
Truth tableA 16-bit value: bit n is the output for the input combination n (the four inputs in the order of the documentation).
Register optionThe output is combinational or registered (PLAY_OUTPUT_COMBINATIONAL / PLAY_OUTPUT_REGISTERED) with the clock of the register.
Input interconnectFor every element input: a source from play_Source_t - a pin (PLAY_SRC_PIN_IN0...), a peripheral signal of the device, the output of an element, a constant, a software controlled bit.
Output interconnectFor every output of the array: the element it comes from, and the destinations - a pin, a peripheral trigger input.
Input conditioningThe synchronization to a clock, the glitch filter, the edge detection and the pulse extension per input.
Software inputsBits written by the software to feed the logic (Play_Set_SoftwareInput) and the flags set by the logic that can interrupt the software.
LockThe configuration is frozen until the reset.

Rules:

  1. Play_Set_Config( config ) is applied in a safe order: the array is disabled, the elements and the interconnects are written and read back, then the array is enabled; a configuration that references an element or a signal the device does not have is rejected before the first register is written.
  2. The software inputs and the flags work while the array runs: Play_Set_SoftwareInput( index, level ) is atomic, Play_Get_Flag and the FlagCallback report the events.
  3. A reconfiguration of a running array is possible element by element only where the hardware allows it (Play_Set_Element); otherwise Play_Set_Config stops the array, rewrites it and starts it again, which produces a short interruption of the outputs.
  4. Play_Set_Lock freezes the configuration until the next reset; every later write returns an error.
  5. The pins used by the array are put into the right mode (the alternate function of the PLAY) by the module, with the lists of the pins of the device.
  6. All parameters are checked before a register is written.

Supported families​

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

FamilyBranchArrayStatus
STM32H5Dev/STM32H5PLAY on the STM32H5E / H5F lines: 16 logic elements (4-input look-up table and a register), input and output interconnects, synchronization and glitch filters with the edge detection and the pulse extension, software inputs, flags with the interrupt, the software lockplanned (first)
STM32U3, STM32U5, STM32H7, STM32G4, STM32L4, STM32F4, STM32F7Dev/STM32U3 ...no programmable logic array on the device - the module is a stub that returns PLAY_REQUEST_ERRORplanned

A function without a meaning in a family stays in the interface, returns PLAY_REQUEST_ERROR and suppresses the unused parameters (for example a source signal the device does not have).


Public interface in short (proposal)​

GroupFunctions
Module managementPlay_Get_ModuleVersion, Play_Init, Play_Deinit, Play_Task, Play_Get_DefaultConfig
ConfigurationPlay_Set_Config, Play_Set_Element, Play_Get_Element, Play_Set_InputConditioning, Play_Set_Lock, Play_Get_LockState
ControlPlay_Set_Active, Play_Set_Inactive, Play_Get_State
Software interfacePlay_Set_SoftwareInput, Play_Get_Output, Play_Get_Flag, Play_Set_FlagClear
InterruptsPlay_Set_IrqPriority / Get, the callbacks are a part of the configuration
PinsPlay_InitInputGpio, Play_InitOutputGpio
play_ModuleVersion_t Play_Get_ModuleVersion ( void );

play_RequestState_t Play_Init ( const play_Config_t * const playConfig );
play_RequestState_t Play_Deinit ( void );
void Play_Task ( void );
play_RequestState_t Play_Get_DefaultConfig ( play_Config_t * const playConfig );

play_RequestState_t Play_Set_Config ( const play_Config_t * const playConfig );
play_RequestState_t Play_Set_Element ( play_ElementId_t elementId, const play_Element_t * const element );
play_RequestState_t Play_Set_Active ( void );
play_RequestState_t Play_Set_Inactive ( void );

play_RequestState_t Play_Set_SoftwareInput ( play_SoftwareInput_t inputId, play_Level_t level );
play_RequestState_t Play_Get_Output ( play_OutputId_t outputId, play_Level_t * const level );
play_RequestState_t Play_Get_Flag ( play_FlagId_t flagId, play_FlagState_t * const flagState );
play_RequestState_t Play_Set_Lock ( void );

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

TypeMeaning
play_Config_tThe element table, the input and the output interconnect tables, the input conditioning, the flags to enable, callbacks, interrupt priority
play_Element_tThe truth table, the inputs (sources), the output option (combinational / registered) and the register clock
play_Source_tThe sources of the device: pins, peripheral signals, element outputs, constants, software inputs
CallbacksFlagCallback( flagId )

Usage​

"Start the conversion when the timer is high and the enable pin is low", latched until the software releases​

#include "Play_Port.h"

play_Config_t playConfig;

(void)Play_Get_DefaultConfig( &playConfig );

/* element 0: out = timerOutput AND NOT enablePin */
playConfig.Element[ PLAY_ELEMENT_0 ].Input[ 0u ] = PLAY_SRC_TIM1_OC1;
playConfig.Element[ PLAY_ELEMENT_0 ].Input[ 1u ] = PLAY_SRC_PIN_IN0;
playConfig.Element[ PLAY_ELEMENT_0 ].Lut = PLAY_LUT_A_AND_NOT_B;

/* element 1: an SR latch set by the element 0, cleared by the software input 0 */
playConfig.Element[ PLAY_ELEMENT_1 ].Input[ 0u ] = PLAY_SRC_ELEMENT_0;
playConfig.Element[ PLAY_ELEMENT_1 ].Input[ 1u ] = PLAY_SRC_SOFTWARE_0;
playConfig.Element[ PLAY_ELEMENT_1 ].Input[ 2u ] = PLAY_SRC_ELEMENT_1; /* its own output: the feedback */
playConfig.Element[ PLAY_ELEMENT_1 ].Lut = PLAY_LUT_SET_RESET_LATCH;

playConfig.Output[ PLAY_OUTPUT_0 ].Source = PLAY_ELEMENT_1;
playConfig.Output[ PLAY_OUTPUT_0 ].Destination = PLAY_DST_ADC_TRIGGER;

(void)Play_Set_Config( &playConfig );
(void)Play_Set_Active();

(void)Play_Set_SoftwareInput( PLAY_SOFTWARE_INPUT_0, PLAY_LEVEL_HIGH ); /* release the latch */

Behaviour and limits​

  • Glitches. The elements are glitch-free in the steady state; a reconfiguration of a running array can glitch the outputs - the module therefore stops the array to reload it.
  • Timing. The delay through an element is a few nanoseconds; the registered paths are clocked by the selected clock; the maximum frequency is in the datasheet.
  • Low power. The array works in the low-power modes where the clocks and the sources it uses run; a wake-up by a flag is possible on the families that route it.
  • Documentation of the logic. The truth table helpers document the bit order of the table; a complex logic should keep its schematic or the equations next to the configuration (the comments in the code).
  • Not part of the first version: the graphical or the text description (HDL) of the logic and the generation of the tables from it, the dynamic partial reconfiguration during the operation, the combination of several arrays.

Dependencies​

  • Rcc - peripheral clock, the register clock sources, reset
  • Nvic - interrupt
  • Gpio - the input and the output pins
  • Tim, Comp, Adc - the producers and the consumers of the signals (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 table helper constants evaluated on the host for every input combination, the configuration application order (disabled, loaded, enabled), the rejected references to missing elements / sources, the software inputs, the flags and the callbacks, the lock.
  • Integration tests (target, probe-rs): the truth tables measured on the pins with a stimulus from the timers and the GPIO, the latch with the software release, the signal routed to a peripheral trigger, the operation in the Stop mode.

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 PLAY_<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. Play_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 Play_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 (play_FunctionState_t, play_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 PLAY_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
Play_Port.h, Play_Types.hPublic interface (identical in all families)
Play*.c, Play.hImplementation of the family
CMakeLists.txtLibrary Play_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 Play_Lib )
  1. Link Play_Lib to your CMake library.
  2. Include Play_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.