Port — Requirements

Normative

Defines what a conformant Port driver MUST do. Keywords per Requirement Keywords; conformance per Conformance. Requirements do not carry individual status — the set-level status applies to all of them. Signatures, error codes, and configuration properties are in the API Reference, Errors, and Configuration Reference pages. Cross-module rules (types, error model, naming, memory mapping) are in General.

Mandatory (MUST) - 13 Requirements

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

State machine and lifecycle

CHI-PORT-MUST-01 — State machine

After reset the driver MUST be in PORT_DRV_STATE_UNINIT. Port_Init MUST move it to PORT_DRV_STATE_INIT. The driver is single-instance and has no de-initialization; a pin’s function and direction are fixed once Port_Init has run.

CHI-PORT-MUST-02 — Initialization

Port_Init MUST initialize every configured pin to its configured function mode, direction, and initial output value, without producing glitches or spikes, and MUST disable edge detection on every pin. configPtr MUST be NULL_PTR.

Pin and port access

CHI-PORT-MUST-03 — Read pin and port values

Port_GetPinValue MUST return the addressed pin’s value and Port_GetPortValue MUST return all pins of a port as a uint32 (bit n = pin n). Where the hardware supports direct read-back the value MUST reflect the physical pin, otherwise the latched output value. Undefined pin positions MUST read PORT_PIN_VALUE_LOW, and on a detected error a Get API MUST return PORT_PIN_VALUE_LOW (all-LOW for a port).

CHI-PORT-MUST-04 — Direction semantics of access APIs

The Get APIs MUST work for both input and output pins. The behavior of a Set API on an input pin is implementation-defined and MUST NOT be relied upon by portable callers.

CHI-PORT-MUST-05 — Write and toggle pins

Port_SetPinValue MUST write the given value to the addressed pin and Port_TogglePinValue MUST invert it and return the new value. All Set APIs MUST be thread-safe (e.g. via an atomic manipulation or a HW read-modify-write protection).

CHI-PORT-MUST-06 — Masked port write

Port_SetMaskedPortValue MUST write value & mask to the port, modifying only the pins selected by mask and leaving the others unchanged. PORT_PIN_MASK_ALL MUST select every pin in the port.

Edge detection

CHI-PORT-MUST-07 — Edge-detection configuration

Port_SetEdgeDetection MUST set the addressed pin’s edge-detection mode to the requested Port_EdgeConfigType value (none / rising / falling / both). Detection starts disabled after Port_Init.

CHI-PORT-MUST-08 — Edge event notification

On a configured pin edge the driver MUST call Port_Callout_OnEdgeDetection with the pin id. Port_Interrupt MUST handle the edge event for interrupt pins.

CHI-PORT-MUST-09 — Poll function

Port_PollFunction MUST provide the same edge-event handling as Port_Interrupt by polling the hardware, for pins configured for polling.

Symbols, types, errors, and configuration

CHI-PORT-MUST-10 — Port and pin id symbols

A pin id MUST be a uint16 with the port id in the upper 8 bits and the pin index in the lower 8 bits. The driver MUST generate, in the configuration header, the default port symbols PORT_PORT_P<port> and pin symbols PORT_PIN_P<port>_<pin>, and — where a port_name / pin_name is configured — the alias symbols PORT_PORT_<name> / PORT_PIN_<name>.

CHI-PORT-MUST-11 — Development error detection

When development error reporting is enabled, each API MUST detect the conditions listed in Errors and report them via LogM_Report (CHI-GEN-MUST-10).

CHI-PORT-MUST-12 — Public types and error identifiers

The driver MUST provide Port_ConfigType, Port_PinValueType (with PORT_PIN_VALUE_LOW / PORT_PIN_VALUE_HIGH), Port_EdgeConfigType, PORT_PIN_MASK_ALL, and the development error identifiers as defined in API Reference and Errors, MUST call Port_Callout_OnEdgeDetection as defined there, and MUST use the shared type system from General (CHI-GEN-MUST-09).

CHI-PORT-MUST-13 — Configuration model

The driver MUST support the configuration model in Configuration Reference — a General section and a ConfigSet with a port list, each port holding a pin list — following the common model in General (CHI-GEN-MUST-12).