API Reference

Normative

The Port driver API contract. A conformant driver MUST provide these types and functions with the behavior described. Function and type signatures are extracted from the driver headers with Doxygen/Breathe; only the interrupt handler is hand-framed, because its name is vendor-specific. Keywords per Requirement Keywords; behavioral rules in Port — Requirements; error codes in Errors.

Data types at a glance

Type	Kind	Purpose
Port_ConfigType	struct	Root configuration structure (build-time; Port_Init takes NULL_PTR).
Port_PinValueType	typedef	A pin’s physical value (PORT_PIN_VALUE_LOW / PORT_PIN_VALUE_HIGH).
Port_EdgeConfigType	enum	Edge-detection selection (none / rising / falling / both).

API at a glance

Function	Group	Purpose
Port_Init	Initialization	Apply every pin’s configured function, direction, and value.
Port_GetPinValue	Pin and port access	Read one pin.
Port_SetPinValue	Pin and port access	Write one pin.
Port_TogglePinValue	Pin and port access	Toggle one pin; return the new value.
Port_GetPortValue	Pin and port access	Read all pins of a port.
Port_SetMaskedPortValue	Pin and port access	Write masked pins of a port atomically.
Port_SetEdgeDetection	Edge detection and scheduling	Configure edge detection for a pin.
Port_PollFunction	Edge detection and scheduling	Service edge events for polled pins.
Port_Interrupt	Edge detection and scheduling	Driver interrupt service routine.

Callouts and expected interfaces at a glance

The functions the integrator MUST provide where applicable (CHI-PORT-MUST-08, CHI-PORT-MUST-12); see the Callouts group below. PortDrv has no upper-layer interface stack, so it reports its events through callouts that the integrator implements in the generated Port_Callout_Stubs.c (see The Callout Stub File).

Function	Kind	Purpose
Port_Callout_OnEdgeDetection	Callout	Notifies the integration code of a detected pin edge.
LogM_Report	Common (optional)	Reports development errors with a log level.
<Mip>_EnterCriticalSection / <Mip>_ExitCriticalSection	Common (optional)	Bracket sections requiring exclusive access — see critical sections.

Generated symbols

The configuration generator emits, in the configuration header, the PORT_PORT_P<n> / PORT_PORT_<name> port-id symbols and the PORT_PIN_P<port>_<pin> / PORT_PIN_<name> pin-id symbols (a pin id is (portId << 8) | pinIndex), plus PORT_PIN_MASK_ALL for whole-port writes (CHI-PORT-MUST-10, CHI-PORT-MUST-11). Always address pins/ports through these symbols.

Data types

Port_ConfigType

struct Port_ConfigType

Configuration structure type.

Configuration variants are selected at build time; Port_Init currently takes NULL_PTR. Available via: Port.h

Port_PinValueType

typedef uint8 Port_PinValueType

This type represents the pin physical value.

Range:

PORT_PIN_VALUE_LOW - 0u - Physical pin value low

PORT_PIN_VALUE_HIGH - 1u - Physical pin value high

Values: PORT_PIN_VALUE_LOW (0) and PORT_PIN_VALUE_HIGH (1). Available via: Port_DriverTypes.h

Port_EdgeConfigType

enum Port_EdgeConfigType

Pin edge detection configuration type.

Values:

enumerator PORT_EDGE_CONFIG_NONE = 0x00

Disable pin edge detection

enumerator PORT_EDGE_CONFIG_RISING = 0x01

Enable pin rising edge detection

enumerator PORT_EDGE_CONFIG_FALLING = 0x02

Enable pin falling edge detection

enumerator PORT_EDGE_CONFIG_BOTH = 0x03

Enable pin rising and falling edge detection

Available via: Port_DriverTypes.h

PORT_PIN_MASK_ALL

Pin mask definition. This symbol is intended to be used with Port_SetMaskedPortValue to update all pins in the port.

Defines

PORT_PIN_MASK_ALL (0xFFu)

‘1’ for bit positions where a pin is considered, and ‘0’ for pins that are ignored. For a hardware port with 8 pins, the mask value would be 0xFFu, which considers all available pins on that port.

Use as the mask for Port_SetMaskedPortValue to update every pin in a port. Available via: Port_DriverTypes.h

Initialization

Port_Init

void Port_Init(const Port_ConfigType *configPtr)

Initializes the driver and HW.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x00

Development error(s):

• PORT_DEVERR_INVALID_STATE PortDrv is NOT in PORT_DRV_STATE_UNINIT

• PORT_DEVERR_PARAM_POINTER configPtr is NOT null pointer

Parameters:

configPtr – [in] Pointer to the configuration structure. This parameter is intended for future extensions to support runtime-selectable configuration variants, which allow the selection and initialization of specific variants during runtime. As this functionality is not currently supported, a NULL_PTR SHALL be provided.

Returns:

None.

When to call: once, before any other Port function, with the driver in PORT_DRV_STATE_UNINIT. configPtr MUST be NULL_PTR.

Effect: applies every configured pin’s function mode, direction, and initial value — glitch-free — disables edge detection on every pin, and moves the driver to PORT_DRV_STATE_INIT. Errors: see Errors. Available via: Port.h

Pin and port access

Port_GetPinValue

Port_PinValueType Port_GetPinValue(uint16 pinId)

Returns the value of the specified pin.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Service ID [hex]:

0x01

Development error(s):

• PORT_DEVERR_PARAM_PIN The pin specified by pinId is not configured.

Parameters:

pinId – [in] Pin ID to be addressed

Return values:

The – physical pin value.

Returns:

Port_PinValueType

Effect: returns the pin’s value (physical read-back where supported, otherwise the latched output value); works for input and output pins. Returns PORT_PIN_VALUE_LOW on error. Errors: see Errors. Available via: Port.h

Port_SetPinValue

void Port_SetPinValue(uint16 pinId, Port_PinValueType value)

Sets the pin value to the specified value.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Service ID [hex]:

0x02

Development error(s):

• PORT_DEVERR_PARAM_PIN The pin specified by pinId is not configured.

• PORT_DEVERR_PARAM_PIN_VALUE value is out of range

Parameters:

• pinId – [in] Pin ID to be addressed.

• value – [in] Value to be written.

Returns:

None.

Effect: writes value to the pin (thread-safe). Writing an input pin is implementation-defined. Errors: see Errors. Available via: Port.h

Port_TogglePinValue

Port_PinValueType Port_TogglePinValue(uint16 pinId)

Toggles the pin value (LOW to HIGH, HIGH to LOW).

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Service ID [hex]:

0x05

Development error(s):

• PORT_DEVERR_PARAM_PIN The pin specified by pinId is not configured.

Parameters:

pinId – [in] Pin ID to be addressed.

Returns:

Port_PinValueType Pin value after toggling the pin value.

Effect: flips the pin (LOW↔HIGH) and returns the new value. Errors: see Errors. Available via: Port.h

Port_GetPortValue

uint32 Port_GetPortValue(uint8 portId)

Returns value of all pins in the specified port.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Service ID [hex]:

0x03

Development error(s):

• PORT_DEVERR_PARAM_PORT portId is out of range from used HW setup

Parameters:

portId – [in] Port ID to be addressed.

Return values:

Pin – values in the specified port. Bit n in value represents index n pin value.

Returns:

uint32

Effect: returns all pins of the port as a uint32 (bit n = pin n); undefined pins and the all-error case read PORT_PIN_VALUE_LOW. Errors: see Errors. Available via: Port.h

Port_SetMaskedPortValue

void Port_SetMaskedPortValue(uint8 portId, uint32 value, uint32 mask)

Sets level of output pins in a port with a bitmask.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Service ID [hex]:

0x04

Development error(s):

• PORT_DEVERR_PARAM_PORT portId is out of range from used HW setup

Parameters:

• portId – [in] Port ID to be addressed.

• value – [in] Value assigned to the pins in the specified port. Bit n in value represents index n pin value.

• mask – [in] Mask value that indicates which pins will be modified.

Returns:

None.

Effect: writes value & mask to the port, changing only the masked pins and — where the hardware allows — updating them simultaneously. Use PORT_PIN_MASK_ALL for all pins. Errors: see Errors. Available via: Port.h

Edge detection and scheduling

Port_SetEdgeDetection

void Port_SetEdgeDetection(uint16 pinId, Port_EdgeConfigType edgeConfig)

Sets the pin edge detection functionality.

Sync/Async:

Synchronous

Reentrancy:

Conditionally reentrant (reentrant for different pinId)

Service ID [hex]:

0x06

Development error(s):

• PORT_DEVERR_UNINIT PortDrv is NOT initialized

• PORT_DEVERR_PARAM_PIN The pin specified by pinId is not configured

• PORT_DEVERR_PARAM_EDGE_CONFIG Given edgeConfig selection is not supported

Parameters:

• pinId – [in] Pin ID to be addressed.

• edgeConfig – [in] Edge detection type to be set.

Returns:

None.

Effect: sets the pin’s edge-detection mode (Port_EdgeConfigType). A configured edge triggers Port_Callout_OnEdgeDetection. Errors: see Errors. Available via: Port.h

Port_PollFunction

void Port_PollFunction(void)

This function is called to check an edge detection event via a pin.

Reentrancy:

Non reentrant

Service ID [hex]:

0x08

Parameters:

None –

Returns:

None.

When to call: cyclically, for pins configured for polling. Handles the same edge events as Port_Interrupt. Available via: Port.h

Port_Interrupt

void Port_Interrupt<vectorNr>[<VendorSpecificSuffix>](void)

Effect: the driver interrupt service routine; handles pin-edge events and calls Port_Callout_OnEdgeDetection. Define it with the ISR() macro (see the general reference). Available via: Port.h

Callouts the integrator provides

The driver calls these callouts; the integrator MUST provide them where applicable (CHI-PORT-MUST-08) by filling in the matching user code block in Port_Callout_Stubs.c (see The Callout Stub File). The prototypes are declared in Port.h. LogM_Report and the critical-section services are documented in the general reference.

Port_Callout_OnEdgeDetection

void Port_Callout_OnEdgeDetection(uint16 pinId)

This service notifies an edge detection event detected by a pin.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Parameters:

pinId – [in] The ID of the pin that detects the edge.

Returns:

None.

Notifies the integration code that pin pinId detected a configured edge. Available via: Port.h; implement it in Port_Callout_Stubs.c.