Runtime pin-ownership bitmap implementation. More...

#include "ra8_pin_validator.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_bit_constants.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_port_constants.h"

Include dependency graph for ra8_pin_validator.c:

Functions
static ra8_err_t	internal_flat_index (ra8_port_pin_t pin, uint16_t *out_index)
ra8_err_t	ra8_pin_validator_claim (ra8_port_pin_t pin, const char *owner)
	Implementation of ra8_pin_validator_claim().
ra8_err_t	ra8_pin_validator_release (ra8_port_pin_t pin)
	Implementation of ra8_pin_validator_release().
bool	ra8_pin_validator_is_claimed (ra8_port_pin_t pin)
	Implementation of ra8_pin_validator_is_claimed().
void	ra8_pin_validator_reset (void)
	Implementation of ra8_pin_validator_reset().

Variables
static const char *	s_tag = "PINVAL"
static uint8_t	s_claimed [((uint16_t) k_ra8_port_count *(uint16_t) k_ra8_pin_count)/(uint16_t) k_ra8_bits_per_byte]
	Bitmap of claimed pins (1 bit per port/pin).
static const char *	s_owner [(uint16_t) k_ra8_port_count *(uint16_t) k_ra8_pin_count]
	Owner tag for each claimed pin, indexed by flat (port, pin) index.

Detailed Description

Runtime pin-ownership bitmap implementation.

Implements the API defined in ra8_pin_validator.h. Uses a fixed 30-byte bitmap (15 ports x 16 pins x 1 bit) and a parallel owner-tag array so that diagnostics can report which driver currently owns a given pin.

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

Definition in file ra8_pin_validator.c.

Function Documentation

◆ internal_flat_index()

ra8_err_t internal_flat_index	(	ra8_port_pin_t	pin,
		uint16_t *	out_index )

static

Definition at line 53 of file ra8_pin_validator.c.

References k_ra8_err_gpio_invalid_pin, k_ra8_err_gpio_invalid_port, k_ra8_ok, k_ra8_pin_count, k_ra8_port_count, pin, RA8_INTERNAL, RA8_PIN_PIN, and RA8_PIN_PORT.

Referenced by ra8_pin_validator_claim(), ra8_pin_validator_is_claimed(), and ra8_pin_validator_release().

◆ ra8_pin_validator_claim()

ra8_err_t ra8_pin_validator_claim	(	ra8_port_pin_t	pin,
		const char *	owner )

nodiscard

Implementation of ra8_pin_validator_claim().

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 )

Implementation of ra8_pin_validator_is_claimed().

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

Implementation of ra8_pin_validator_release().

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 )

Implementation of ra8_pin_validator_reset().

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().

Variable Documentation

◆ s_claimed

uint8_t s_claimed[((uint16_t) k_ra8_port_count *(uint16_t) k_ra8_pin_count)/(uint16_t) k_ra8_bits_per_byte]

static

Bitmap of claimed pins (1 bit per port/pin).

Index = (port * k_ra8_pin_count) + pin, then split into byte = index / k_ra8_bits_per_byte, bit = index % k_ra8_bits_per_byte.

Note: Size is exactly k_ra8_port_count * k_ra8_pin_count / k_ra8_bits_per_byte bytes = 30.

Definition at line 39 of file ra8_pin_validator.c.

Referenced by ra8_pin_validator_claim(), ra8_pin_validator_is_claimed(), ra8_pin_validator_release(), and ra8_pin_validator_reset().

◆ s_owner

const char* s_owner[(uint16_t) k_ra8_port_count *(uint16_t) k_ra8_pin_count]

static

Owner tag for each claimed pin, indexed by flat (port, pin) index.

NULL means "not claimed". Claim stores the caller-provided string literal pointer; the validator never copies the bytes.

Definition at line 50 of file ra8_pin_validator.c.

Referenced by ra8_pin_validator_claim(), ra8_pin_validator_release(), and ra8_pin_validator_reset().

◆ s_tag

const char* s_tag = "PINVAL"

static

Definition at line 26 of file ra8_pin_validator.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_flat_index()

◆ ra8_pin_validator_claim()

◆ ra8_pin_validator_is_claimed()

◆ ra8_pin_validator_release()

◆ ra8_pin_validator_reset()

Variable Documentation

◆ s_claimed

◆ s_owner

◆ s_tag