Preskočiť na hlavný obsah

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​

ItemMeaning
SemaphoreOne of 32 semaphores HSEM_SEMAPHORE_0 .. HSEM_SEMAPHORE_31 (hsem_SemaphoreId_t). Free or locked; a locked semaphore has an owner.
OwnerThe 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 lockHsem_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 lockHsem_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).
ReleaseHsem_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 coreHsem_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.
NotificationHsem_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:

  1. 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_BUSY at once.
  2. Hsem_Get_Owner reads the semaphore register and never the read lock register (a read of the read lock register locks the semaphore).
  3. 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.
  4. Hsem_Init does not change the state of the semaphores (the other core may hold locks); Hsem_Deinit disables 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.

FamilyBranchHSEMStatus
STM32H7Dev/STM32H732 semaphores; dual-core STM32H745 / H747 / H755 / H757: interrupt line per core (HSEM1 Cortex-M7, HSEM2 Cortex-M4), single-core lines: HSEM1; STM32H7R / H7S: no HSEMplanned (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)​

GroupFunctions
Module managementHsem_Get_ModuleVersion, Hsem_Init, Hsem_Deinit, Hsem_Task, Hsem_Get_DefaultConfig
Lock and releaseHsem_Set_Lock, Hsem_Set_LockFast, Hsem_Set_Release, Hsem_Set_ReleaseCore, Hsem_Get_Owner
NotificationHsem_Set_NotificationActive, Hsem_Set_NotificationInactive, Hsem_Get_NotificationState
InterruptHsem_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 );
TypeMeaning
hsem_RequestState_tHSEM_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_tHSEM_SEMAPHORE_0 .. HSEM_SEMAPHORE_31, HSEM_SEMAPHORE_CNT
hsem_CoreId_tHSEM_CORE_CM7, HSEM_CORE_CM4 (dual-core lines), HSEM_CORE_NONE (owner of a free semaphore)
hsem_ProcessId_tProcess of the core, 0 .. 255 (8-bit PROCID)
hsem_Owner_tLocked (flag), Core (hsem_CoreId_t), Process (hsem_ProcessId_t)
hsem_Config_tReleaseCallback (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_ReleaseCore releases the semaphores of any core, the other core included - for recovery only. The notifications of the released semaphores are generated.
  • Clock. Hsem_Init enables the HSEM clock of the current core (RCC), Hsem_Deinit disables 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:

PathContent
README.mdREADME of the family: specifics, status
Hsem_Port.h, Hsem_Types.hPublic interface (identical in all families)
Hsem*.c, Hsem.h, Hsem_Reg.c/.hImplementation of the family, private register access
CMakeLists.txtLibrary Hsem_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.


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.