Can — Requirements

Normative

Defines what a conformant CAN driver MUST do. Requirements are clustered by severity so the essential contract is read first — 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. Exact signatures, error codes, and configuration properties are in the API Reference, Errors, and Configuration Reference pages.

Mandatory (MUST) - 26 Requirements

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

Lifecycle and State Handling

CHI-CAN-MUST-01 — Driver lifecycle

The driver MUST power up in CAN_DRV_STATE_UNINIT. Can_Init MUST move it to CAN_DRV_STATE_INIT after initializing every channel; Can_DeInit MUST return it to CAN_DRV_STATE_UNINIT.

CHI-CAN-MUST-02 — Channel state machine

Each channel MUST follow the state machine in Concepts. Can_Init MUST leave every channel in CAN_CH_STATE_STOPPED; Can_DeInit MUST leave every channel in CAN_CH_STATE_UNINIT. Can_SetChannelState MUST perform the STARTED / STOPPED / SLEEP transitions, configuring the hardware so the channel does or does not participate in the network accordingly, and MUST detect and reject invalid transitions. Where the hardware has no sleep state, a SLEEP→STOPPED request MUST leave the (already stopped) channel unchanged.

CHI-CAN-MUST-03 — Asynchronous state transitions

If a transition cannot be confirmed immediately (e.g. it requires status-register polling), Can_SetChannelState MUST NOT block waiting for completion. Can_CyclicFunction MUST poll for completion, and the driver MUST notify the upper layer via CanIf_OnChannelState when the transition completes (immediately from Can_SetChannelState if it completed synchronously).

CHI-CAN-MUST-04 — Cancel pending messages on leaving the bus

On a transition to CAN_CH_STATE_STOPPED — whether requested via Can_SetChannelState or caused by bus-off / an unrecoverable error — the driver MUST cancel still-pending messages.

Bus Participation

CHI-CAN-MUST-05 — No remote frames

The driver MUST NOT transmit messages in response to remote transmission requests, and MUST configure the CAN hardware to ignore and reject all incoming remote transmission requests.

CHI-CAN-MUST-06 — Bus-off and unrecoverable error handling

On detecting bus-off or an unrecoverable channel error, the driver MUST transition the channel to CAN_CH_STATE_STOPPED, ensure it no longer participates in the network, and notify the upper layer — CanIf_OnError with CAN_ERR_BUS_OFF for bus-off, and LogM_Report for unrecoverable hardware errors. Detection occurs in Can_Interrupt or, in polling mode, Can_CyclicFunction.

CHI-CAN-MUST-07 — No automatic bus-off recovery

The driver MUST disable or suppress any automatic bus-off recovery mechanism; recovery is the upper layer’s responsibility (rationale: Design Decisions).

Transmission

CHI-CAN-MUST-08 — Transmit behavior

When the target TX hardware object is free, Can_Transmit MUST format the ID, length, and data as the hardware requires, copy them into the hardware, initiate transmission, and return E_OK. When the mailbox is busy with another request, Can_Transmit MUST NOT cancel that request, MUST take no action, and MUST return CAN_BUSY.

CHI-CAN-MUST-09 — Transmit data consistency

The driver MUST copy the transmit data directly from the upper-layer buffer. The upper layer is responsible for keeping that buffer consistent until the Can_Transmit operation completes.

CHI-CAN-MUST-10 — Retain PDU id for confirmation

Can_Transmit MUST store the pduId from pduInfoPtr and pass it to CanIf_OnTransmission when the transmission of that request completes.

CHI-CAN-MUST-11 — No software priority emulation

The driver MUST NOT emulate L-PDU priority in software. Priority MUST rely on hardware capability or be managed by the upper layer.

CHI-CAN-MUST-12 — Frame format, ID, and length interpretation

The driver MUST interpret the two most significant bits of Can_PduInfoType.frameId to determine frame and ID type, evaluating the CAN FD bit only when the channel is in CAN FD mode. A frame requested as CAN FD on a non-FD channel MUST be sent as a classic CAN frame. If the requested length is not a valid DLC, the driver MUST use the next higher valid DLC and pad the unused bytes with the configured padding value.

Reception

CHI-CAN-MUST-13 — Reception notification

On receiving an L-PDU, the driver MUST invoke CanIf_OnReception and MUST indicate both the frame type (classic / CAN FD) and the ID type (standard / extended).

CHI-CAN-MUST-14 — Data byte-order mapping

For both transmission and reception, byte n of the CAN payload MUST map to element n of the L-SDU buffer (first byte ↔ element 0). If the hardware byte order differs, the driver MUST rearrange the data so the upper layer always sees this order.

CHI-CAN-MUST-15 — Receive data consistency

The driver MUST guarantee received-data consistency until CanIf_OnReception returns.

CHI-CAN-MUST-16 — Multiple hardware objects per RX mailbox

The driver MUST support an RX mailbox backed by multiple hardware objects, implemented as a hardware FIFO or as multiple identically-configured objects (shadow buffer).

Configuration objects

CHI-CAN-MUST-17 — Mailbox and hardware-object handle configuration

The driver MUST support configuring multiple TX and RX mailboxes, where each mailbox consists of one or more hardware object handles (HOHs).

Events, Notifications, and Scheduling

CHI-CAN-MUST-18 — Configurable event handling mode

For each channel, the driver MUST support selecting interrupt or polling handling independently for transmit, reception, and bus-off/error events. Can_Init MUST enable the interrupt for events configured as interrupt and disable it for events configured as polling.

CHI-CAN-MUST-19 — Upper-layer notifications

The driver MUST notify the upper layer of completed transmissions (CanIf_OnTransmission), receptions (CanIf_OnReception), channel-state changes (CanIf_OnChannelState), and errors (CanIf_OnError). Each notification MUST be issued from Can_Interrupt or, in polling mode, from the appropriate scheduling function.

CHI-CAN-MUST-20 — Scheduling functions

The driver MUST provide Can_PollFunction for high-frequency TX/RX event polling and Can_CyclicFunction for bus-off, other unrecoverable errors, and state-transition polling. Either MAY be an empty function when no corresponding event is configured for polling.

Errors

CHI-CAN-MUST-21 — Development error detection

When development error reporting is enabled, each API MUST detect and report the invalid conditions listed for it in Errors (e.g. use before init, invalid channel or mailbox id, null pointer, invalid length, invalid state transition).

CHI-CAN-MUST-22 — Runtime and unrecoverable error reporting

The driver MUST report unrecoverable hardware errors via LogM_Report, using the log level to distinguish error categories. Detection occurs in Can_Interrupt or, in polling mode, Can_CyclicFunction.

API, Types and Interfaces

CHI-CAN-MUST-23 — API surface and behavior

The driver MUST provide the functions specified in API Reference — Can_Init, Can_DeInit, Can_Transmit, Can_GetChannelState, Can_SetChannelState, Can_Interrupt, Can_PollFunction, and Can_CyclicFunction — with the behavior, return values, and side effects described there.

CHI-CAN-MUST-24 — Data types

The driver MUST define the types in API Reference (Can_ConfigType, Can_PduInfoType, Can_FrameIdType, Can_MailboxIdType, Can_MessageInfoType, Can_ChannelStateType, Can_ErrorType, and the error/return extensions).

CHI-CAN-MUST-25 — Expected interfaces present

The integrator MUST provide the interfaces the driver calls: CanIf_OnTransmission, CanIf_OnReception, CanIf_OnChannelState, CanIf_OnError, and LogM_Report (plus the optional critical-section services if the implementation uses them). See API Reference → Expected interfaces.

CHI-CAN-MUST-26 — Minimum configuration items

The driver MUST support at least the configuration items in Configuration Reference (general options, configuration set, channel, baudrate, mailbox, and filter properties). Vendor-specific extensions are allowed; the configuration toolchain and file schema are implementation-defined.

Recommended (SHOULD) - 1 Requirement

Strongly advised; ignore only with a clear, understood reason. Not required for conformance.

Runtime Configuration

CHI-CAN-SHOULD-01 — Runtime baudrate switching

Where an application changes bit timing at runtime, the driver SHOULD provide Can_SetBaudrate (gated by the enable_set_baud_rate_api configuration option) to select a preconfigured baudrate set while the channel is in CAN_CH_STATE_STOPPED. See API Reference.

Optional (MAY) - 2 Requirements

Truly optional; consumers must not assume these features are present.

Optional Features

CHI-CAN-MAY-01 — Multiplexed transmission

The driver MAY support multiplexed transmission by assigning multiple hardware objects to a single TX mailbox and using the corresponding hardware mechanism.

CHI-CAN-MAY-02 — Lost-frame detection and reporting

Where the hardware can detect lost frames (overwrite or FIFO overrun), the driver MAY report a lost received frame via LogM_Report with runtime-error level CAN_RTERR_DATALOST.