The Callout Stub File

Informative

The file an integrator edits to connect their own components to a driver that has no upper-layer interface stack. This page shows the generated skeleton and what each part is for; the binding rules are CHI-GEN-MUST-14, CHI-GEN-MUST-15 and CHI-GEN-MUST-16. Mip / MIP stands in for a concrete module implementation prefix (e.g. I2c, Uart) — substitute your own.

Where this file comes from

A module without an upper-layer interface stack declares its callouts — the functions it calls to report events — in its own public header <Mip>.h, named <Mip>_Callout_On<Event> (see Naming Conventions). The module generator emits one default, empty implementation of each enabled callout into <Mip>_Callout_Stubs.c. You fill in the bodies; the generator keeps what you wrote when it runs again.

The generated skeleton

Two callouts are shown: Mip_Callout_OnReception, enabled by the configuration and filled in, and Mip_Callout_OnError, not currently enabled and therefore excluded from compilation.

/***************************************************************************************************
 *  Chiisai HAL - generated callout stubs
 *  File: Mip_Callout_Stubs.c
 *  Generated by the Mip module generator. Fill in the user code blocks only.
 **************************************************************************************************/

/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!         <USERBLOCK User Version>          DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/

/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!               </USERBLOCK>                DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/

/***************************************************************************************************
 *  INCLUDES
 **************************************************************************************************/
#include "Mip.h"          /* callout prototypes + driver API (CHI-GEN-MUST-14) */
#include "Mip_Cfg.h"      /* generated configuration */

/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!         <USERBLOCK User Includes>         DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/

/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!               </USERBLOCK>                DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/

/***************************************************************************************************
 *  CALLOUT FUNCTIONS
 **************************************************************************************************/
#define MIP_START_SEC_CODE_CALLOUT
#include "Mip_MemMap.h"

FUNC(void, MIP_CODE) Mip_Callout_OnReception(uint8 channelId, uint16 length)
{
/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!    <USERBLOCK Mip_Callout_OnReception>    DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/

    /* your code: hand the received bytes to your own component */
    MyComponent_Consume(channelId, length);

/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!               </USERBLOCK>                DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/
} /* End of Mip_Callout_OnReception */

#define MIP_STOP_SEC_CODE_CALLOUT
#include "Mip_MemMap.h"

#if 0  /* not enabled by the current configuration - the user code below is preserved */

/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!      <USERBLOCK Mip_Callout_OnError>      DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/

/***************************************************************************************************
 * DO NOT CHANGE THIS COMMENT!               </USERBLOCK>                DO NOT CHANGE THIS COMMENT!
 **************************************************************************************************/

#endif

/***************************************************************************************************
 *  END OF FILE: MIP_CALLOUT_STUBS.C
 **************************************************************************************************/

What each piece does

In the file	Why
`#include "Mip.h"`	Brings in the callout prototypes, so the compiler checks each definition against the declaration the driver actually calls (CHI-GEN-MUST-05, CHI-GEN-MUST-14).
`<USERBLOCK Mip_Callout_OnReception>` … `</USERBLOCK>`	The user code block. Everything between the markers is yours and is reproduced verbatim on regeneration; everything outside them is generator-owned. The marker names the callout by its full symbol name — that is how the generator matches your code to a body (CHI-GEN-MUST-16).
`<USERBLOCK User Includes>`	Where your own `#include` directives go, so they also survive regeneration. There is a matching block for a user version string.
`#define MIP_START_SEC_CODE_CALLOUT` / `#include "Mip_MemMap.h"` … `STOP` …	The memory-mapping wrap, using the `SEC_CODE` optional-keyword form so callout code can be placed in its own section (CHI-GEN-MUST-07, CHI-GEN-MUST-08).
`FUNC(void, MIP_CODE)`	The declaration macro applies the memory class portably; the callout signature itself is fixed by the module specification (CHI-GEN-MUST-09).
`#if 0` around `Mip_Callout_OnError`	A callout the active configuration does not enable is still emitted, but excluded from compilation, so code you wrote for it is not lost if the event is later re-enabled (CHI-GEN-MUST-16).

Note

Do not rename the file, move a callout definition out of it, or edit the marker comments — the generator locates your code by those markers. Keep a callout body short and observe the re-entrancy and context notes in the module’s API reference: depending on configuration, a callout may be reached from an interrupt or from the module’s PollFunction.

Warning

Because a marker carries the callout’s full symbol name, renaming a callout in a future revision of a module specification changes its marker. A regeneration would then no longer match your existing block, so such a rename has to be accompanied by a migration of the affected stub files.