Multi-function Pin Controller (MPC) facade. More...

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

Include dependency graph for ra8_mpc.h:

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

Enumerations
enum	ra8_mpc_psel_t : uint8_t { k_ra8_mpc_psel_gpio = 0x00U , k_ra8_mpc_psel_agt = 0x01U , k_ra8_mpc_psel_gpt0 = 0x02U , k_ra8_mpc_psel_gpt1 = 0x03U , k_ra8_mpc_psel_sci0 = 0x04U , k_ra8_mpc_psel_sci1 = 0x05U , k_ra8_mpc_psel_spi = 0x06U , k_ra8_mpc_psel_iic = 0x07U , k_ra8_mpc_psel_key = 0x08U , k_ra8_mpc_psel_clkout_rtc = 0x09U , k_ra8_mpc_psel_cac_adc = 0x0AU , k_ra8_mpc_psel_bus = 0x0BU , k_ra8_mpc_psel_acmphs = 0x0CU , k_ra8_mpc_psel_lcdc = 0x0DU , k_ra8_mpc_psel_ceu = 0x0FU , k_ra8_mpc_psel_canfd = 0x10U , k_ra8_mpc_psel_qspi = 0x11U , k_ra8_mpc_psel_ssi = 0x12U , k_ra8_mpc_psel_usbfs = 0x13U , k_ra8_mpc_psel_usbhs = 0x14U , k_ra8_mpc_psel_sdhi = 0x15U , k_ra8_mpc_psel_ether_mii = 0x16U , k_ra8_mpc_psel_ether_rmii = 0x17U , k_ra8_mpc_psel_pdc = 0x18U , k_ra8_mpc_psel_ether_rgmii = 0x18U , k_ra8_mpc_psel_glcdc = 0x19U , k_ra8_mpc_psel_trace = 0x1AU , k_ra8_mpc_psel_pdm = 0x1BU , k_ra8_mpc_psel_ospi = 0x1CU , k_ra8_mpc_psel_cec = 0x1DU , k_ra8_mpc_psel_ulpt = 0x1EU , k_ra8_mpc_psel_mipi = 0x1FU }
	Peripheral function select values for the PMR/PSEL path. More...
enum	ra8_mpc_dir_t : uint8_t { k_ra8_mpc_dir_input = 0U , k_ra8_mpc_dir_output = 1U }
	Pin direction for ra8_mpc_set_gpio. More...
enum	ra8_mpc_pull_t : uint8_t { k_ra8_mpc_pull_off = 0U , k_ra8_mpc_pull_up = 1U }
	Pull-up enable for ra8_mpc_set_pull. More...

Functions
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.

Detailed Description

Multi-function Pin Controller (MPC) facade.

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

Ring 3 / HAL substrate. Wraps the RA8D2 PmnPFS register array (HUM Ch 20 "I/O Ports", p 837) behind a small set of operation-named helpers:

ra8_mpc_route_peripheral – map a pin to a PSEL function.
ra8_mpc_set_gpio – reset a pin to plain GPIO.
ra8_mpc_set_analog – put a pin in analog-input mode.
ra8_mpc_set_irq – mark a pin as an external IRQ input.
ra8_mpc_set_pull – toggle pull-up.
ra8_mpc_set_open_drain – toggle N-channel open-drain output.

Drivers never touch PmnPFS directly. The substrate handles the PWPR unlock / lock sequence, the "write zero first" reset, and the pin-validator registration so two drivers cannot claim the same pin without being told about it.

Threading

Single-threaded init context only.

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

Definition in file ra8_mpc.h.

Enumeration Type Documentation

◆ ra8_mpc_dir_t

enum ra8_mpc_dir_t : uint8_t

Pin direction for ra8_mpc_set_gpio.

Enumerator
k_ra8_mpc_dir_input	Input direction (PDR = 0).
k_ra8_mpc_dir_output	Output direction (PDR = 1).

Definition at line 105 of file ra8_mpc.h.

◆ ra8_mpc_psel_t

enum ra8_mpc_psel_t : uint8_t

Peripheral function select values for the PMR/PSEL path.

Values come from HUM Ch 20 table "Pin function select" (section 20.2.x), cross-verified against FSP ra/fsp/src/bsp/mcu/ra8d2/bsp_override.h (RA8D2-specific ioport_peripheral_t enum). The 5-bit PSEL field accepts values 0x00..0x1F; only the codes the firmware currently routes are listed – extend as new drivers come online.

Note: Values are the raw 5-bit PSEL, not pre-shifted into bits 28..24. ra8_mpc_route_peripheral shifts left by k_ra8_pfs_bit_psel0 before writing.

Enumerator
k_ra8_mpc_psel_gpio	00000: plain GPIO / DEBUG.
k_ra8_mpc_psel_agt	00001: AGT/AGTW timer I/O.
k_ra8_mpc_psel_gpt0	00010: GPT0 (low channels).
k_ra8_mpc_psel_gpt1	00011: GPT1 alt mux.
k_ra8_mpc_psel_sci0	00100: SCI 0/2/4/6/8.
k_ra8_mpc_psel_sci1	00101: SCI 1/3/5/7/9.
k_ra8_mpc_psel_spi	00110: SPI.
k_ra8_mpc_psel_iic	00111: IIC.
k_ra8_mpc_psel_key	01000: KEY input.
k_ra8_mpc_psel_clkout_rtc	01001: CLKOUT / comparator / RTC.
k_ra8_mpc_psel_cac_adc	01010: CAC / ADC trigger.
k_ra8_mpc_psel_bus	01011: external bus interface.
k_ra8_mpc_psel_acmphs	01100: ACMPHS / CTSU.
k_ra8_mpc_psel_lcdc	01101: segment LCDC / SCI DEn.
k_ra8_mpc_psel_ceu	01111: camera engine unit (CEU).
k_ra8_mpc_psel_canfd	10000: CAN / CANFD.
k_ra8_mpc_psel_qspi	10001: QSPI controller.
k_ra8_mpc_psel_ssi	10010: SSI audio.
k_ra8_mpc_psel_usbfs	10011: USB Full-Speed.
k_ra8_mpc_psel_usbhs	10100: USB High-Speed / GPT2.
k_ra8_mpc_psel_sdhi	10101: SDHI / MMC / GPT3.
k_ra8_mpc_psel_ether_mii	10110: Ethernet MII / GPT4 / UARTA.
k_ra8_mpc_psel_ether_rmii	10111: Ethernet RMII.
k_ra8_mpc_psel_pdc	11000: PDC / AGT1 / Ether RGMII (alias).
k_ra8_mpc_psel_ether_rgmii	11000: Ethernet RGMII (preferred name).
k_ra8_mpc_psel_glcdc	11001: graphics LCDC / CAC.
k_ra8_mpc_psel_trace	11010: ETM debug trace.
k_ra8_mpc_psel_pdm	11011: PDM / GPT5.
k_ra8_mpc_psel_ospi	11100: Octa-SPI controller.
k_ra8_mpc_psel_cec	11101: CEC / PGAOUT0.
k_ra8_mpc_psel_ulpt	11110: ULPT / PGAOUT1.
k_ra8_mpc_psel_mipi	11111: MIPI DSI.

Definition at line 66 of file ra8_mpc.h.

◆ ra8_mpc_pull_t

enum ra8_mpc_pull_t : uint8_t

Pull-up enable for ra8_mpc_set_pull.

Enumerator
k_ra8_mpc_pull_off	RA8 mpc pull off.
k_ra8_mpc_pull_up	RA8 mpc pull up.

Definition at line 114 of file ra8_mpc.h.

Function Documentation

◆ 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.

Enumerations

Functions

Detailed Description

Threading

Enumeration Type Documentation

◆ ra8_mpc_dir_t

◆ ra8_mpc_psel_t

◆ ra8_mpc_pull_t

Function Documentation

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