Requirements

Normative

The cross-module rules every conformant Chiisai HAL driver MUST satisfy, in addition to its own module requirements. Clustered by severity — expand a cluster below. Keywords per Requirement Keywords; conformance per Conformance. Requirements do not carry individual status — the set-level status applies to all of them. The naming scheme is illustrated in Naming Conventions; the shared types and services are catalogued in the Reference.

Mandatory (MUST) - 16 Requirements

The cross-module conformance contract — an implementation MUST satisfy every requirement here.

Naming

CHI-GEN-MUST-01 — Module implementation prefix

Every implementation-specific symbol MUST be built from a module implementation prefix <Mip> = <Ma>[_<Vi>][_<Ci>] (see Naming Conventions). The optional vendor and API infixes MAY be omitted for a single-instance microcontroller-internal driver.

CHI-GEN-MUST-02 — Symbol naming

Driver symbols MUST follow the scheme in Naming Conventions: enumeration literals and #define directives as <MIP>_<SN>; error values as <MIP>_DEVERR_<EN> (development), <MIP>_RTERR_<EN> (runtime), or <MIP>_ERR_<EN> (other); global variables as <Mip>_<Vn>; global functions as <Mip>_<Fn>; types as <Mip>_<Tn>Type.

Files and packaging

CHI-GEN-MUST-03 — File naming and include guards

File names MUST be case-sensitive and unambiguous (two names MUST differ by more than letter case). Driver implementation files MUST be named <Mip>[_<Ie>]*.*. Every driver header other than the general types header MUST carry an include guard named after the file (e.g. MEM_VENDOR_CODE_H for Mem_Vendor_Code.h).

CHI-GEN-MUST-04 — General types header

Each module MUST publish the types and definitions of its specification in a general types header, and that header MUST contain only the types and definitions specified by the respective driver specification. A module that is delivered with an upper-layer interface stack MUST name this header <Ma>If_DriverTypes.h; a module that has no upper-layer interface stack MUST name it <Ma>_DriverTypes.h.

CHI-GEN-MUST-05 — Include and export discipline

A driver MUST import only the headers required to realise its functionality and MUST export only the information other modules need to use it. A driver MUST include its own header so the toolchain checks declarations against definitions (consistency check).

CHI-GEN-MUST-06 — Package folder structure

Each module package MUST follow the common directory structure (<Mip>/ containing Documentation/, Generator/, and Implementation/ as sibling folders — see Integration Guidelines). Additional sub-folders under <Mip> are allowed.

Memory mapping

CHI-GEN-MUST-07 — Memory mapping mechanism

Each driver file MUST include the memory-mapping header <Mip>_MemMap.h and MUST wrap the declaration/definition of code, variables, and constants between a start-section symbol and a stop-section symbol, each followed by an inclusion of <Mip>_MemMap.h. The memory-mapping header MUST select sections by checking the module-specific allocation keywords.

CHI-GEN-MUST-08 — Memory allocation keywords

Allocation keywords MUST follow these templates, where <PREFIX> = <MIP>[_<OPTIONAL_PREFIX>]: variables — <PREFIX>_{START,STOP}_SEC_VAR_<INIT_POLICY>[_<OPTIONAL_KEYWORD>]_<ALIGNMENT>, with <INIT_POLICY> one of INIT / CLEARED / POWER_ON_CLEARED (extensible); constants — <PREFIX>_{START,STOP}_SEC_CONST[_<OPTIONAL_KEYWORD>]_<ALIGNMENT>; code — <PREFIX>_{START,STOP}_SEC_CODE[_<OPTIONAL_KEYWORD>]. <ALIGNMENT> is a bit-alignment value or UNSPECIFIED.

Shared type and service contract

CHI-GEN-MUST-09 — Standard type system and compiler abstraction

A driver MUST use the shared type system and compiler-abstraction set defined in the Reference: Std_ReturnType with E_OK / E_NOT_OK, STD_ON / STD_OFF, the platform integer and float types, CPU_TYPE / BIT_ORDER / BYTE_ORDER, TRUE / FALSE / NULL_PTR, the memory-class and VAR / CONST / P2VAR / P2CONST / FUNC (…) abstraction macros, and the ComStack types PduIdType / PduInfoType / PduLengthType. The driver MUST NOT redefine these.

CHI-GEN-MUST-10 — Error, logging, and system services

A driver MUST report errors through the shared services defined in the Reference: development and runtime errors via LogM_Report with the appropriate LogM_LogLevel, using its assigned module id. It MUST bracket regions requiring exclusive access with the common critical-section services, define interrupt handlers with the common ISR() macro, and use the standard memory utilities (Std_MemCpy / Std_MemClr / …) where applicable.

Handlers

CHI-GEN-MUST-11 — Interrupt and scheduling handlers

Interrupt handlers MUST be named <Mip>_Interrupt<VectorNr>[<VendorSpecificSuffix>]. If a module specification defines a PollFunction / CyclicFunction, the implementation MUST provide it regardless of configuration (an empty function is acceptable when the corresponding events are interrupt-driven), so integration code stays uniform.

Configuration and documentation

CHI-GEN-MUST-12 — Configuration model

Each driver MUST provide a configuration model file, a generator script, and code templates. The model root MUST be <Mip>Model with a single general section and a config_set list. Model classes MUST use UpperCamelCase, properties snake_case, and enum values SNAKE_CASE; vendor- or hardware-specific properties MUST carry an ext_ prefix.

CHI-GEN-MUST-13 — Module documentation

Each module MUST provide documentation covering: a cover sheet and change history; a navigable table of contents; a functional overview; the source-file list; deviations to the specification; used resources (interrupts, peripherals); API, integration, and configuration descriptions (parameter, description, unit, valid range, default, relations). Where the implementation depends on a microcontroller, it MUST also state the µC vendor / family / derivative / stepping, the toolchain name, version, and options, and the used register list.

Callouts

CHI-GEN-MUST-14 — Callout definitions

Where a module defines a callout to be implemented by the user, the toolchain MUST generate a default implementation (marked as user-update code that the generator MUST NOT overwrite), and the callout prototype MUST be available via the module public header <Mip>.h. The generated file and its user-code blocks MUST follow CHI-GEN-MUST-16.

CHI-GEN-MUST-15 — Callout function naming

A callout is a function that the driver calls and the integrator implements. Every callout MUST carry the Callout infix directly after the module implementation prefix, so that a callout is identifiable as such from its name alone: a callout that notifies an event MUST be named <Mip>_Callout_On<Event>, where <Event> names the event being signalled (for example I2c_Callout_OnReception); a callout that requests an action of the integration code, rather than notifying it of something that already happened, MUST be named <Mip>_Callout_<Action> (for example Spi_Callout_CsControl, by which the driver asks the integration code to assert or release a GPIO chip select). Where two modules signal the same kind of event, they MUST reuse the same <Event> name, so that a callout’s role is recognisable regardless of which driver raises it; the common set is illustrated in Naming Conventions. This scheme applies to a module that has no upper-layer interface stack. A module that is delivered with an upper-layer interface stack MUST instead name the functions it reports through <Ma>If_On<Event>, which the interface stack — not the integrator — implements. Because the infix is reserved, a function named <Mip>_On<Event> without it is not a callout. A module MAY provide such a function as an inbound notification service, which the integration code calls to notify the driver of an event the hardware cannot report itself (for example Spi_OnCs, notifying a chip-select edge detected outside the driver). Such a service is part of the driver API, carries a service id, and MUST be documented among the module’s services — not among its callouts.

CHI-GEN-MUST-16 — Callout stub file

The toolchain MUST emit the generated default callout implementations of a module into a single file named <Mip>_Callout_Stubs.c. Within it: each callout body MUST contain a user-code block whose delimiting markers identify the callout by its full symbol name, and the generator MUST reproduce the content of every such block unchanged on regeneration; the file MUST additionally provide a user-code block for user includes; a callout that the active configuration does not enable MUST be retained in the file but excluded from compilation (e.g. within #if 0), so that user code written for it survives a configuration change; each callout definition MUST use the FUNC() declaration macro (CHI-GEN-MUST-09) and MUST be wrapped in a code-section pair per CHI-GEN-MUST-07 and CHI-GEN-MUST-08, using the optional-keyword form <MIP>_{START,STOP}_SEC_CODE_CALLOUT.

Recommended (SHOULD) - 3 Requirements

Strongly advised; an implementation that deviates should understand the implications.

Instances and vendor differentiation

CHI-GEN-SHOULD-01 — Multiple driver instances

If multiple instances of a driver are required (e.g. an internal and an external watchdog), each instance SHOULD use the optional vendor / API infixes of the naming convention to avoid symbol conflicts. External-hardware drivers in particular SHOULD use the infixes.

CHI-GEN-SHOULD-02 — Vendor infixes

The vendor infix <Vi> SHOULD be a vendor-specific name (abbreviation allowed); the vendor API infix <Ci> SHOULD represent the driver’s functionality (e.g. a HW instance number, or a target such as CodeFlash / DataFlash).

Memory mapping

CHI-GEN-SHOULD-03 — Memory-mapping generation and imported software

The configurator SHOULD support generation of the memory-mapping file. If a driver imports other software (e.g. an existing library), that software SHOULD be able to address the same memory sections as the driver (via its own memory-mapping mechanism or a linker directive).