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 |
|---|---|
|
Module abbreviation — the standardized short module name (e.g. |
|
Vendor infix — a vendor-specific name (abbreviation allowed). |
|
Vendor API infix — represents the driver functionality (e.g. a HW instance number, or a
target such as |
|
Module implementation prefix — |
|
The module implementation prefix capitalised (e.g. |
|
Internal-file element — an optional suffix for driver-internal files (e.g. |
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 & |
|
|
Development error values |
|
|
Runtime error values |
|
|
Other error values |
|
|
Global variables |
|
|
Global functions |
|
|
Types |
|
|
(<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 — |
|
the interface header |
Without an upper-layer interface stack — |
|
the module’s own public header |
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 |
|---|---|---|
|
Indicate a completed (or partial) reception of received data. |
|
|
Confirm a previously requested transmission has completed. |
|
|
Notify a detected error or fault condition. |
|
|
Report a channel / bus state transition. |
|
|
Signal a detected wake-up event. |
|
|
Report a detected signal edge. |
|
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 inCan_Irq.c).Each driver header — other than the general types header — carries an include guard named after the file (e.g.
MEM_VENDOR_CODE_HforMem_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>.hinstead. It is named<Ma>If_DriverTypes.hfor a module delivered with an upper-layer interface stack, and<Ma>_DriverTypes.hfor 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 — <Mip>"]
MipC["<Mip>.c — implementation"]
MipH["<Mip>.h — public header (API + callout prototypes)"]
CfgC["<Mip>_Cfg.c — generated config"]
CfgH["<Mip>_Cfg.h — generated config header"]
Ie["<Mip>_<Ie>.c / .h — optional internal files"]
end
subgraph iface["With an upper-layer"]
direction LR
IfTypes["<Ma>If_DriverTypes.h — general types (spec only)"]
IfH["<Ma>If.h — callback prototypes (<Ma>If_On*)"]
IfC["<Ma>If.c — interface implementation"]
end
subgraph nostack["Without an upper-layer"]
direction LR
MaTypes["<Ma>_DriverTypes.h — general types (spec only)"]
Stubs["<Mip>_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.