HSEM MCAL Module
Supported STM32 families: H7
Not supported: F4, F7, G4, H5, L4, U3, U5
This module provides an abstraction layer for the hardware semaphores (HSEM) of STM32 MCUs: lock (2-step and 1-step), release, the owner of a semaphore, the release of all semaphores of a core and the notification of the release by an interrupt. It is a low-level MCAL module: it owns the HSEM hardware, the other modules (startup, middlewares, applications of both cores) use it for the synchronization of the cores and do not touch the HSEM registers.
The public interface (Hsem_Port.h, Hsem_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 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
- The dual-core STM32H7 lines (STM32H745 / H747 / H755 / H757) run a firmware on the Cortex-M7 and another one on the Cortex-M4. Every core has its own project; the cores share the memories and the peripherals. They need an atomic mechanism to synchronize the start (the core that does not configure the system waits until the system core has configured the supply and the clocks), to protect shared resources (a shared peripheral, a mailbox in shared RAM) and to signal events to the other core.
- The HSEM provides 32 semaphores that can be locked atomically by a core (and by a process of the core) and that generate an interrupt on the other core when they are released. The single-core STM32H7 lines have the HSEM too (synchronization of processes, interrupt on release).
- The module hides the register protocol (COREID of the bus master, PROCID, the read lock register, the clear key) and the interrupt registers of the current core.
What the module is not: it does not allocate shared memory (the memory shared by the cores is defined by the project linker script) and it does not decide which semaphore is used for what - the meaning of a semaphore is agreed by the firmwares of the cores.
Concept
| Item | Meaning |
|---|---|
| Semaphore | One of 32 semaphores HSEM_SEMAPHORE_0 .. HSEM_SEMAPHORE_31 (hsem_SemaphoreId_t). Free or locked; a locked semaphore has an owner. |
| Owner | The core that locked the semaphore (hsem_CoreId_t: HSEM_CORE_CM7, HSEM_CORE_CM4) and the process of the core (hsem_ProcessId_t, 0 .. 255). The core is the bus master of the access, it is not given by the caller. |
| 2-step lock | Hsem_Set_Lock( semaphoreId, processId ): the semaphore is written with the core and the process and read back; the lock succeeds only when the semaphore was free. |
| 1-step lock | Hsem_Set_LockFast( semaphoreId ): the semaphore is locked by a read of the read lock register; process 0. Not for several processes of one core (they all read the semaphore as their own). |
| Release | Hsem_Set_Release( semaphoreId, processId ): only the owner (the same core and process) releases the semaphore; a release by another core or process is rejected and the semaphore stays locked. |
| Release of a core | Hsem_Set_ReleaseCore( coreId ): all semaphores locked by a core are released at once (clear register with the key of the module) - recovery when a core stops working. |
| Notification | Hsem_Set_NotificationActive( semaphoreId ): the release of the semaphore (by any core) generates the interrupt of the current core, the module calls the release callback of the configuration with the semaphore id. |
Rules:
- Every function checks its parameters and the state of the module before it touches a register; a function of a
locked or released semaphore never waits - a lock that fails returns
HSEM_REQUEST_BUSYat once. Hsem_Get_Ownerreads the semaphore register and never the read lock register (a read of the read lock register locks the semaphore).- The interrupt registers are those of the current core (Cortex-M7: interrupt line 1, Cortex-M4: interrupt line 2, single-core lines: interrupt line 1). The notification of a semaphore is a setting of the current core only.
Hsem_Initdoes not change the state of the semaphores (the other core may hold locks);Hsem_Deinitdisables the notifications of the current core and does not release the locks.
Supported families
Every family gets its own story, its own tasks and its own branches Dev/<Family> and Releases/<Family> cut from this
master.
| Family | Branch | HSEM | Status |
|---|---|---|---|
| STM32H7 | Dev/STM32H7 | 32 semaphores; dual-core STM32H745 / H747 / H755 / H757: interrupt line per core (HSEM1 Cortex-M7, HSEM2 Cortex-M4), single-core lines: HSEM1; STM32H7R / H7S: no HSEM | planned (first) |
On a device without the HSEM (no HSEM in the CMSIS device header, for example STM32H7R / H7S) every function keeps
its signature and returns HSEM_REQUEST_ERROR (Hsem_Get_ModuleVersion returns the version).
Public interface in short (proposal)
| Group | Functions |
|---|---|
| Module management | Hsem_Get_ModuleVersion, Hsem_Init, Hsem_Deinit, Hsem_Task, Hsem_Get_DefaultConfig |
| Lock and release | Hsem_Set_Lock, Hsem_Set_LockFast, Hsem_Set_Release, Hsem_Set_ReleaseCore, Hsem_Get_Owner |
| Notification | Hsem_Set_NotificationActive, Hsem_Set_NotificationInactive, Hsem_Get_NotificationState |
| Interrupt | Hsem_Set_IrqPriority, Hsem_Get_IrqPriority |
hsem_ModuleVersion_t Hsem_Get_ModuleVersion ( void );
hsem_RequestState_t Hsem_Init ( const hsem_Config_t * const hsemConfig );
hsem_RequestState_t Hsem_Deinit ( void );
void Hsem_Task ( void );
hsem_RequestState_t Hsem_Get_DefaultConfig ( hsem_Config_t * const hsemConfig );
hsem_RequestState_t Hsem_Set_Lock ( hsem_SemaphoreId_t semaphoreId, hsem_ProcessId_t processId );
hsem_RequestState_t Hsem_Set_LockFast ( hsem_SemaphoreId_t semaphoreId );
hsem_RequestState_t Hsem_Set_Release ( hsem_SemaphoreId_t semaphoreId, hsem_ProcessId_t processId );
hsem_RequestState_t Hsem_Set_ReleaseCore ( hsem_CoreId_t coreId );
hsem_RequestState_t Hsem_Get_Owner ( hsem_SemaphoreId_t semaphoreId, hsem_Owner_t * const owner );
hsem_RequestState_t Hsem_Set_NotificationActive ( hsem_SemaphoreId_t semaphoreId );
hsem_RequestState_t Hsem_Set_NotificationInactive ( hsem_SemaphoreId_t semaphoreId );
hsem_RequestState_t Hsem_Get_NotificationState ( hsem_SemaphoreId_t semaphoreId, hsem_FunctionState_t * const state );
hsem_RequestState_t Hsem_Set_IrqPriority ( hsem_IrqPrio_t irqPrio );
hsem_RequestState_t Hsem_Get_IrqPriority ( hsem_IrqPrio_t * const irqPrio );
| Type | Meaning |
|---|---|
hsem_RequestState_t | HSEM_REQUEST_OK, HSEM_REQUEST_ERROR (invalid parameter, module not initialized, no HSEM), HSEM_REQUEST_BUSY (lock failed - the semaphore is locked by another core or process) |
hsem_SemaphoreId_t | HSEM_SEMAPHORE_0 .. HSEM_SEMAPHORE_31, HSEM_SEMAPHORE_CNT |
hsem_CoreId_t | HSEM_CORE_CM7, HSEM_CORE_CM4 (dual-core lines), HSEM_CORE_NONE (owner of a free semaphore) |
hsem_ProcessId_t | Process of the core, 0 .. 255 (8-bit PROCID) |
hsem_Owner_t | Locked (flag), Core (hsem_CoreId_t), Process (hsem_ProcessId_t) |
hsem_Config_t | ReleaseCallback (called from the interrupt with the released semaphore, HSEM_NULL_PTR - no interrupt), IrqPriority |
Hsem_Task() is the common Init / Deinit / Task interface of the MCAL modules; the module is event driven and does
not need it (return;).
Usage
Start synchronization of the cores
/* system core (Cortex-M7), after the supply and the clocks are configured: semaphore 0 locked = system ready */
(void)Hsem_Set_Lock( HSEM_SEMAPHORE_0, SYSTEM_READY_PROCESS );
/* other core (Cortex-M4): waits until the system core holds semaphore 0 (bounded loop) */
hsem_Owner_t owner = { .Locked = HSEM_FLAG_INACTIVE, .Core = HSEM_CORE_NONE, .Process = 0u };
for( uint32_t idx = 0u;
( WAIT_LIMIT > idx ) &&
( HSEM_CORE_CM7 != owner.Core );
idx++ )
{
(void)Hsem_Get_Owner( HSEM_SEMAPHORE_0, &owner );
}
Shared resource
if( HSEM_REQUEST_OK == Hsem_Set_Lock( HSEM_SEMAPHORE_1, MAILBOX_PROCESS ) )
{
/* exclusive access to the mailbox in shared RAM */
(void)Hsem_Set_Release( HSEM_SEMAPHORE_1, MAILBOX_PROCESS );
}
else
{
/* locked by the other core - try again later */
}
Event to the other core
/* receiving core: release of semaphore 2 calls the release callback of the configuration */
(void)Hsem_Set_NotificationActive( HSEM_SEMAPHORE_2 );
/* sending core: lock and release - the release generates the interrupt of the receiving core */
(void)Hsem_Set_LockFast( HSEM_SEMAPHORE_2 );
(void)Hsem_Set_Release( HSEM_SEMAPHORE_2, 0u );
Behaviour and limits
- No waiting. The lock functions return at once; a loop around them is the decision of the caller.
- 1-step lock. Process 0 only, not for several processes of one core (the read lock returns the lock of the core to every process).
- Release of a core.
Hsem_Set_ReleaseCorereleases the semaphores of any core, the other core included - for recovery only. The notifications of the released semaphores are generated. - Clock.
Hsem_Initenables the HSEM clock of the current core (RCC),Hsem_Deinitdisables it for the current core only (the clock of the other core stays). - Not part of the first version: the HSEM interrupt as a wake-up event from the low-power modes (event mode), the check of the AHB bus master ID of other bus masters than the cores.
Repository layout and branches
The master holds this README and the license. The family branches (Dev/<Family>, Releases/<Family>) hold:
| Path | Content |
|---|---|
README.md | README of the family: specifics, status |
Hsem_Port.h, Hsem_Types.h | Public interface (identical in all families) |
Hsem*.c, Hsem.h, Hsem_Reg.c/.h | Implementation of the family, private register access |
CMakeLists.txt | Library Hsem_Lib of the EmBi platform |
Tests/UnitTests | Unit tests (Unity + CMock + RegMem) |
Tests/IntegrationTests | Integration tests on the target (probe-rs) |
A change of the public interface is made in all families.
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
- Mr.Nobody - embedbits.com
Contributions are welcome! Please open a pull request.