Network PAL implementation – ra8_eth wrapper. More...

#include "ra8_net_pal.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_eth.h"
#include "ra8_log.h"

Include dependency graph for ra8_net_pal.c:

Data Structures
struct	ra8_net_pal_slot_t
	One ring slot holding a single frame plus its byte length. More...
struct	ra8_net_pal_state_t
	Singleton PAL state. More...

Enumerations
enum	ra8_net_pal_ring_dim_t : uint16_t { k_ra8_net_pal_ring_slots = 4U }

Functions
static void	internal_copy_bytes (uint8_t dst, const uint8_t src, uint16_t len)
	Copy len bytes byte-by-byte (string.h-free implementation).
static void	internal_zero_bytes (uint8_t *dst, uint16_t len)
	Zero len bytes (project-local replacement for memset).
static void	internal_ring_reset (void)
	Reset the software ring to empty.
static uint32_t	internal_translate_event (uint32_t eth_mask)
	Translate ra8_eth status bits into PAL event bits.
static void	internal_eth_event (void *ctx, uint32_t status_mask)
	ra8_eth event handler – translate + forward to the PAL callback.
ra8_err_t	ra8_net_pal_init (const ra8_net_pal_mac_t *mac)
	Bring up the network PAL singleton.
ra8_err_t	ra8_net_pal_deinit (void)
	Tear down the network PAL singleton.
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)
	Install a single event handler for link / RX / TX events.

Variables
static const char *	s_tag = "NETPAL"
static ra8_net_pal_state_t	s_state = {}

Detailed Description

Network PAL implementation – ra8_eth wrapper.

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

PAL over the Ring-3 ra8_eth driver. The PAL owns a small in-memory TX/RX ring the stack drains with the send/recv primitives. On real hardware the ring would be backed by the GWCA descriptor engine; today the ring is a contiguous RAM buffer large enough for Ethernet loopback tests.

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

Definition in file ra8_net_pal.c.

Enumeration Type Documentation

◆ ra8_net_pal_ring_dim_t

enum ra8_net_pal_ring_dim_t : uint16_t

Enumerator
k_ra8_net_pal_ring_slots	Number of in-flight frames.

Definition at line 91 of file ra8_net_pal.c.

Function Documentation

◆ internal_copy_bytes()

void internal_copy_bytes	(	uint8_t *	dst,
		const uint8_t *	src,
		uint16_t	len )

static

Copy len bytes byte-by-byte (string.h-free implementation).

The codebase avoids string.h to dodge clang-tidy's insecureAPI.DeprecatedOrUnsafeBufferHandling check; this loop is the project-local replacement for memcpy on small fixed buffers like the 6-byte MAC.

Parameters

[out]	dst	Destination buffer; must hold at least len bytes.
[in]	src	Source buffer; must hold at least len bytes.
[in]	len	Number of bytes to copy.

Precondition: dst and src are non-NULL.; dst and src do not overlap.

Postcondition: dst[0..len-1] == src[0..len-1].; No other state is mutated.

Note: Pure helper; safe from any context.

Since: 0.1.0

Definition at line 51 of file ra8_net_pal.c.

Referenced by ra8_net_pal_get_mac_addr(), ra8_net_pal_init(), ra8_net_pal_recv_frame(), ra8_net_pal_send_frame(), and ra8_net_pal_set_mac_addr().

◆ internal_eth_event()

void internal_eth_event	(	void *	ctx,
		uint32_t	status_mask )

static

ra8_eth event handler – translate + forward to the PAL callback.

Installed via ra8_eth_attach_handler during ra8_net_pal_init. Drops events while the PAL is uninitialized, then translates the raw status mask via internal_translate_event and forwards non-zero results to the stack-installed callback.

Parameters

[in]	ctx	Opaque context (unused – PAL is a singleton).
[in]	status_mask	Raw ra8_eth status bits.

Precondition: Invoked from ra8_eth ISR or task context.; s_state storage is mapped and readable.

Postcondition: No PAL state is mutated.; Stack callback may have been invoked at most once per call.

Note: Reentrant only with respect to a different ra8_net_pal instance, which does not exist; treat as not thread-safe.

Since: 0.1.0

Definition at line 212 of file ra8_net_pal.c.

References internal_translate_event(), k_ra8_net_pal_event_none, and s_state.

Referenced by ra8_net_pal_init().

◆ internal_ring_reset()

void internal_ring_reset ( void )

static

Reset the software ring to empty.

Clears the head/tail/count cursors and zeroes every slot's len field so a subsequent ra8_net_pal_send_frame starts at slot 0.

Precondition: Caller holds the PAL single-thread lock (init/deinit context).; s_state storage is mapped and writable.

Postcondition: s_state.head == s_state.tail == s_state.count == 0.; Every s_state.ring[i].len == 0.

Note: Not thread-safe; call only from init/deinit paths.

Since: 0.1.0

Definition at line 149 of file ra8_net_pal.c.

References k_ra8_net_pal_ring_slots, and s_state.

Referenced by ra8_net_pal_deinit(), and ra8_net_pal_init().

◆ internal_translate_event()

uint32_t internal_translate_event ( uint32_t eth_mask )

static

Translate ra8_eth status bits into PAL event bits.

Today the mapping is "any non-zero ra8_eth status bit becomes an error event"; future waves will fan the bits out into the link/RX/TX event taxonomy.

Parameters

[in] eth_mask Raw status mask published by ra8_eth.

Returns: PAL-side event mask suitable for the stack callback.

Return values

k_ra8_net_pal_event_none	eth_mask was zero.
k_ra8_net_pal_event_error	eth_mask had any bit set.

Precondition: eth_mask may take any uint32_t value.; No global state is read.

Postcondition: No state is modified.; Return value reflects the translation only.

Note: Pure helper; safe from any context.

Since: 0.1.0

Definition at line 182 of file ra8_net_pal.c.

References k_ra8_net_pal_event_error, and k_ra8_net_pal_event_none.

Referenced by internal_eth_event().

◆ internal_zero_bytes()

void internal_zero_bytes	(	uint8_t *	dst,
		uint16_t	len )

static

Zero len bytes (project-local replacement for memset).

Same rationale as internal_copy_bytes – string.h is excluded by clang-tidy policy, so a hand-rolled loop fills small buffers.

Parameters

[out]	dst	Destination buffer; must hold at least len bytes.
[in]	len	Number of bytes to clear.

Precondition: dst is non-NULL.; len accurately describes the writable extent of dst.

Postcondition: dst[0..len-1] == 0.; No other state is mutated.

Note: Pure helper; safe from any context.

Since: 0.1.0

Definition at line 77 of file ra8_net_pal.c.

Referenced by ra8_net_pal_init().

◆ ra8_net_pal_deinit()

ra8_err_t ra8_net_pal_deinit ( void )

nodiscard

Tear down the network PAL singleton.

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.

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

Bring up the network PAL singleton.

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

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

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

Variable Documentation

◆ s_state

ra8_net_pal_state_t s_state = {}

static

Definition at line 125 of file ra8_net_pal.c.

◆ s_tag

const char* s_tag = "NETPAL"

static

Definition at line 84 of file ra8_net_pal.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_net_pal_ring_dim_t

Function Documentation

◆ internal_copy_bytes()

◆ internal_eth_event()

◆ internal_ring_reset()

◆ internal_translate_event()

◆ internal_zero_bytes()

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

Variable Documentation

◆ s_state

◆ s_tag