Concepts

Informative

The model behind the Port driver: its driver state machine, how pins and ports are addressed, the value model, masked port writes, and how pin edges are detected and reported. Non-binding; the normative rules live in Port — Requirements.

State machine

The PortDrv has a single driver-wide state — there are no channels and no de-init.

        stateDiagram-v2
   [*] --> PORT_DRV_STATE_UNINIT : Reset
   PORT_DRV_STATE_UNINIT --> PORT_DRV_STATE_INIT : Port_Init()

Driver state

Meaning

API calls accepted

PORT_DRV_STATE_UNINIT

Not initialized (state after reset/startup)

Only Port_Init()

PORT_DRV_STATE_INIT

Initialized; all service APIs are accepted

All

Addressing pins and ports

A port is a group of pins in hardware; a pin is one line within a port.

  • A pin id is a uint16 where the upper 8 bits are the port id and the lower 8 bits are the pin index within that port. The generator emits symbolic names into the configuration header: PORT_PIN_P<port>_<pin> (e.g. PORT_PIN_P8_2), plus an alias PORT_PIN_<pin_name> when a pin_name is configured (e.g. PORT_PIN_CAN_PHY_IN).

  • A port id is a uint8. The generator emits PORT_PORT_P<port> (e.g. PORT_PORT_P8), plus an alias PORT_PORT_<port_name> when a port_name is configured (e.g. PORT_PORT_SENSOR).

Always address pins and ports through these generated symbols rather than raw numbers.

Value model

A pin value is Port_PinValueType with two values: PORT_PIN_VALUE_LOW (0) and PORT_PIN_VALUE_HIGH (1). A whole-port value is a uint32 where bit n is the value of pin index n; bits for undefined pins read as PORT_PIN_VALUE_LOW.

  • Reads. Where the hardware supports direct read-back from the physical pin, the Get APIs return the physical level; otherwise they return the latched value in the output register. The Get APIs work for both input and output pins.

  • On error, a Get API returns PORT_PIN_VALUE_LOW (Port_GetPortValue returns all-LOW).

  • Set APIs are thread-safe — realised by an atomic pin manipulation or a GPIO read-modify-write protection mechanism. Writing an input pin is implementation-defined (see Design Decisions).

Masked port writes

Port_SetMaskedPortValue(portId, value, mask) writes value to only the pins selected by mask (it applies value & mask), leaving the other pins untouched — and, where the hardware allows, updates all selected pins simultaneously (even a mix of LOW→HIGH and HIGH→LOW). Use the PORT_PIN_MASK_ALL symbol as the mask to update every pin in the port.

Edge detection and event handling

Edge detection is the one attribute set at runtime. Port_SetEdgeDetection(pinId, edgeConfig) selects none / rising / falling / both (Port_EdgeConfigType); Port_Init disables detection on every pin to start. When a configured edge occurs, the driver reports it via Port_Callout_OnEdgeDetection(pinId) — serviced in one of two modes per pin:

  • Interrupt — Port_Interrupt services the edge event.

  • Polling — Port_PollFunction services the same event by polling the hardware.

Pin manipulation sequence

The informative view of typical PortDrv use — bring pins up, manipulate them, then detect an edge (CHI-PORT-MUST-02, CHI-PORT-MUST-05…CHI-PORT-MUST-09):

        sequenceDiagram
   participant IC as Integration code
   participant INTEG as Integration code
   participant DRV as PortDrv
   participant HW as GPIO HW

   Note over IC,HW: after reset
   IC->>DRV: Port_Init(NULL_PTR)
   activate DRV
   DRV->>HW: apply function/direction/initial value (glitch-free)
   DRV-->>IC: return (state INIT)
   deactivate DRV

   Note over IC,HW: pin manipulation
   INTEG->>DRV: Port_SetPinValue(pinId, value)
   DRV->>HW: write pin
   INTEG->>DRV: Port_GetPinValue(pinId)
   DRV-->>INTEG: pin value

   Note over IC,HW: edge detection
   INTEG->>DRV: Port_SetEdgeDetection(pinId, PORT_EDGE_CONFIG_RISING)
   DRV->>HW: enable edge detection
   HW->>DRV: Port_Interrupt (edge)
   activate DRV
   DRV->>INTEG: Port_Callout_OnEdgeDetection(pinId)
   deactivate DRV

Key terms

For Port terms — port, pin, edge detection, masked write — see the glossary in the appendix and the shared foundation in General.