Multi-function Pin Controller facade implementation. More...

#include "ra8_mpc.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_pfs_regs.h"

Include dependency graph for ra8_mpc.c:

Functions
static ra8_err_t	internal_check (ra8_port_t port, ra8_pin_t pin)
	Bounds-check a (port, pin) pair.
static void	internal_update_pfs (ra8_port_t port, ra8_pin_t pin, uint32_t clear_mask, uint32_t set_mask)
	Update a single field of PmnPFS under PWPR unlock.
static void	internal_reset_pfs (ra8_port_t port, ra8_pin_t pin, uint32_t set_mask)
	All-fields reset + new-fields write under PWPR unlock.
ra8_err_t	ra8_mpc_route_peripheral (ra8_port_t port, ra8_pin_t pin, ra8_mpc_psel_t psel)
	Route a pin to a peripheral function.
ra8_err_t	ra8_mpc_set_gpio (ra8_port_t port, ra8_pin_t pin, ra8_mpc_dir_t dir)
	Reset a pin to plain GPIO with a chosen direction.
ra8_err_t	ra8_mpc_set_analog (ra8_port_t port, ra8_pin_t pin)
	Put a pin in analog-input mode (ASEL = 1).
ra8_err_t	ra8_mpc_set_irq (ra8_port_t port, ra8_pin_t pin)
	Mark a pin as an external IRQ input (ISEL = 1).
ra8_err_t	ra8_mpc_set_pull (ra8_port_t port, ra8_pin_t pin, ra8_mpc_pull_t pull)
	Enable or disable the internal pull-up on a pin.
ra8_err_t	ra8_mpc_set_open_drain (ra8_port_t port, ra8_pin_t pin, bool enable)
	Enable or disable N-channel open-drain on a pin.
ra8_err_t	ra8_mpc_read_pfs (ra8_port_t port, ra8_pin_t pin, uint32_t *out_val)
	Read the raw 32-bit PmnPFS register for diagnostic use.

Variables
static const char *	s_tag = "MPC"

Detailed Description

Multi-function Pin Controller facade implementation.

Tag: [Ring 3 / HAL] {World: S}

Ring 3 / HAL substrate. Owns every write to PmnPFS and the accompanying PWPR unlock/lock sequence. See ra8_mpc.h for the API contract.

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

Definition in file ra8_mpc.c.

Function Documentation

◆ internal_check()

ra8_err_t internal_check	(	ra8_port_t	port,
		ra8_pin_t	pin )

static

Bounds-check a (port, pin) pair.

Returns: k_ra8_ok if both indices are in range, otherwise the appropriate k_ra8_err_gpio_* code.

See implementation.

Parameters

[in]	port	See implementation.
[in]	pin	See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 46 of file ra8_mpc.c.

References k_ra8_err_gpio_invalid_pin, k_ra8_err_gpio_invalid_port, k_ra8_ok, k_ra8_pin_max, k_ra8_port_max, pin, and RA8_INTERNAL.

Referenced by ra8_mpc_read_pfs(), ra8_mpc_route_peripheral(), ra8_mpc_set_analog(), ra8_mpc_set_gpio(), ra8_mpc_set_irq(), ra8_mpc_set_open_drain(), and ra8_mpc_set_pull().

◆ internal_reset_pfs()

void internal_reset_pfs	(	ra8_port_t	port,
		ra8_pin_t	pin,
		uint32_t	set_mask )

static

All-fields reset + new-fields write under PWPR unlock.

Used by the "route" and "set_*" helpers that want to take a pin from whatever state it is in and put it in a clean known state. The register is rewritten from 0 with only the new field bits set; any leftover PSEL / ISEL / ASEL / PDR bits are cleared in the same cycle.

Parameters

[in]	port	See implementation.
[in]	pin	See implementation.
[in]	set_mask	See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 111 of file ra8_mpc.c.

References pin, RA8_INTERNAL, ra8_pfs_pmn(), ra8_pfs_pwpr_lock(), and ra8_pfs_pwpr_unlock().

Referenced by ra8_mpc_set_analog(), ra8_mpc_set_gpio(), and ra8_mpc_set_irq().

◆ internal_update_pfs()

void internal_update_pfs	(	ra8_port_t	port,
		ra8_pin_t	pin,
		uint32_t	clear_mask,
		uint32_t	set_mask )

static

Update a single field of PmnPFS under PWPR unlock.

Read-modify-write the whole 32-bit register with the requested field bits cleared and set. PWPR is unlocked once per call and re-locked unconditionally, including on the no-op path.

Parameters

[in]	port	See implementation.
[in]	pin	See implementation.
[in]	clear_mask	See implementation.
[in]	set_mask	See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 77 of file ra8_mpc.c.

References pin, ra8_pfs_pmn(), ra8_pfs_pwpr_lock(), and ra8_pfs_pwpr_unlock().

Referenced by ra8_mpc_set_open_drain(), and ra8_mpc_set_pull().

◆ ra8_mpc_read_pfs()

ra8_err_t ra8_mpc_read_pfs	(	ra8_port_t	port,
		ra8_pin_t	pin,
		uint32_t *	out_val )

nodiscard

Read the raw 32-bit PmnPFS register for diagnostic use.

Parameters

[in]	port	Port index.
[in]	pin	Pin index.
[out]	out_val	On success, the current PmnPFS value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Value returned.
k_ra8_err_null_ptr	out_val was NULL.
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.

Precondition: out_val is non-NULL.

Postcondition: No hardware state is modified.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 212 of file ra8_mpc.c.

References internal_check(), k_ra8_err_gpio_invalid_pin, k_ra8_ok, pin, RA8_CHECK_NULL_PTR, ra8_pfs_pmn(), and s_tag.

◆ ra8_mpc_route_peripheral()

ra8_err_t ra8_mpc_route_peripheral	(	ra8_port_t	port,
		ra8_pin_t	pin,
		ra8_mpc_psel_t	psel )

nodiscard

Route a pin to a peripheral function.

Unlocks PWPR, writes the pin's PmnPFS register with PMR = 1 and PSEL = psel, then re-locks PWPR. Any stale direction / pull / open-drain bits are cleared in the same write so the caller sees a clean slate.

Parameters

[in]	port	Port index 0..k_ra8_port_max.
[in]	pin	Pin index 0..k_ra8_pin_max.
[in]	psel	Peripheral function from ra8_mpc_psel_t.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Pin routed.
k_ra8_err_gpio_invalid_port	port index out of range.
k_ra8_err_gpio_invalid_pin	pin index out of range.

Precondition: IRQs masked or single-threaded init context.

Postcondition: The target pin is in peripheral mode with the requested PSEL value programmed.; PWPR is re-locked regardless of success.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 122 of file ra8_mpc.c.

References internal_check(), k_ra8_err_gpio_invalid_pin, k_ra8_ok, k_ra8_pfs_bit_psel0, k_ra8_pfs_mask_pmr, k_ra8_pfs_mask_psel, pin, ra8_log_info_val, ra8_pfs_pmn(), ra8_pfs_pwpr_lock(), ra8_pfs_pwpr_unlock(), and s_tag.

◆ ra8_mpc_set_analog()

ra8_err_t ra8_mpc_set_analog	(	ra8_port_t	port,
		ra8_pin_t	pin )

nodiscard

Put a pin in analog-input mode (ASEL = 1).

Parameters

[in]	port	Port index.
[in]	pin	Pin index.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Analog input configured.
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.

Precondition: IRQs masked or single-threaded init context.

Postcondition: PmnPFS: ASEL = 1, PMR = 0, PDR = 0.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 167 of file ra8_mpc.c.

References internal_check(), internal_reset_pfs(), k_ra8_ok, k_ra8_pfs_mask_asel, and pin.

◆ ra8_mpc_set_gpio()

ra8_err_t ra8_mpc_set_gpio	(	ra8_port_t	port,
		ra8_pin_t	pin,
		ra8_mpc_dir_t	dir )

nodiscard

Reset a pin to plain GPIO with a chosen direction.

Parameters

[in]	port	Port index 0..k_ra8_port_max.
[in]	pin	Pin index 0..k_ra8_pin_max.
[in]	dir	Input or output.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Pin reset to GPIO.
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.

Precondition: IRQs masked or single-threaded init context.

Postcondition: PMR = 0, PDR = dir, all peripheral select bits cleared.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 156 of file ra8_mpc.c.

References internal_check(), internal_reset_pfs(), k_ra8_mpc_dir_output, k_ra8_ok, k_ra8_pfs_mask_pdr, and pin.

◆ ra8_mpc_set_irq()

ra8_err_t ra8_mpc_set_irq	(	ra8_port_t	port,
		ra8_pin_t	pin )

nodiscard

Mark a pin as an external IRQ input (ISEL = 1).

Does NOT program the ICU IELSR entry – that's ra8_isr's job. This helper just flips the pin's PFS so the edge detector is active.

Parameters

[in]	port	Port index.
[in]	pin	Pin index.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Pin ISEL set.
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.

Precondition: IRQs masked or single-threaded init context.

Postcondition: PmnPFS: ISEL = 1, PMR = 0, PDR = 0.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 177 of file ra8_mpc.c.

References internal_check(), internal_reset_pfs(), k_ra8_ok, k_ra8_pfs_mask_isel, and pin.

◆ ra8_mpc_set_open_drain()

ra8_err_t ra8_mpc_set_open_drain	(	ra8_port_t	port,
		ra8_pin_t	pin,
		bool	enable )

nodiscard

Enable or disable N-channel open-drain on a pin.

Parameters

[in]	port	Port index.
[in]	pin	Pin index.
[in]	enable	true for open-drain, false for CMOS.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	NCODR updated.
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.

Precondition: IRQs masked or single-threaded init context.

Postcondition: NCODR reflects the requested state.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 198 of file ra8_mpc.c.

References internal_check(), internal_update_pfs(), k_ra8_ok, k_ra8_pfs_mask_ncodr, and pin.

Referenced by combo_pfs_or_halt(), i3c_demo_pfs_or_halt(), and internal_io_expander_route_pins().

◆ ra8_mpc_set_pull()

ra8_err_t ra8_mpc_set_pull	(	ra8_port_t	port,
		ra8_pin_t	pin,
		ra8_mpc_pull_t	pull )

nodiscard

Enable or disable the internal pull-up on a pin.

Parameters

[in]	port	Port index.
[in]	pin	Pin index.
[in]	pull	Off or on.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Pull updated.
k_ra8_err_gpio_invalid_port	Port out of range.
k_ra8_err_gpio_invalid_pin	Pin out of range.

Precondition: IRQs masked or single-threaded init context.

Postcondition: PCR reflects the requested state; all other fields untouched.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 187 of file ra8_mpc.c.

References internal_check(), internal_update_pfs(), k_ra8_mpc_pull_up, k_ra8_ok, k_ra8_pfs_mask_pcr, and pin.

Variable Documentation

◆ s_tag

const char* s_tag = "MPC"

static

Definition at line 27 of file ra8_mpc.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_check()

◆ internal_reset_pfs()

◆ internal_update_pfs()

◆ ra8_mpc_read_pfs()

◆ ra8_mpc_route_peripheral()

◆ ra8_mpc_set_analog()

◆ ra8_mpc_set_gpio()

◆ ra8_mpc_set_irq()

◆ ra8_mpc_set_open_drain()

◆ ra8_mpc_set_pull()

Variable Documentation

◆ s_tag