API Reference

Normative

The MCU driver API contract. A conformant driver MUST provide these types and functions with the behavior described. Function and type signatures are extracted from the driver headers with Doxygen/Breathe. Keywords per Requirement Keywords; behavioral rules in Mcu — Requirements; error codes in Errors.

Data types at a glance

Type

Kind

Purpose

Mcu_ConfigType

struct

Root configuration structure (build-time; Mcu_Init takes NULL_PTR).

Mcu_ClockIdType

typedef

Identifier of a clock configuration (index into clock_settings).

API at a glance

Function

Group

Purpose

Mcu_Init

Initialization

Initialize the driver and core HW; capture the reset cause.

Mcu_InitClock

Clock

Apply a clock configuration (non-blocking).

Mcu_IsClockDistributed

Clock

Report whether the clock tree has stabilised and distributed.

Mcu_PollFunction

Clock

Service clock stabilisation / distribution / supervision.

Mcu_GetResetRawValue

Reset

Return the reset cause captured at initialization.

Mcu_PerformReset

Reset

Issue a microcontroller reset.

Expected interfaces at a glance

Integration interfaces the integrator MUST provide where applicable (CHI-MCU-MUST-10, CHI-MCU-MUST-11); all are documented in the general reference. McuDrv defines no callouts — it reports nothing back to the integration code, so it has no Mcu_Callout_Stubs.c.

Function

Kind

Purpose

LogM_Report

Common (optional)

Reports development / runtime errors (e.g. MCU_RTERR_CLOCK) with a log level.

<Mip>_EnterCriticalSection / <Mip>_ExitCriticalSection

Common (optional)

Bracket sections requiring exclusive access — see critical sections.
Data types
Mcu_ConfigType
struct Mcu_ConfigType

Configuration structure type.

Configuration variants are selected at build time; Mcu_Init currently takes NULL_PTR. Available via: Mcu.h

Mcu_ClockIdType
typedef uint8 Mcu_ClockIdType

Represents identifier of clock configuration.

Identifies a clock configuration — its index in the configured clock_settings list. Available via: Mcu_DriverTypes.h

Initialization
Mcu_Init
void Mcu_Init(const Mcu_ConfigType *configPtr)

Initializes the driver and HW.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x00

Development error(s):

Parameters:

configPtr – [in] Pointer to the configuration structure. This parameter is intended for future extensions to support runtime-selectable configuration variants, which allow the selection and initialization of specific variants during runtime. As this functionality is not currently supported, a NULL_PTR SHALL be provided.

Returns:

None.

When to call: once, before any other MCU function, with the driver in MCU_DRV_STATE_UNINIT. configPtr MUST be NULL_PTR.

Effect: initialises the driver and core HW registers (mode, reset management, multi-peripheral registers — not clocks, not I/O pins); captures and clears the reset cause; moves the driver to MCU_DRV_STATE_INIT. Errors: see Errors. Available via: Mcu.h

Clock
Mcu_InitClock
Std_ReturnType Mcu_InitClock(Mcu_ClockIdType clockId)

Initializes the MCU specific clock settings according to the configuration specified by clockId parameter.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x01

Development error(s):

Parameters:

clockId – [in] Identifier of a clock configuration to be applied.

Return values:

  • E_OK – Request has been accepted

  • E_NOT_OK – Request has not been accepted

Returns:

Std_ReturnType.

When to call: after Mcu_Init, to apply the clock configuration clockId. Returns: E_OK if accepted, else E_NOT_OK. It does not busy-wait for stabilisation — drive that from Mcu_PollFunction. Errors: see Errors. Available via: Mcu.h

Mcu_IsClockDistributed
boolean Mcu_IsClockDistributed(void)

Returns the status of clocks.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Service ID [hex]:

0x02

Development error(s):

Parameters:

None –

Return values:

  • TRUE – all clocks that were set by Mcu_InitClock have been stabilized and distributed to the MCU clock tree.

  • FALSE – Clocks have not yet been distributed.

Returns:

boolean.

Effect: returns TRUE once every clock set by Mcu_InitClock has stabilised and been distributed; FALSE while still stabilising. Before Mcu_Init (or after a reset, before Mcu_InitClock) it returns TRUE. Errors: see Errors. Available via: Mcu.h

Mcu_PollFunction
void Mcu_PollFunction(void)

Handle events with polling method.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x05

Parameters:

None –

Returns:

None.

When to call: cyclically — during clock bring-up to drive stabilisation and distribution, and at runtime for any configured clock supervision. Available via: Mcu.h

Reset
Mcu_GetResetRawValue
uint32 Mcu_GetResetRawValue(void)

Returns raw reset reason gathering from the HW.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Service ID [hex]:

0x03

Development error(s):

Parameters:

None –

Returns:

uint32 Bitwise ORed value of the reset reason. Bit meaning depends on used HW.

Effect: returns the reset cause captured by Mcu_Init as a bitwise-ORed uint32 (bit meanings are HW-defined). Returns 0 if called before Mcu_Init, and MCU_RESET_POWER_ON on hardware without reset-reason detection. Errors: see Errors. Available via: Mcu.h

Mcu_PerformReset
void Mcu_PerformReset(void)

Performs a reset operation of the microcontroller. Note that ensuring no preemption during Mcu_PerformReset must be ensured by caller side. (e.g. disabling all interrupts before calling).

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x04

Development error(s):

Parameters:

None –

Returns:

None.

When to call: to reset the microcontroller. The caller MUST ensure no preemption during the call (e.g. disable all interrupts first). Does not return under normal operation. Errors: see Errors. Available via: Mcu.h