Runtime Pin-Ownership Validator. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_port_constants.h"

Include dependency graph for ra8_pin_validator.h:

This graph shows which files directly or indirectly include this file:

Functions
ra8_err_t	ra8_pin_validator_claim (ra8_port_pin_t pin, const char *owner)
	Claim a pin for a driver.
ra8_err_t	ra8_pin_validator_release (ra8_port_pin_t pin)
	Release a pin previously claimed by a driver.
bool	ra8_pin_validator_is_claimed (ra8_port_pin_t pin)
	Test whether a pin is currently claimed.
void	ra8_pin_validator_reset (void)
	Reset the validator (release every pin).

Detailed Description

Runtime Pin-Ownership Validator.

Centralised bookkeeping that prevents two drivers from accidentally claiming the same physical pin. Every driver that touches IOPORT or PFS (Pin Function Select) must call ra8_pin_validator_claim() before configuring the pin. The call returns k_ra8_err_gpio_conflict if anyone else already owns the pin.

How it works

One bit per (port, pin) pair in a static bitmap: 15 ports x 16 pins = 240 bits = 30 bytes.
ra8_pin_validator_claim(pin, owner_tag) atomically sets the bit and records the owner tag.
ra8_pin_validator_release(pin) clears the bit.
ra8_pin_validator_is_claimed(pin) is a read-only query.

When to call

At driver init time, after validating arguments, BEFORE touching any hardware registers. If the claim fails, the driver must return k_ra8_err_gpio_conflict without leaving the peripheral in a half-initialized state.
At driver de-init time, release all owned pins so the same pin can be re-used by another peripheral later.

Thread safety

The bitmap is guarded by an IRQ-masked critical section. Safe to call from any context (init, task body, ISR).

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_pin_validator.h.

Function Documentation

◆ ra8_pin_validator_claim()

ra8_err_t ra8_pin_validator_claim	(	ra8_port_pin_t	pin,
		const char *	owner )

nodiscard

Claim a pin for a driver.

Parameters

[in]	pin	Packed port/pin identifier.
[in]	owner	Short owner tag (e.g. "SCI0", "LED1"). Must point to a static string; the validator stores the pointer, not the contents.

Returns: k_ra8_err_t error code.

Return values

k_ra8_ok	Pin successfully claimed.
k_ra8_err_gpio_invalid_port	Port out of range (0..14).
k_ra8_err_gpio_invalid_pin	Pin out of range within the port.
k_ra8_err_gpio_conflict	Pin already claimed by another owner.

Precondition: ra8_infrastructure_init() has run.

Postcondition: On success, the pin is marked as owned by owner.

Since: 0.1.0

Claim a pin for a driver.

Marks the pin's bit in s_claimed and stores the owner pointer in s_owner.

Parameters

[in]	pin	Packed port/pin identifier.
[in]	owner	String literal naming the claimer; must be non-NULL.

Returns: Error code.

Return values

k_ra8_ok	Pin successfully claimed.
k_ra8_err_null_ptr	owner was NULL.
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.
k_ra8_err_gpio_conflict	Pin already owned.

Precondition: ra8_infrastructure_init() has run.; Caller serialises concurrent claim/release calls.

Postcondition: On success, the pin reads as claimed.; On failure, validator state is unchanged.

Note: Not thread-safe with respect to other claim/release callers.

Since: 0.1.0

Definition at line 94 of file ra8_pin_validator.c.

References internal_flat_index(), k_ra8_bits_per_byte, k_ra8_err_gpio_conflict, k_ra8_ok, owner, pin, RA8_CHECK_NULL_PTR, ra8_log_error, s_claimed, s_owner, and s_tag.

Referenced by internal_claim(), and ra8_pfs_route_peripheral().

◆ ra8_pin_validator_is_claimed()

bool ra8_pin_validator_is_claimed ( ra8_port_pin_t pin )

Test whether a pin is currently claimed.

Reads the bitmap maintained by claim/release. Out-of-range identifiers report false rather than an error.

Parameters

[in] pin Packed port/pin identifier.

Returns: true if claimed, false if free or if pin is out of range.

Return values

true	The pin is currently owned by some driver.
false	The pin is free OR the identifier is out of range.

Precondition: ra8_infrastructure_init() has run.; pin is the result of RA8_PIN_PACK(port, pin) or 0.

Postcondition: No internal state modified.; Result reflects the bitmap at the moment of the call.

Note: Best-effort read; result may be stale on return. Thread-safe vs other readers; not safe vs concurrent claim/release.

Since: 0.1.0

Test whether a pin is currently claimed.

Out-of-range identifiers quietly report false.

Parameters

[in] pin Packed port/pin identifier.

Returns: true if claimed, false otherwise.

Return values

true	Pin is owned.
false	Pin is free OR identifier is invalid.

Precondition: ra8_infrastructure_init() has run.; Caller tolerates a best-effort read.

Postcondition: No state modified.; Result reflects the bitmap at the moment of the call.

Note: Thread-safe vs other readers; not safe vs concurrent writers.

Since: 0.1.0

Definition at line 174 of file ra8_pin_validator.c.

References internal_flat_index(), k_ra8_bits_per_byte, k_ra8_ok, pin, and s_claimed.

◆ ra8_pin_validator_release()

ra8_err_t ra8_pin_validator_release ( ra8_port_pin_t pin )

nodiscard

Release a pin previously claimed by a driver.

Parameters

[in] pin Packed port/pin identifier.

Returns: k_ra8_ok on success, k_ra8_err_* on invalid arguments.

Since: 0.1.0

Release a pin previously claimed by a driver.

Clears the pin's bit in s_claimed and zeroes its owner.

Parameters

[in] pin Packed port/pin identifier.

Returns: Error code.

Return values

k_ra8_ok	Pin released (or was already free).
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.

Precondition: ra8_infrastructure_init() has run.; Caller serialises concurrent claim/release calls.

Postcondition: On success, the pin reads as free.; Owner pointer for the pin is nullptr.

Note: Not thread-safe with respect to other claim/release callers.

Since: 0.1.0

Definition at line 138 of file ra8_pin_validator.c.

References internal_flat_index(), k_ra8_bits_per_byte, k_ra8_ok, pin, s_claimed, and s_owner.

Referenced by ra8_gpio_attach_irq(), ra8_gpio_detach_irq(), ra8_gpio_input_init(), ra8_gpio_output_init(), ra8_gpio_release(), and ra8_pfs_route_peripheral().

◆ ra8_pin_validator_reset()

void ra8_pin_validator_reset ( void )

Reset the validator (release every pin).

Called exactly once during ra8_infrastructure_init(). Clears the claim bitmap and parallel owner-tag array.

Precondition: Called exactly once during early infrastructure bring-up.; All driver state referencing pin claims has been torn down.

Postcondition: Every pin reads as free.; Every owner tag pointer is nullptr.

Note: Not thread-safe; one-shot init only.

Since: 0.1.0

Reset the validator (release every pin).

Zeroes the claim bitmap and the owner array.

Precondition: Called exactly once during early init.; No other code is currently inspecting validator state.

Postcondition: Every pin reads as free.; Every owner pointer is nullptr.

Note: Not thread-safe; one-shot init only.

Since: 0.1.0

Definition at line 201 of file ra8_pin_validator.c.

References k_ra8_pin_count, k_ra8_port_count, s_claimed, and s_owner.

Referenced by ra8_infrastructure_init().

Functions

Detailed Description

How it works

When to call

Thread safety

Function Documentation

◆ ra8_pin_validator_claim()

◆ ra8_pin_validator_is_claimed()

◆ ra8_pin_validator_release()

◆ ra8_pin_validator_reset()