How to Read This Specification

Informative

This page explains how the specification is organized. It does not itself impose any requirement on a driver implementation.

Chiisai HAL is a hardware-abstraction standard for small, cost-sensitive MCUs. It is written to be read and implemented — primarily by silicon vendors building a driver, and secondarily by application developers consuming one.

The Three Tiers

Each driver module is organized into three tiers, plus connective material (overview, concepts, design decisions):

Tier

Audience

What it contains

Guide

Application developers

Informative. How upper-layer software uses the driver — quickstart, configuration, and task-oriented pages organized by capability (initialize, transmit, receive, …).

Reference

Both

The precise API and configuration surface. API pages are extracted from the driver headers so code and documentation stay in sync.

Requirements

Silicon vendors

Normative. The behavioral contract as traceable requirements, clustered by severity.

A reader can follow a single capability — for example transmit — from its guide page, to the relevant API reference block, to the requirement IDs that govern it, via cross-links.

Normative vs. Informative

Every page declares which kind of content it is:

Normative

Defines what a conformant driver MUST do. Requirement keywords follow Requirement Keywords. Normative content appears on Reference and Requirements pages.

Informative

Shows how upper-layer software uses the driver. It does not constrain how a driver is implemented internally. Informative content appears on Overview, Concepts, Guide, and Design Decisions pages.

The guiding rule for normative content: a requirement describes what the driver must do from the outside, never how to write it on the inside. Implementation rationale lives in Design Decisions.

Requirements, IDs, and status

  • Requirements carry short, stable identifiers of the form CHI-<MODULE>-<BAND>-<NN> (for example CHI-CAN-MUST-01), where <BAND> is the severity — MUST, SHOULD, or MAY — and <NN> numbers the requirements within that band consecutively from 01, independently per module. One identifier corresponds to one functional rule, not to each sentence.

  • Within a module, requirements are grouped under Mandatory (MUST), Recommended (SHOULD), and Optional (MAY) so the essential contract is read first. See Requirement Keywords.

  • The specification set carries a single lifecycle status (draft → approved → released); individual requirements do not repeat it.

  • Conformance is defined once, in Conformance.