Network Platform Abstraction Layer for the RA8D2 ESWM block. More...

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

Include dependency graph for ra8_net_pal.h:

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

Data Structures
struct	ra8_net_pal_mac_t
	48-bit MAC address container. More...

Typedefs
typedef void(*	ra8_net_pal_event_fn_t) (void *ctx, uint32_t event_mask)
	Async event callback shape (link change, RX ready, error).

Enumerations
enum	ra8_net_pal_limits_t : uint16_t { k_ra8_net_pal_mac_addr_len = 6U , k_ra8_net_pal_mtu = 1500U , k_ra8_net_pal_frame_max = 1518U }
	maximums / sizes baked into the PAL contract. More...
enum	ra8_net_pal_link_state_t : uint8_t { k_ra8_net_pal_link_down = 0U , k_ra8_net_pal_link_up = 1U }
	Possible link-up states surfaced to the stack. More...
enum	ra8_net_pal_event_t : uint32_t { k_ra8_net_pal_event_none = 0x00U , k_ra8_net_pal_event_link_up = 0x01U , k_ra8_net_pal_event_link_down = 0x02U , k_ra8_net_pal_event_rx_ready = 0x04U , k_ra8_net_pal_event_tx_done = 0x08U , k_ra8_net_pal_event_error = 0x10U }
	Bits passed to ra8_net_pal_event_fn_t. More...

Functions
ra8_err_t	ra8_net_pal_init (const ra8_net_pal_mac_t *mac)
	Initialise the network PAL.
ra8_err_t	ra8_net_pal_deinit (void)
	Tear down the network PAL.
ra8_err_t	ra8_net_pal_set_mac_addr (const ra8_net_pal_mac_t *mac)
	Programme the PAL MAC address.
ra8_err_t	ra8_net_pal_get_mac_addr (ra8_net_pal_mac_t *out_mac)
	Read the currently programmed MAC address.
ra8_err_t	ra8_net_pal_send_frame (const uint8_t *frame, uint16_t len)
	Hand a complete ethernet frame to the MAC for transmit.
ra8_err_t	ra8_net_pal_recv_frame (uint8_t out_buf, uint16_t inout_len)
	Pull the next received ethernet frame, if any, into a buffer.
ra8_err_t	ra8_net_pal_link_status (ra8_net_pal_link_state_t *out_state)
	Read the current link state.
ra8_err_t	ra8_net_pal_set_event_handler (ra8_net_pal_event_fn_t fn, void *ctx)
	Attach a single event handler for link / RX / TX events.

Detailed Description

Network Platform Abstraction Layer for the RA8D2 ESWM block.

Tag: [Ring 4 / PAL] {World: NS}

scaffold for the ethernet PAL. The PAL sits between the Ring-3 ra8_eth_* driver and any higher-level network stack (NetX Duo today, possibly TCPDirect or a custom stack later).

Responsibilities:

Own the MAC address.
Translate ra8_eth_t error codes into stack-friendly status.
Provide a single send/receive primitive a stack can call.
Track link state and surface it to the stack.
Hide the MSTP / clock-gate dance behind ra8_net_pal_init.

The PAL is intentionally stack-agnostic: no NetX Duo types appear in this header, and the same would hold for any future TCPDirect or zero-stack consumer.

Its real consumers today are libs/ra8_nsc/src/ra8_nsc_eth.c (the TrustZone veneer that exposes Ethernet to the Non-Secure world) and the host tests. NetX Duo is NOT one of them: its driver (port/netxduo/src/nx_ether_driver_ra8_eth.c) includes ra8_eth.h and calls ra8_eth_* directly, never this API (#621).

Layering

Threading

Single-threaded. Init runs from the boot path; send/recv are called from the main loop or a single network task. Frame RX is delivered through ra8_net_pal_recv_frame polling – the IRQ path lives inside ra8_eth and is fanned out via ra8_net_pal_set_event_handler.

Send/recv backing store

The PAL owns a small in-memory ring (k_ra8_net_pal_ring_slots slots, each k_ra8_net_pal_frame_max bytes) the stack writes to with ra8_net_pal_send_frame and drains with ra8_net_pal_recv_frame. On real hardware the ring is backed by the GWCA descriptor engine; in host tests it is a plain contiguous RAM buffer. The stack-facing contract is identical in either case, so NetX Duo's driver talks to the same API.

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

Definition in file ra8_net_pal.h.

Typedef Documentation

◆ ra8_net_pal_event_fn_t

typedef void(* ra8_net_pal_event_fn_t) (void *ctx, uint32_t event_mask)

Async event callback shape (link change, RX ready, error).

Parameters

[in]	ctx	Caller-supplied context.
[in]	event_mask	OR of k_ra8_net_pal_event_* bits.

Note: Invoked from ra8_eth ISR context. Must return quickly and must not call back into ra8_net_pal_init / deinit.

Definition at line 139 of file ra8_net_pal.h.

Enumeration Type Documentation

◆ ra8_net_pal_event_t

enum ra8_net_pal_event_t : uint32_t

Bits passed to ra8_net_pal_event_fn_t.

Enumerator
k_ra8_net_pal_event_none	RA8 net pal event none.
k_ra8_net_pal_event_link_up	Link came up.
k_ra8_net_pal_event_link_down	Link went down.
k_ra8_net_pal_event_rx_ready	RX descriptor has data.
k_ra8_net_pal_event_tx_done	TX descriptor freed.
k_ra8_net_pal_event_error	MAC reported a fault.

Definition at line 145 of file ra8_net_pal.h.

◆ ra8_net_pal_limits_t

enum ra8_net_pal_limits_t : uint16_t

maximums / sizes baked into the PAL contract.

MTU is the standard Ethernet maximum payload (1500 bytes) plus the 14-byte header. Frame size includes the FCS placeholder so the descriptor ring can route 1518-byte frames without truncation.

Enumerator
k_ra8_net_pal_mac_addr_len	48-bit Ethernet MAC.
k_ra8_net_pal_mtu	Standard payload size.
k_ra8_net_pal_frame_max	MTU + header + FCS.

Definition at line 94 of file ra8_net_pal.h.

◆ ra8_net_pal_link_state_t

enum ra8_net_pal_link_state_t : uint8_t

Possible link-up states surfaced to the stack.

Enumerator
k_ra8_net_pal_link_down	Cable unplugged or PHY not up.
k_ra8_net_pal_link_up	Link up at any speed/duplex.

Definition at line 104 of file ra8_net_pal.h.

Function Documentation

◆ ra8_net_pal_deinit()

ra8_err_t ra8_net_pal_deinit ( void )

nodiscard

Tear down the network PAL.

Releases any in-flight TX descriptors, detaches the event handler, and calls ra8_eth_deinit to drop the ESWM MSTP reference.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	PAL released.
k_ra8_err_invalid_state	PAL was never initialized.

Precondition: IRQs masked or single-threaded shutdown context.

Postcondition: Link state reads as k_ra8_net_pal_link_down.; Subsequent send/recv calls return k_ra8_err_invalid_state.

Note: Thread safety: not thread-safe.

See also: ra8_net_pal_init

Since: 0.1.0

Tear down the network PAL.

Detaches the ra8_eth handler, releases the underlying driver, clears the event callback, marks the link as down, and resets the in-memory ring.

Returns: ra8_err_t error code from ra8_eth_deinit.

Return values

k_ra8_ok	Released cleanly.
k_ra8_err_invalid_state	PAL was never initialized.

Precondition: IRQs masked or single-threaded shutdown context.; PAL was previously initialized (otherwise returns invalid_state).

Postcondition: s_state.initialized == false.; Subsequent send/recv calls return k_ra8_err_invalid_state.

Note: Not thread-safe.

See also: ra8_net_pal_init

Since: 0.1.0

Definition at line 302 of file ra8_net_pal.c.

References internal_ring_reset(), k_ra8_err_invalid_state, k_ra8_net_pal_link_down, ra8_eth_attach_handler(), ra8_eth_deinit(), and s_state.

◆ ra8_net_pal_get_mac_addr()

ra8_err_t ra8_net_pal_get_mac_addr ( ra8_net_pal_mac_t * out_mac )

nodiscard

Read the currently programmed MAC address.

Parameters

[out] out_mac Receives the MAC.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MAC copied.
k_ra8_err_null_ptr	out_mac was NULL.
k_ra8_err_invalid_state	PAL not initialized.

Precondition: out_mac is non-NULL.; PAL has been initialized.

Postcondition: No PAL state is modified.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Copies s_state.mac into the caller buffer.

Parameters

[out] out_mac Receives the MAC descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MAC copied.
k_ra8_err_null_ptr	out_mac was NULL.
k_ra8_err_invalid_state	PAL not initialized.

Precondition: out_mac is non-NULL.; PAL has been initialized.

Postcondition: out_mac holds the current MAC.; No PAL state is modified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 369 of file ra8_net_pal.c.

References ra8_net_pal_mac_t::bytes, internal_copy_bytes(), k_ra8_err_invalid_state, k_ra8_net_pal_mac_addr_len, k_ra8_ok, RA8_CHECK_NULL_PTR, s_state, and s_tag.

◆ ra8_net_pal_init()

ra8_err_t ra8_net_pal_init ( const ra8_net_pal_mac_t * mac )

nodiscard

Initialise the network PAL.

Powers on the underlying ra8_eth driver via ra8_eth_init, loads the MAC address from the supplied descriptor (NULL keeps the implementation default of all-zeros), and resets the internal state machine to "link down, no event handler".

Parameters

[in] mac MAC address to programme. May be NULL to keep whatever the underlying ESWM block already has.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	PAL ready, link state = down.
k_ra8_err_hw_init_failed	Underlying ra8_eth_init failed.

Precondition: ra8_mstp_init and ra8_pwr_init have been called.; IRQs masked or single-threaded init context.

Postcondition: On success, the PAL is ready and ra8_net_pal_link_status returns k_ra8_net_pal_link_down.

Note: Thread safety: not thread-safe.

See also: ra8_net_pal_deinit

Since: 0.1.0

Initialise the network PAL.

Powers up the underlying ra8_eth driver, programmes the supplied MAC (or leaves it zero), resets the in-memory ring, and installs the internal ra8_eth event handler so the stack callback can fire.

Parameters

[in] mac MAC descriptor to programme; may be NULL to keep the all-zero default.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	PAL ready, link state = down.
k_ra8_err_hw_init_failed	ra8_eth_init failed.

Precondition: ra8_mstp_init and ra8_pwr_init have been called.; IRQs masked or single-threaded init context.

Postcondition: On success, s_state.initialized == true and the ring is empty.; On failure, s_state.initialized == false and ra8_eth has been torn down.

Note: Not thread-safe; must run from boot init context.

See also: ra8_net_pal_deinit

Since: 0.1.0

Definition at line 256 of file ra8_net_pal.c.

References ra8_net_pal_mac_t::bytes, internal_copy_bytes(), internal_eth_event(), internal_ring_reset(), internal_zero_bytes(), k_ra8_err_hw_init_failed, k_ra8_net_pal_link_down, k_ra8_net_pal_mac_addr_len, k_ra8_ok, ra8_eth_attach_handler(), ra8_eth_init(), ra8_log_error_val, ra8_log_info, s_state, and s_tag.

◆ ra8_net_pal_link_status()

ra8_err_t ra8_net_pal_link_status ( ra8_net_pal_link_state_t * out_state )

nodiscard

Read the current link state.

Parameters

[out] out_state Receives link up/down.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Link state copied.
k_ra8_err_null_ptr	out_state was NULL.
k_ra8_err_invalid_state	PAL not initialized.

Precondition: out_state is non-NULL.; PAL has been initialized.

Postcondition: No PAL state is modified.

Note: Thread safety: not thread-safe with respect to the event handler which can update link state from ISR context.

Since: 0.1.0

Definition at line 485 of file ra8_net_pal.c.

References k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_state, and s_tag.

◆ ra8_net_pal_recv_frame()

ra8_err_t ra8_net_pal_recv_frame	(	uint8_t *	out_buf,
		uint16_t *	inout_len )

nodiscard

Pull the next received ethernet frame, if any, into a buffer.

If a frame is available it is copied into out_buf and *inout_len is updated to the byte count actually written. When no frame is ready the function returns k_ra8_err_no_data so callers can poll without blocking.

Parameters

[out]	out_buf	Destination buffer.
[in,out]	inout_len	On entry: capacity of out_buf. On exit: bytes written.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Frame copied.
k_ra8_err_no_data	No frame ready (poll-friendly).
k_ra8_err_null_ptr	out_buf / inout_len NULL.
k_ra8_err_invalid_state	PAL not initialized.
k_ra8_err_invalid_arg	*inout_len < frame_max capacity.

Precondition: out_buf and inout_len are non-NULL.; *inout_len >= k_ra8_net_pal_frame_max.; PAL has been initialized.

Postcondition: On success, *inout_len holds the actual frame length.

Note: Thread safety: not thread-safe.

See also: ra8_net_pal_send_frame

Since: 0.1.0

If a frame is available it is copied into out_buf and *inout_len is set to the byte count actually written. When no frame is queued the function returns k_ra8_err_no_data so callers can poll without blocking.

Parameters

[out]	out_buf	Destination buffer, sized at least k_ra8_net_pal_frame_max bytes.
[in,out]	inout_len	On entry: capacity of out_buf. On exit: bytes written.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Frame copied.
k_ra8_err_no_data	No frame ready.
k_ra8_err_null_ptr	out_buf or inout_len NULL.
k_ra8_err_invalid_state	PAL not initialized.
k_ra8_err_invalid_arg	*inout_len < k_ra8_net_pal_frame_max.

Precondition: out_buf and inout_len are non-NULL.; *inout_len >= k_ra8_net_pal_frame_max.

Postcondition: On success, the consumed slot is freed and s_state.count decremented.; On error, no ring state is mutated.

Note: Not thread-safe.

See also: ra8_net_pal_send_frame

Since: 0.1.0

Definition at line 462 of file ra8_net_pal.c.

References ra8_net_pal_slot_t::data, internal_copy_bytes(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_no_data, k_ra8_net_pal_frame_max, k_ra8_net_pal_ring_slots, k_ra8_ok, ra8_net_pal_slot_t::len, RA8_CHECK_NULL_PTR, s_state, and s_tag.

Referenced by ra8_nsc_eth_recv().

◆ ra8_net_pal_send_frame()

ra8_err_t ra8_net_pal_send_frame	(	const uint8_t *	frame,
		uint16_t	len )

nodiscard

Hand a complete ethernet frame to the MAC for transmit.

Copies frame[0..len-1] into the next free TX ring slot. On real hardware the slot is a GWCA descriptor; in the host build it is a plain RAM buffer the PAL also exposes through ra8_net_pal_recv_frame for loopback tests.

Parameters

[in]	frame	Ethernet frame bytes (header + payload, no FCS).
[in]	len	Frame length in bytes; non-zero, <= frame_max.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Frame queued for TX.
k_ra8_err_null_ptr	frame was NULL.
k_ra8_err_invalid_arg	len zero or out of range.
k_ra8_err_invalid_state	PAL not initialized.
k_ra8_err_no_mem	TX ring full; try again later.

Precondition: frame is non-NULL.; PAL has been initialized.

Postcondition: On success, the frame is queued and the caller may drop frame.

Note: Thread safety: not thread-safe.

See also: ra8_net_pal_recv_frame

Since: 0.1.0

Copies frame[0..len-1] into the next free TX ring slot. On real hardware the slot would be a GWCA descriptor; in the host build it is a plain RAM buffer the PAL also exposes through ra8_net_pal_recv_frame for loopback tests. Fires the k_ra8_net_pal_event_tx_done event after enqueue when an event handler is installed.

Parameters

[in]	frame	Ethernet frame bytes (header + payload, no FCS).
[in]	len	Frame length in bytes; non-zero, <= frame_max.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Frame queued.
k_ra8_err_null_ptr	frame was NULL.
k_ra8_err_invalid_arg	len zero or above k_ra8_net_pal_frame_max.
k_ra8_err_invalid_state	PAL not initialized.
k_ra8_err_no_mem	TX ring is full; retry after drain.

Precondition: frame is non-NULL.; PAL has been initialized.

Postcondition: On success, s_state.count is incremented by one.; On error, no ring state is mutated.

Note: Not thread-safe.

See also: ra8_net_pal_recv_frame

Since: 0.1.0

Definition at line 409 of file ra8_net_pal.c.

References ra8_net_pal_slot_t::data, internal_copy_bytes(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_net_pal_event_tx_done, k_ra8_net_pal_frame_max, k_ra8_net_pal_ring_slots, k_ra8_ok, ra8_net_pal_slot_t::len, RA8_CHECK_NULL_PTR, s_state, and s_tag.

Referenced by ra8_nsc_eth_send().

◆ ra8_net_pal_set_event_handler()

ra8_err_t ra8_net_pal_set_event_handler	(	ra8_net_pal_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a single event handler for link / RX / TX events.

Replaces any previously installed handler. The PAL relays ra8_eth ISR events into this callback after translating them into the PAL-level k_ra8_net_pal_event_* bit set.

Parameters

[in]	fn	Callback. Pass NULL to detach.
[in]	ctx	Context passed to the callback.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handler installed (or detached).
k_ra8_err_invalid_state	PAL not initialized.

Precondition: PAL has been initialized.

Postcondition: Subsequent ra8_eth events are routed through fn.

Note: Thread safety: not thread-safe; only call from single-threaded init or with IRQs masked.

Since: 0.1.0

Attach a single event handler for link / RX / TX events.

Replaces any previously installed callback. Pass fn == nullptr to detach. The callback fires from ra8_eth ISR/task context via internal_eth_event and from the send/recv hot path.

Parameters

[in]	fn	Event callback, or NULL to detach.
[in]	ctx	Opaque context handed back to fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handler installed/cleared.
k_ra8_err_invalid_state	PAL not initialized.

Precondition: PAL has been initialized.; fn is callable from ISR context if it is non-NULL.

Postcondition: s_state.event_fn == fn and s_state.event_ctx == ctx.; No other PAL state is mutated.

Note: Not thread-safe with respect to a concurrent event delivery.

Since: 0.1.0

Definition at line 518 of file ra8_net_pal.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

◆ ra8_net_pal_set_mac_addr()

ra8_err_t ra8_net_pal_set_mac_addr ( const ra8_net_pal_mac_t * mac )

nodiscard

Programme the PAL MAC address.

Updates the in-memory copy of the MAC and (when ra8_eth gains MAC-write support) the ESWM hardware filter. Called by the stack at any time after ra8_net_pal_init.

Parameters

[in] mac Non-NULL MAC descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MAC stored.
k_ra8_err_null_ptr	mac was NULL.
k_ra8_err_invalid_state	ra8_net_pal_init not called yet.

Precondition: mac is non-NULL.; PAL has been initialized.

Postcondition: Subsequent ra8_net_pal_get_mac_addr returns mac.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Updates the in-memory MAC. When ra8_eth gains MAC-write support the same call will also update the ESWM hardware filter.

Parameters

[in] mac Non-NULL MAC descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MAC stored.
k_ra8_err_null_ptr	mac was NULL.
k_ra8_err_invalid_state	PAL not initialized.

Precondition: mac is non-NULL.; PAL has been initialized.

Postcondition: s_state.mac mirrors the supplied descriptor.; No other PAL state is mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 339 of file ra8_net_pal.c.

References ra8_net_pal_mac_t::bytes, internal_copy_bytes(), k_ra8_err_invalid_state, k_ra8_net_pal_mac_addr_len, k_ra8_ok, RA8_CHECK_NULL_PTR, s_state, and s_tag.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Layering

Threading

Send/recv backing store

Typedef Documentation

◆ ra8_net_pal_event_fn_t

Enumeration Type Documentation

◆ ra8_net_pal_event_t

◆ ra8_net_pal_limits_t

◆ ra8_net_pal_link_state_t

Function Documentation

◆ ra8_net_pal_deinit()

◆ ra8_net_pal_get_mac_addr()

◆ ra8_net_pal_init()

◆ ra8_net_pal_link_status()

◆ ra8_net_pal_recv_frame()

◆ ra8_net_pal_send_frame()

◆ ra8_net_pal_set_event_handler()

◆ ra8_net_pal_set_mac_addr()