Using the Shared Contract

Informative

How the shared types, compiler-abstraction macros, memory mapping, logging, and the ISR() macro come together in a driver source file. In the examples, Mip / MIP stands in for a concrete module implementation prefix (e.g. Can, Mem) — substitute your own.

A driver source file, end to end

The skeleton below wires up the pieces a typical driver uses: it includes its own header, declares a variable and code in named memory sections, uses the type system and declaration macros, reports a development error through the Log Manager, and defines an interrupt handler with the ISR() macro.

#include "Mip.h"            /* own header — enables the consistency check (CHI-GEN-MUST-05) */
#include "Std_Types.h"      /* Std_ReturnType, E_OK / E_NOT_OK */
#include "LogM.h"           /* LogM_Report */
#include "Os.h"             /* ISR() macro */

/* --- a module-global variable, placed in a "cleared 32-bit" RAM section --- */
#define MIP_START_SEC_VAR_CLEARED_32
#include "Mip_MemMap.h"
static VAR(uint32, MIP_VAR_CLEARED) Mip_Counter;
#define MIP_STOP_SEC_VAR_CLEARED_32
#include "Mip_MemMap.h"

/* --- driver code, placed in the module code section --- */
#define MIP_START_SEC_CODE
#include "Mip_MemMap.h"

FUNC(Std_ReturnType, MIP_CODE) Mip_DoSomething(VAR(uint8, AUTOMATIC) value)
{
    if (value == 0u)
    {
        /* wrong usage → development error, reported and rejected */
        LogM_Report(LOGM_LOG_LEVEL_DEVERR, MIP_MODULE_ID, 0u,
                    MIP_API_DO_SOMETHING, MIP_DEVERR_PARAM_VALUE);
        return E_NOT_OK;
    }

    Mip_Counter += value;
    return E_OK;
}

#define MIP_STOP_SEC_CODE
#include "Mip_MemMap.h"

/* --- interrupt handler, defined portably with the ISR() macro --- */
ISR(Mip_Interrupt0)
{
    Mip_EnterCriticalSection();   /* keep the exclusive region short */
    /* ... touch shared state ... */
    Mip_ExitCriticalSection();
}

What each piece does

In the code	Why
`#include "Mip.h"`	A driver includes its own header so the compiler checks declarations against definitions (CHI-GEN-MUST-05).
#define MIP_START_SEC_* `` / ``#include "Mip_MemMap.h" … `STOP` …	The memory-mapping wrap: everything between the start and stop symbols is placed in the selected section (CHI-GEN-MUST-07, CHI-GEN-MUST-08). The section keyword names the init policy (`INIT` / `CLEARED` / `POWER_ON_CLEARED`) and alignment.
`VAR(uint32, MIP_VAR_CLEARED)` / `FUNC(Std_ReturnType, MIP_CODE)`	Declaration macros apply the memory/pointer class portably (see declaration macros). Standard types (`uint32`, `Std_ReturnType`) are used instead of native C types (CHI-GEN-MUST-09).
`LogM_Report(LOGM_LOG_LEVEL_DEVERR, MIP_MODULE_ID, …)`	Errors are reported through the Log Manager with the module’s id and the right level — here a development error (CHI-GEN-MUST-10; see LogM_Report).
`ISR(Mip_Interrupt0)`	The interrupt handler is defined with the common macro rather than a compiler-specific keyword (CHI-GEN-MUST-11; see the ISR macro).
`Mip_EnterCriticalSection()` / `Mip_ExitCriticalSection()`	Bracket the shared-state access; keep it short (see critical sections).

Note

The exact qualifier order produced by the declaration macros, and whether the memory-mapping sections expand to anything, are target- and compiler-specific — see the generalized headers in Foundation Header Examples.