ethernet.h File Reference

Caller-owned untagged Ethernet II frames and receive loans. More...

#include "nexus/core/request.h"
#include "nexus/io/wake.h"

Go to the source code of this file.

Data Structures
struct	nx_eth_tx_request_t
	Caller-owned immutable contiguous frame, excluding its hardware FCS. More...
struct	nx_eth_link_t
	Observed PHY fact, supplied explicitly by the external link owner. More...
struct	nx_eth_rx_frame_t
	Complete immutable frame; release requires this exact incarnation. More...
struct	nx_eth_state_t
	Latched facts survive receive backpressure and failed wake hints. More...
struct	nx_eth_ops_t
struct	nx_eth_port_t

Macros
#define	NX_ETH_FRAME_MIN   14U
#define	NX_ETH_FRAME_MAX   1514U
#define	NX_ETH_RX_STORAGE_MIN   1518U
#define	NX_ETH_RX_CRC   1U
#define	NX_ETH_RX_LENGTH   2U
#define	NX_ETH_RX_FRAGMENT   4U
#define	NX_ETH_RX_UNSUPPORTED   8U
#define	NX_ETH_RX_DMA_ERROR   16U
#define	NX_ETH_RX_BACKPRESSURE   32U

Functions
nx_result_t	nx_eth_tx_prepare (nx_eth_tx_request_t *request, const void *data, size_t length, nx_time_us_t deadline)
	Prepare an initialized, unborrowed request and its immutable frame.
nx_result_t	nx_eth_port_submit (const nx_eth_port_t *port, nx_eth_tx_request_t *request)
	Admit one frame into caller-owned hardware descriptors.
nx_result_t	nx_eth_port_cancel (const nx_eth_port_t *port, nx_eth_tx_request_t *request)
	Close TX admission and drain the shared TX engine without replay.
nx_result_t	nx_eth_port_service (const nx_eth_port_t *port)
	Task-owner bounded progress; no worker, lock, pool or wait.
nx_result_t	nx_eth_port_acquire (const nx_eth_port_t *port, nx_eth_rx_frame_t *frame)
	Task-consumer complete-frame loan; EMPTY creates no borrow.
nx_result_t	nx_eth_port_release (const nx_eth_port_t *port, const nx_eth_rx_frame_t *frame)
	Final consumer access; stale, foreign and double releases reject.
nx_result_t	nx_eth_port_state (const nx_eth_port_t *port, nx_eth_state_t *state)
	Copy latched instance/link/error facts; output is not retained.
nx_result_t	nx_eth_port_apply_link (const nx_eth_port_t *port, const nx_eth_link_t *link)
	Apply external PHY observations, not auto-negotiate or invent link.
nx_result_t	nx_eth_port_stop (const nx_eth_port_t *port)
	Close admission and withdraw MAC/DMA/IRQ sources with readback.
nx_result_t	nx_eth_port_attach_wake (const nx_eth_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
	Bind an optional borrowed hint after actual IRQ-policy validation.

Detailed Description

Caller-owned untagged Ethernet II frames and receive loans.

Author

Nexus Team

Definition in file ethernet.h.

Macro Definition Documentation

NX_ETH_FRAME_MAX

#define NX_ETH_FRAME_MAX   1514U

Definition at line 14 of file ethernet.h.

NX_ETH_FRAME_MIN

#define NX_ETH_FRAME_MIN   14U

Definition at line 13 of file ethernet.h.

NX_ETH_RX_BACKPRESSURE

#define NX_ETH_RX_BACKPRESSURE   32U

Definition at line 21 of file ethernet.h.

NX_ETH_RX_CRC

#define NX_ETH_RX_CRC   1U

Definition at line 16 of file ethernet.h.

NX_ETH_RX_DMA_ERROR

#define NX_ETH_RX_DMA_ERROR   16U

Definition at line 20 of file ethernet.h.

NX_ETH_RX_FRAGMENT

#define NX_ETH_RX_FRAGMENT   4U

Definition at line 18 of file ethernet.h.

NX_ETH_RX_LENGTH

#define NX_ETH_RX_LENGTH   2U

Definition at line 17 of file ethernet.h.

NX_ETH_RX_STORAGE_MIN

#define NX_ETH_RX_STORAGE_MIN   1518U

Definition at line 15 of file ethernet.h.

NX_ETH_RX_UNSUPPORTED

#define NX_ETH_RX_UNSUPPORTED   8U

Definition at line 19 of file ethernet.h.

Function Documentation

nx_eth_port_acquire()

nx_result_t nx_eth_port_acquire	(	const nx_eth_port_t *	port,
		nx_eth_rx_frame_t *	frame )

Task-consumer complete-frame loan; EMPTY creates no borrow.

Parameters

[in]	port	Stable started instance and one consumer.
[out]	frame	Exact immutable frame loan, not output storage borrow.

Returns

Success, EMPTY without a loan, or invalid state/context.

nx_eth_port_apply_link()

nx_result_t nx_eth_port_apply_link	(	const nx_eth_port_t *	port,
		const nx_eth_link_t *	link )

Apply external PHY observations, not auto-negotiate or invent link.

Parameters

[in]	port	Serialized task-owner face.
[in]	link	Observed up/speed/duplex fact, never a guess.

Returns

Success, BUSY until real drain, or STATE/IO/context error.

Note

Task owner; changing speed/duplex first requires explicit link-down and observed idle TX/RX engines and FIFOs. BUSY keeps the old mode. Reapplying an unchanged up fact is idempotent. Link-down closes admission and drains pending TX with IO; later up requires real quiescence. This is not a PHY power/reset/electrical proof.

nx_eth_port_attach_wake()

nx_result_t nx_eth_port_attach_wake	(	const nx_eth_port_t *	port,
		const nx_irq_wake_t *	wake,
		uint8_t	syscall_ceiling )

Bind an optional borrowed hint after actual IRQ-policy validation.

Parameters

[in]	port	Started serialized task-owner face.
[in]	wake	Borrowed IRQ hint; NULL requests detach.
[in]	syscall_ceiling	Exact configured unshifted syscall ceiling.

Returns

Success, BUSY while publishers live, or policy/context error.

Note

Task owner with no pending TX; notify is bounded and legal in IRQ. Service does not invoke the IRQ hint from a task. Detach after stop.

nx_eth_port_cancel()

nx_result_t nx_eth_port_cancel	(	const nx_eth_port_t *	port,
		nx_eth_tx_request_t *	request )

Close TX admission and drain the shared TX engine without replay.

Parameters

[in]	port	Serialized task-owner face.
[in,out]	request	Live request accepted by this instance.

Returns

Success requests drain; STATE for a foreign request.

Note

Task owner. Cancel is controller-wide: other pending TX requests also become CANCELLED. It never revokes a borrow. Stuck sources quarantine. Apply a confirmed link again after successful drain to reopen TX.

nx_eth_port_release()

nx_result_t nx_eth_port_release	(	const nx_eth_port_t *	port,
		const nx_eth_rx_frame_t *	frame )

Final consumer access; stale, foreign and double releases reject.

Parameters

[in]	port	The same provider identity as acquisition.
[in]	frame	Exact acquired token after final consumer access.

Returns

Success, STATE for an altered token, or invalid input/context.

Note

A held descriptor is never rearmed, even at ring wrap or stop.

nx_eth_port_service()

nx_result_t nx_eth_port_service

(

const nx_eth_port_t *

port

)

Task-owner bounded progress; no worker, lock, pool or wait.

Parameters

[in]

port

Serialized task-owner face and live storage.

Returns

Success, STATE before startup, or invalid context/input.

nx_eth_port_state()

nx_result_t nx_eth_port_state	(	const nx_eth_port_t *	port,
		nx_eth_state_t *	state )

Copy latched instance/link/error facts; output is not retained.

Parameters

[in]	port	Stable private instance.
[out]	state	Unretained output, separate from all provider storage.

Returns

Success, INVALID for output alias, or CONTEXT.

nx_eth_port_stop()

nx_result_t nx_eth_port_stop

(

const nx_eth_port_t *

port

)

Close admission and withdraw MAC/DMA/IRQ sources with readback.

Parameters

[in]

port

Live face and all storage, including held loans.

Returns

Success releases sources; BUSY/IO retain remaining ownership.

Note

Task owner. Closing rejects new RX loans; existing loans still release. BUSY retains hardware/storage/wake ownership; timeout quarantines pending TX. Held RX loans remain valid and must be released before SUCCESS. Caller joins IRQ/consumers before reclaiming storage.

nx_eth_port_submit()

nx_result_t nx_eth_port_submit	(	const nx_eth_port_t *	port,
		nx_eth_tx_request_t *	request )

Admit one frame into caller-owned hardware descriptors.

Parameters

[in]	port	Stable face and live private assembly.
[in,out]	request	Prepared storage borrowed on acceptance.

Returns

Success means ACCEPTED; BUSY/STATE/IO/invalid inputs reject.

Note

Privileged serialized task, masks clear. SUCCESS is ACCEPTED. Borrow includes request and frame until acquire-observed SETTLED. Completion reports MAC wire status, never delivery to another application.

nx_eth_tx_prepare()

nx_result_t nx_eth_tx_prepare	(	nx_eth_tx_request_t *	request,
		const void *	data,
		size_t	length,
		nx_time_us_t	deadline )

Prepare an initialized, unborrowed request and its immutable frame.

Parameters

[in,out]	request	Initialized READY or consumed SETTLED storage.
[in]	data	Immutable contiguous Ethernet II frame.
[in]	length	Bytes excluding FCS, from 14 through 1514.
[in]	deadline	Absolute provider-clock deadline or NEVER.

Returns

Success, INVALID for frame/overlap, STATE while borrowed.

Note

Task owner. Ethernet II only, 14..1514 bytes excluding FCS; no VLAN or length-coded 802.3. Failure changes no request or payload.