Naming Conventions

The naming scheme and file layout every Chiisai HAL driver follows, so that modules from different vendors look and integrate consistently. These conventions are stated normatively in the Requirements; this page explains and illustrates them.

Notation

Placeholders used throughout the specification:

Token

Meaning

<Ma>

Module abbreviation — the standardized short module name (e.g. Can, Mem, Spi).

<Vi>

Vendor infix — a vendor-specific name (abbreviation allowed).

<Ci>

Vendor API infix — represents the driver functionality (e.g. a HW instance number, or a target such as CodeFlash / DataFlash).

<Mip>

Module implementation prefix — <Ma>[_<Vi>][_<Ci>] in camel case (e.g. Mem_Vendor_Code).

<MIP>

The module implementation prefix capitalised (e.g. MEM_VENDOR_CODE).

<Ie>

Internal-file element — an optional suffix for driver-internal files (e.g. Can_Irq.c).

Module Implementation Prefix

Every implementation-specific symbol is built from a module implementation prefix:

<Mip> = <Ma>[_<Vi>][_<Ci>]

e.g.  Module = Mem, Vi = Vendor, Ci = Code   ->   <Mip> = Mem_Vendor_Code

The bracketed parts are optional. A microcontroller-internal driver is typically assumed to have a single instance, so the vendor/API infixes are often omitted (<Mip> = <Ma>). The vendor infix should be a vendor-specific (possibly abbreviated) name; the vendor API infix should describe the driver’s functionality.

Normative: CHI-GEN-MUST-01, CHI-GEN-SHOULD-02.

Symbol Naming

Symbol kind

Pattern

Example

Enumeration literals & #define

<MIP>_<SN>

CAN_ENUMERATION

Development error values

<MIP>_DEVERR_<EN>

I2C_DEVERR_PARAM_POINTER

Runtime error values

<MIP>_RTERR_<EN>

MEM_RTERR_DATALOST

Other error values

<MIP>_ERR_<EN>

MEM_ERR_UNCLEARED

Global variables

<Mip>_<Vn>

Uart_SpecificVariable

Global functions

<Mip>_<Fn>

I2c_SpecificApi

Types

<Mip>_<Tn>Type

Wdg_External_SpecificType

(<SN> specific name, <EN> error name, <Vn> variable name, <Fn> function name, <Tn> type name.)

Important

Not every type is prefixed with <Mip>. The patterns above name implementation-specific symbols — the ones a driver’s implementation adds — all built from <Mip>. The types the specification itself defines are different: they are standardized across every implementation of a module and are named with the module abbreviation, <Ma>_<Tn>Type (for example Can_FrameIdType). Each module lists them in its API reference, and they are delivered through the general types header <Ma>[If]_DriverTypes.h (see File naming below). Implementation-specific types and error extensions are not put in that header; they belong in <Mip>.h.

Normative: CHI-GEN-MUST-02.

Callout Function Naming

A driver reports events back to its user through functions that the driver calls and its user implements. Where those functions live, and how they are named, depends on whether the module is delivered with an upper-layer interface stack:

Module kind

Pattern

Declared in

With an upper-layer interface stack — Can, Lin, Mem, Wdg

<Ma>If_On<Event>

the interface header <Ma>If.h, and implemented by the interface stack.

Without an upper-layer interface stack — I2c, Mcu, Port, Spi, Uart

<Mip>_Callout_On<Event>

the module’s own public header <Mip>.h. These are callouts: the integrator implements them in the generated <Mip>_Callout_Stubs.c to connect their own components to the driver.

A callout always carries the Callout infix right after the module prefix, so you can tell a callout from a driver service at a glance. After that, both patterns end in On followed by the event being signalled, and the same On<Event> names are used across modules — the event vocabulary is shared:

Event

Purpose

Examples

OnReception

Indicate a completed (or partial) reception of received data.

CanIf_OnReception, Uart_Callout_OnReception

OnTransmission

Confirm a previously requested transmission has completed.

CanIf_OnTransmission, I2c_Callout_OnTransmission

OnError

Notify a detected error or fault condition.

I2c_Callout_OnError

OnChannelState

Report a channel / bus state transition.

CanIf_OnChannelState

OnWakeup

Signal a detected wake-up event.

LinIf_OnWakeup

OnEdgeDetection

Report a detected signal edge.

Port_Callout_OnEdgeDetection

Not every callout notifies an event. A callout by which the driver requests an action of the integration code is named <Mip>_Callout_<Action> — for example Spi_Callout_CsControl, with which the SPI driver asks the integration code to assert or release a GPIO chip select. Reserving On<Event> for notifications — and a plain <Action> name for requests — lets the name alone say what is expected of the integration code: an On name reports an event that has happened, while a name without On asks the integration code to perform an action.

The event list is open — a module names further events by keeping the On<Event> shape (e.g. LinIf_OnHeader, I2c_Callout_OnAddress, Spi_Callout_OnTransactionEnd). A worked callout file is in The Callout Stub File.

Important

Mind the missing infix. A function named <Mip>_On<Event> — with no Callout — is not a callout but an inbound notification service: the integration code calls it to tell the driver about an event the hardware cannot report on its own. Spi_OnCs is one; the integration code detects a chip-select edge and notifies the driver. Such a service is part of the driver’s API and carries a service id, and it is listed among the module’s services rather than its callouts. The infix is what tells the two apart.

Normative: CHI-GEN-MUST-15.

File Naming

  • File names are case-sensitive and unambiguous (two names must differ by more than letter case alone).

  • Driver implementation files are named <Mip>[_<Ie>]*.*; the optional <Ie> part marks driver-internal files (e.g. the CAN ISR implementation lives in Can_Irq.c).

  • Each driver header — other than the general types header — carries an include guard named after the file (e.g. MEM_VENDOR_CODE_H for Mem_Vendor_Code.h).

  • The general types header contains only the standardized types and definitions the respective driver specification defines — named <Ma>_<Tn>Type (e.g. Can_FrameIdType), the same for every implementation of the module; implementation-specific types and error extensions go in <Mip>.h instead. It is named <Ma>If_DriverTypes.h for a module delivered with an upper-layer interface stack, and <Ma>_DriverTypes.h for a module without one — keyed to <Ma> (not <Mip>) so vendor-neutral upper-layer software can include it without knowing which implementation is present (see Design Decisions).

  • A module that defines callouts ships their generated default implementations in <Mip>_Callout_Stubs.c — the file the integrator edits (see The Callout Stub File).

Normative: CHI-GEN-MUST-03, CHI-GEN-MUST-04, CHI-GEN-MUST-16.

Source Files at a Glance

Whether a module ships with an upper-layer interface stack (Can, Lin, Mem, Wdg) or without one (I2c, Mcu, Port, Spi, Uart), the driver’s own files are the same; what differs is where its general types header comes from and who implements the functions the driver reports through.

        %%{init: {"flowchart": {"wrappingWidth": 400}}}%%
flowchart BT
    subgraph driver["Driver — &lt;Mip&gt;"]
        MipC["&lt;Mip&gt;.c — implementation"]
        MipH["&lt;Mip&gt;.h — public header (API + callout prototypes)"]
        CfgC["&lt;Mip&gt;_Cfg.c — generated config"]
        CfgH["&lt;Mip&gt;_Cfg.h — generated config header"]
        Ie["&lt;Mip&gt;_&lt;Ie&gt;.c / .h — optional internal files"]
    end
    subgraph iface["With an upper-layer"]
        direction LR
        IfTypes["&lt;Ma&gt;If_DriverTypes.h — general types (spec only)"]
        IfH["&lt;Ma&gt;If.h — callback prototypes (&lt;Ma&gt;If_On*)"]
        IfC["&lt;Ma&gt;If.c — interface implementation"]
    end
    subgraph nostack["Without an upper-layer"]
        direction LR
        MaTypes["&lt;Ma&gt;_DriverTypes.h — general types (spec only)"]
        Stubs["&lt;Mip&gt;_Callout_Stubs.c — generated; integrator fills the user code blocks"]
    end

    MipC --> MipH
    MipH --> CfgH
    CfgC --> CfgH
    CfgC --> MipH
    MipC -.->|"with an upper-layer"| IfTypes
    MipC -.->|"if callbacks used"| IfH
    MipC -.->|"without an upper-layer"| MaTypes
    Stubs -.->|"implements the callouts declared in"| MipH
    CfgH ~~~ IfTypes
    CfgH ~~~ IfH
    CfgH ~~~ MaTypes
    CfgH ~~~ Stubs
    

Source files of a driver and how they include one another (solid = always, dashed = only for that kind of module). Generated config files come from the module generator. A module with an upper-layer stack takes its general types from <Ma>If_DriverTypes.h and reports through <Ma>If.h; a module without one takes them from <Ma>_DriverTypes.h and declares its callouts in <Mip>.h, which the integrator implements in the generated <Mip>_Callout_Stubs.c. A driver may add <Mip>_<Ie> internal files (e.g. Can_Irq.c).

Include Discipline

  • A driver imports only the headers it needs to realise its functionality, and exports only the information other modules need to use it.

  • A driver imports its own header, so the compiler checks the declarations against the definitions (consistency check).

Normative: CHI-GEN-MUST-05.