Layer 1 (Physical) - link bring-up, the interface registry, and live egress reporting. More...

#include "config/platform/platform.h"
#include "shared/ip/ip.h"
#include "protocore_config.h"

Classes
struct	PhysicalWifiArgs
	What an 802.11 bring-up takes: the station join, the softAP, and the radio-only start. More...

struct	PhysicalReadArgs
	Where a readout copies to. More...

struct	PhysicalRouteArgs
	What the egress classifier judges: the live route and the two WiFi addresses. More...

struct	PhysicalIfaceArgs
	What names an interface in the registry, and the frame a send puts on it. More...

struct	PhysicalVars

struct	PhysicalNs
	The entries. More...

Macros
#define	PROTOCORE_PHYSICAL_HAS_BACKEND 1

#define	PROTOCORE_IF_NONE (-1)
	No interface. Reported by PhysicalNs::iface_at for an empty row.

Typedefs
typedef enum PROTO_ENUM_PACKED	protocore_phy_ps
	Radio power-save mode, in the library's own vocabulary (IEEE 802.11 power management).

typedef void(*	protocore_phy_frame_fn) (const uint8_t *frame, uint16_t len, int8_t rssi, uint8_t channel)
	One received frame, delivered in neutral terms.

typedef proto_bool(*	protocore_if_send_fn) (uint8_t if_id, const uint8_t data, uint16_t len, void ctx)
	Put `len` octets on interface `if_id`.

Enumerations
enum	PROTO_ENUM_PACKED { PROTOCORE_PHY_PS_NONE = 0 , PROTOCORE_PHY_PS_MIN_MODEM = 1 , PROTOCORE_PHY_PS_MAX_MODEM = 2 }
	Radio power-save mode, in the library's own vocabulary (IEEE 802.11 power management). More...

Functions
PROTOCORE_BEGIN_DECLS proto_bool	init_wifi_physical (const char ssid, const char password)
	Start an 802.11 station join to an access point.

proto_bool	wifi_ready (void)
	True when the station link is associated and holds an IPv4 address.

proto_bool	init_wifi_radio_physical (uint8_t channel)
	Start the radio in station mode without associating.

proto_bool	init_wifi_ap_physical (const char ssid, const char password)
	Start a softAP, with AP and station coexistence so a station link runs alongside it.

proto_bool	init_eth_physical (void)
	Start a wired Ethernet link (PROTOCORE_ENABLE_ETHERNET).

proto_bool	eth_ready (void)
	True when the wired link is up and holds an IPv4 address.

proto_bool	init_ipv6_physical (void)
	Enable dual IP layer operation on the WiFi interface (RFC 4213 sec 2, PROTOCORE_ENABLE_IPV6).

proto_bool	net_global_ipv6 (protocore_ip *out)
	The interface's global unicast IPv6 address (RFC 4291 sec 2.5.4).

proto_bool	protocore_ipv6_ready (void)
	True once a global unicast IPv6 address is configured.

protocore_if_kind	protocore_net_egress (void)
	Which interface carries outbound traffic (RFC 1122 sec 3.3.1.2).

uint32_t	protocore_net_egress_ip (void)
	IPv4 of the current default-route interface, network byte order (RFC 791 app. B), 0 if none.

uint32_t	protocore_net_ap_ip (void)
	softAP IPv4, network byte order, or 0 when the softAP is down.

int8_t	protocore_net_rssi (void)
	Station link RSSI in dBm, or 0 when not associated.

proto_bool	protocore_net_mac (uint8_t out[6])
	Copy the 802.11 station hardware address into `out` (6 octets, RFC 826 ar$hln = 6).

proto_bool	protocore_net_egress_mac (uint8_t out[6])
	Copy the hardware address of the current default-route interface into `out` (6 octets).

size_t	protocore_net_ssid (char *out, size_t cap)
	Copy the associated SSID into `out`, null-terminated.

uint8_t	protocore_net_channel (void)
	Station channel (1..14), or 0 when not associated.

protocore_if_kind	protocore_net_classify_ip (uint32_t egress_ip, uint32_t sta_ip, uint32_t ap_ip)
	Map a live default-route IPv4 to the interface it belongs to.

proto_bool	protocore_phy_ps_set (protocore_phy_ps mode)
	Apply a power-save mode. False when there is no radio backend.

protocore_phy_ps	protocore_phy_ps_get (void)
	The active power-save mode (PROTOCORE_PHY_PS_NONE when unsupported).

proto_bool	protocore_phy_tx_power_set (int8_t dbm)
	Cap transmit power.

proto_bool	protocore_phy_monitor_begin (uint8_t channel, protocore_phy_frame_fn cb)
	Enter monitor mode on `channel`, delivering frames to `cb`.

void	protocore_phy_monitor_set_channel (uint8_t channel)
	Retune monitor mode to `channel`.

void	protocore_phy_monitor_end (void)
	Leave monitor mode.

void	protocore_physical_wifi_init (uint8_t *work)

void	protocore_physical_wifi_ready (uint8_t *work)

void	protocore_physical_wifi_radio_init (uint8_t *work)

void	protocore_physical_wifi_ap_init (uint8_t *work)

void	protocore_physical_wifi_ssid (uint8_t *work)

void	protocore_physical_wifi_channel (uint8_t *work)

void	protocore_physical_wifi_rssi (uint8_t *work)

void	protocore_physical_wifi_ap_ip (uint8_t *work)

void	protocore_physical_wifi_mac (uint8_t *work)

void	protocore_physical_eth_init (uint8_t *work)

void	protocore_physical_eth_ready (uint8_t *work)

void	protocore_physical_ip6_init (uint8_t *work)

void	protocore_physical_ip6_global (uint8_t *work)

void	protocore_physical_ip6_ready (uint8_t *work)

void	protocore_physical_egress (uint8_t *work)

void	protocore_physical_egress_ip (uint8_t *work)

void	protocore_physical_egress_mac (uint8_t *work)

void	protocore_physical_classify_ip (uint8_t *work)

void	protocore_physical_iface_add (uint8_t *work)

void	protocore_physical_iface_reset (uint8_t *work)

void	protocore_physical_iface_present (uint8_t *work)

void	protocore_physical_iface_kind (uint8_t *work)

void	protocore_physical_iface_at (uint8_t *work)

void	protocore_physical_iface_count (uint8_t *work)

void	protocore_physical_iface_send (uint8_t *work)

uint8_t *	protocore_physical_span (void)
	The PROTOCORE_PHYSICAL_BORROW bytes this module's state lives in.

Variables
PhysicalVars	PhysicalV
	The operands and the outcome.

Detailed Description

Layer 1 (Physical) - link bring-up, the interface registry, and live egress reporting.

The IETF host model's lowest layer is the link layer (RFC 1122 sec 1.1.3): it names no physical layer, and the media themselves are IEEE (802.3 wired, 802.11 wireless). What the IETF defines for this layer is what the calls below carry - IP over Ethernet (RFC 894), IP over IEEE 802 networks (RFC 1042), the outbound route an interface is chosen by (RFC 1122 sec 3.3.1), IPv6 stateless address autoconfiguration (RFC 4862) and the address forms it produces (RFC 4291 sec 2.5.4 global unicast, sec 2.5.6 link-local), dual IP layer operation (RFC 4213 sec 2), and the 6-octet hardware address ARP resolves to (RFC 826 sec "Packet format", ar$hln = 6).

Bring-up runs in the backend the PROTOCORE_VENDOR_* selector compiled (test/core_setup/physical/<vendor>/), reached through the seam declared below. Failover between interfaces belongs to the stack, which reselects the default route when a link drops, so this layer adds no manager and no tick: it reads the live default route each time it is asked which interface carries outbound traffic (RFC 1122 sec 3.3.1.2 gateway selection).

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file physical.h.

Macro Definition Documentation

◆ PROTOCORE_PHYSICAL_HAS_BACKEND

#define PROTOCORE_PHYSICAL_HAS_BACKEND 1

Definition at line 40 of file physical.h.

◆ PROTOCORE_IF_NONE

PhysicalNs::i16 the interface id a registry row holds or PROTOCORE_IF_NONE (-1)

No interface. Reported by PhysicalNs::iface_at for an empty row.

Definition at line 248 of file physical.h.

Typedef Documentation

◆ protocore_phy_ps

typedef enum PROTO_ENUM_PACKED protocore_phy_ps

Radio power-save mode, in the library's own vocabulary (IEEE 802.11 power management).

◆ protocore_phy_frame_fn

typedef void(* protocore_phy_frame_fn) (const uint8_t *frame, uint16_t len, int8_t rssi, uint8_t channel)

One received frame, delivered in neutral terms.

Not the platform's received-packet struct, so no platform type reaches a service. The FCS is already stripped.

Parameters

frame	frame octets, valid only for the duration of the call.
len	frame length in octets, FCS excluded.
rssi	received signal strength, dBm.
channel	channel the frame arrived on.

Definition at line 197 of file physical.h.

◆ protocore_if_send_fn

typedef proto_bool(* protocore_if_send_fn) (uint8_t if_id, const uint8_t *data, uint16_t len, void *ctx)

Put len octets on interface if_id.

Returns: true if the interface accepted them; false drops.

Definition at line 245 of file physical.h.

Enumeration Type Documentation

◆ PROTO_ENUM_PACKED

enum PROTO_ENUM_PACKED

Radio power-save mode, in the library's own vocabulary (IEEE 802.11 power management).

Enumerator
PROTOCORE_PHY_PS_NONE	Radio always on: lowest latency, highest average draw.
PROTOCORE_PHY_PS_MIN_MODEM	Wake on every DTIM beacon.
PROTOCORE_PHY_PS_MAX_MODEM	Wake on a longer listen interval: lowest draw, highest latency.

Definition at line 179 of file physical.h.

Function Documentation

◆ init_wifi_physical()

PROTOCORE_BEGIN_DECLS proto_bool init_wifi_physical	(	const char *	ssid,
		const char *	password
	)

Start an 802.11 station join to an access point.

Returns immediately; association and address configuration are asynchronous. Poll wifi_ready().

Parameters

ssid	network SSID, null-terminated (IEEE 802.11-2020 9.4.2.2, at most 32 octets).
password	WPA2 passphrase, null-terminated (IEEE 802.11i, not an IETF protocol).

◆ wifi_ready()

proto_bool wifi_ready ( void )

True when the station link is associated and holds an IPv4 address.

◆ init_wifi_radio_physical()

proto_bool init_wifi_radio_physical ( uint8_t channel )

Start the radio in station mode without associating.

Runs the PHY with no IP link, for peer-to-peer radio messaging and promiscuous capture. Pins the radio to channel (1..14) when non-zero; 0 leaves the channel to a capture layer that sets its own (services/radio/promisc).

◆ init_wifi_ap_physical()

proto_bool init_wifi_ap_physical	(	const char *	ssid,
		const char *	password
	)

Start a softAP, with AP and station coexistence so a station link runs alongside it.

Parameters

ssid	softAP SSID, null-terminated.
password	softAP passphrase, null-terminated; >= 8 characters for WPA2, "" for an open AP.

◆ init_eth_physical()

proto_bool init_eth_physical ( void )

Start a wired Ethernet link (PROTOCORE_ENABLE_ETHERNET).

The PHY pins, type and clock come from the platform's own Ethernet build flags. Returns immediately; poll eth_ready(). A wired route classifies as PROTOCORE_IF_ETH (RFC 894 framing).

◆ eth_ready()

proto_bool eth_ready ( void )

True when the wired link is up and holds an IPv4 address.

◆ init_ipv6_physical()

proto_bool init_ipv6_physical ( void )

Enable dual IP layer operation on the WiFi interface (RFC 4213 sec 2, PROTOCORE_ENABLE_IPV6).

The interface autoconfigures a link-local address (RFC 4291 sec 2.5.6) and, when a router advertises a prefix, a global unicast address (RFC 4862). Returns immediately; poll protocore_ipv6_ready().

◆ net_global_ipv6()

proto_bool net_global_ipv6 ( protocore_ip * out )

The interface's global unicast IPv6 address (RFC 4291 sec 2.5.4).

Parameters

[out] out receives the address with family PROTOCORE_IP_V6 when true is returned.

◆ protocore_ipv6_ready()

proto_bool protocore_ipv6_ready ( void )

True once a global unicast IPv6 address is configured.

◆ protocore_net_egress()

protocore_if_kind protocore_net_egress ( void )

Which interface carries outbound traffic (RFC 1122 sec 3.3.1.2).

Reads the live default route, so it reflects the current state after any failover the stack performed. PROTOCORE_IF_ETH / PROTOCORE_IF_WIFI_STA / PROTOCORE_IF_WIFI_AP, or PROTOCORE_IF_ANY when no route is up.

◆ protocore_net_egress_ip()

uint32_t protocore_net_egress_ip ( void )

IPv4 of the current default-route interface, network byte order (RFC 791 app. B), 0 if none.

◆ protocore_net_ap_ip()

uint32_t protocore_net_ap_ip ( void )

softAP IPv4, network byte order, or 0 when the softAP is down.

◆ protocore_net_rssi()

int8_t protocore_net_rssi ( void )

Station link RSSI in dBm, or 0 when not associated.

◆ protocore_net_mac()

proto_bool protocore_net_mac ( uint8_t out[6] )

Copy the 802.11 station hardware address into out (6 octets, RFC 826 ar$hln = 6).

The station address, valid once the WiFi driver is up; a wired-only part reads back zeros. For the address in use on the wire right now whatever the link type, use protocore_net_egress_mac().

◆ protocore_net_egress_mac()

proto_bool protocore_net_egress_mac ( uint8_t out[6] )

Copy the hardware address of the current default-route interface into out (6 octets).

Link-neutral: the Ethernet PHY's address on a wired route, the station address on a wireless one, whichever interface protocore_net_egress_ip() reports. False when no route is up.

◆ protocore_net_ssid()

size_t protocore_net_ssid	(	char *	out,
		size_t	cap
	)

Copy the associated SSID into out, null-terminated.

Returns: SSID length in octets, or 0 when not associated or cap is 0.

◆ protocore_net_channel()

uint8_t protocore_net_channel ( void )

Station channel (1..14), or 0 when not associated.

◆ protocore_net_classify_ip()

protocore_if_kind protocore_net_classify_ip	(	uint32_t	egress_ip,
		uint32_t	sta_ip,
		uint32_t	ap_ip
	)

Map a live default-route IPv4 to the interface it belongs to.

Defined in physical.c, so it answers the same on every backend: an egress IP equal to the station or softAP IP is that WiFi interface, any other live IP is a wired route, 0 is no route. A backend calls it from its own egress readout; a caller reaches it as PhysicalNs::classify_ip.

Parameters

egress_ip	default-route IPv4, network byte order, 0 if none.
sta_ip	station IPv4, network byte order, 0 if not associated.
ap_ip	softAP IPv4, network byte order, 0 if the softAP is down.

◆ protocore_phy_ps_set()

proto_bool protocore_phy_ps_set ( protocore_phy_ps mode )

Apply a power-save mode. False when there is no radio backend.

◆ protocore_phy_ps_get()

protocore_phy_ps protocore_phy_ps_get ( void )

The active power-save mode (PROTOCORE_PHY_PS_NONE when unsupported).

◆ protocore_phy_tx_power_set()

proto_bool protocore_phy_tx_power_set ( int8_t dbm )

Cap transmit power.

Parameters

dbm	maximum transmit power in whole dBm; the backend converts to its own unit.

◆ protocore_phy_monitor_begin()

proto_bool protocore_phy_monitor_begin	(	uint8_t	channel,
		protocore_phy_frame_fn	cb
	)

Enter monitor mode on channel, delivering frames to cb.

◆ protocore_phy_monitor_set_channel()

void protocore_phy_monitor_set_channel ( uint8_t channel )

Retune monitor mode to channel.

◆ protocore_phy_monitor_end()

void protocore_phy_monitor_end ( void )

Leave monitor mode.

◆ protocore_physical_wifi_init()

void protocore_physical_wifi_init ( uint8_t * work )

◆ protocore_physical_wifi_ready()

void protocore_physical_wifi_ready ( uint8_t * work )

◆ protocore_physical_wifi_radio_init()

void protocore_physical_wifi_radio_init ( uint8_t * work )

◆ protocore_physical_wifi_ap_init()

void protocore_physical_wifi_ap_init ( uint8_t * work )

◆ protocore_physical_wifi_ssid()

void protocore_physical_wifi_ssid ( uint8_t * work )

◆ protocore_physical_wifi_channel()

void protocore_physical_wifi_channel ( uint8_t * work )

◆ protocore_physical_wifi_rssi()

void protocore_physical_wifi_rssi ( uint8_t * work )

◆ protocore_physical_wifi_ap_ip()

void protocore_physical_wifi_ap_ip ( uint8_t * work )

◆ protocore_physical_wifi_mac()

void protocore_physical_wifi_mac ( uint8_t * work )

◆ protocore_physical_eth_init()

void protocore_physical_eth_init ( uint8_t * work )

◆ protocore_physical_eth_ready()

void protocore_physical_eth_ready ( uint8_t * work )

◆ protocore_physical_ip6_init()

void protocore_physical_ip6_init ( uint8_t * work )

◆ protocore_physical_ip6_global()

void protocore_physical_ip6_global ( uint8_t * work )

◆ protocore_physical_ip6_ready()

void protocore_physical_ip6_ready ( uint8_t * work )

◆ protocore_physical_egress()

void protocore_physical_egress ( uint8_t * work )

◆ protocore_physical_egress_ip()

void protocore_physical_egress_ip ( uint8_t * work )

◆ protocore_physical_egress_mac()

void protocore_physical_egress_mac ( uint8_t * work )

◆ protocore_physical_classify_ip()

void protocore_physical_classify_ip ( uint8_t * work )

◆ protocore_physical_iface_add()

void protocore_physical_iface_add ( uint8_t * work )

◆ protocore_physical_iface_reset()

void protocore_physical_iface_reset ( uint8_t * work )

◆ protocore_physical_iface_present()

void protocore_physical_iface_present ( uint8_t * work )

◆ protocore_physical_iface_kind()

void protocore_physical_iface_kind ( uint8_t * work )

◆ protocore_physical_iface_at()

void protocore_physical_iface_at ( uint8_t * work )

◆ protocore_physical_iface_count()

void protocore_physical_iface_count ( uint8_t * work )

◆ protocore_physical_iface_send()

void protocore_physical_iface_send ( uint8_t * work )

◆ protocore_physical_span()

uint8_t * protocore_physical_span ( void )

The PROTOCORE_PHYSICAL_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns: the span.

Variable Documentation

◆ PhysicalV

PhysicalVars PhysicalV

extern

The operands and the outcome.

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ PROTOCORE_PHYSICAL_HAS_BACKEND

◆ PROTOCORE_IF_NONE

Typedef Documentation

◆ protocore_phy_ps

◆ protocore_phy_frame_fn

◆ protocore_if_send_fn

Enumeration Type Documentation

◆ PROTO_ENUM_PACKED

Function Documentation

◆ init_wifi_physical()

◆ wifi_ready()

◆ init_wifi_radio_physical()

◆ init_wifi_ap_physical()

◆ init_eth_physical()

◆ eth_ready()

◆ init_ipv6_physical()

◆ net_global_ipv6()

◆ protocore_ipv6_ready()

◆ protocore_net_egress()

◆ protocore_net_egress_ip()

◆ protocore_net_ap_ip()

◆ protocore_net_rssi()

◆ protocore_net_mac()

◆ protocore_net_egress_mac()

◆ protocore_net_ssid()

◆ protocore_net_channel()

◆ protocore_net_classify_ip()

◆ protocore_phy_ps_set()

◆ protocore_phy_ps_get()

◆ protocore_phy_tx_power_set()

◆ protocore_phy_monitor_begin()

◆ protocore_phy_monitor_set_channel()

◆ protocore_phy_monitor_end()

◆ protocore_physical_wifi_init()

◆ protocore_physical_wifi_ready()

◆ protocore_physical_wifi_radio_init()

◆ protocore_physical_wifi_ap_init()

◆ protocore_physical_wifi_ssid()

◆ protocore_physical_wifi_channel()

◆ protocore_physical_wifi_rssi()

◆ protocore_physical_wifi_ap_ip()

◆ protocore_physical_wifi_mac()

◆ protocore_physical_eth_init()

◆ protocore_physical_eth_ready()

◆ protocore_physical_ip6_init()

◆ protocore_physical_ip6_global()

◆ protocore_physical_ip6_ready()

◆ protocore_physical_egress()

◆ protocore_physical_egress_ip()

◆ protocore_physical_egress_mac()

◆ protocore_physical_classify_ip()

◆ protocore_physical_iface_add()

◆ protocore_physical_iface_reset()

◆ protocore_physical_iface_present()

◆ protocore_physical_iface_kind()

◆ protocore_physical_iface_at()

◆ protocore_physical_iface_count()

◆ protocore_physical_iface_send()

◆ protocore_physical_span()

Variable Documentation

◆ PhysicalV