Full-speed device packets and caller-owned endpoint loans. More...

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

Data Structures
struct	nx_usb_request_t
struct	nx_usb_setup_t
struct	nx_usb_event_t
struct	nx_usb_device_state_t
struct	nx_usb_endpoint_ops_t
	Shared readonly packet methods; context is a selected endpoint. More...
struct	nx_usb_endpoint_port_t
struct	nx_usb_device_ops_t
	Controller identity remains separate from endpoint identities. More...
struct	nx_usb_device_port_t

Enumerations
enum	nx_usb_stage_t { NX_USB_DATA , NX_USB_STATUS }
enum	nx_usb_event_kind_t { NX_USB_EVENT_SETUP , NX_USB_EVENT_RESET , NX_USB_EVENT_SUSPEND , NX_USB_EVENT_RESUME , NX_USB_EVENT_LOSS }

Functions
nx_result_t	nx_usb_in_prepare (nx_usb_request_t request, const uint8_t bytes, size_t length, nx_usb_stage_t stage, uint64_t epoch, nx_time_us_t deadline)
	Prepare one IN packet without reading or borrowing its bytes.
nx_result_t	nx_usb_out_prepare (nx_usb_request_t request, uint8_t bytes, size_t capacity, nx_usb_stage_t stage, uint64_t epoch, nx_time_us_t deadline)
	Prepare an OUT packet capacity without modifying its storage.
nx_result_t	nx_usb_endpoint_submit (const nx_usb_endpoint_port_t port, nx_usb_request_t request)
	Admit one packet, never a hidden queue or complete USB transaction.
nx_result_t	nx_usb_endpoint_cancel (const nx_usb_endpoint_port_t port, nx_usb_request_t request)
	Request endpoint disable/drain without revoking a buffer loan.
nx_result_t	nx_usb_endpoint_stall (const nx_usb_endpoint_port_t *port, bool stalled)
	Set/clear STALL only after the endpoint has no live transfer.
nx_result_t	nx_usb_device_service (const nx_usb_device_port_t *port)
	Task-only bounded progress; deadline never depends on USB SOF.
nx_result_t	nx_usb_device_read_events (const nx_usb_device_port_t port, nx_usb_event_t events, size_t capacity, size_t *count)
	Consume bounded value events; output is never retained.
nx_result_t	nx_usb_device_state (const nx_usb_device_port_t port, nx_usb_device_state_t state)
	Task-only authoritative snapshot, independent of event-ring space.
nx_result_t	nx_usb_device_address (const nx_usb_device_port_t *port, uint64_t epoch, uint8_t address)
	Stage SET_ADDRESS for the matching zero-data standard SETUP.
nx_result_t	nx_usb_device_attach_wake (const nx_usb_device_port_t port, const nx_irq_wake_t wake, uint8_t syscall_ceiling)
	Attach/detach a borrowed task/IRQ-compatible wake hint.
nx_result_t	nx_usb_device_stop (const nx_usb_device_port_t *port)
	Disconnect, disable, drain, detach IRQs, then release clock consumer.

Detailed Description

Full-speed device packets and caller-owned endpoint loans.

Author: Nexus Team

Definition in file usb_device.h.

Enumeration Type Documentation

◆ nx_usb_event_kind_t

enum nx_usb_event_kind_t

Enumerator
NX_USB_EVENT_SETUP
NX_USB_EVENT_RESET
NX_USB_EVENT_SUSPEND
NX_USB_EVENT_RESUME
NX_USB_EVENT_LOSS

Definition at line 30 of file usb_device.h.

◆ nx_usb_stage_t

enum nx_usb_stage_t

Enumerator
NX_USB_DATA
NX_USB_STATUS

Definition at line 13 of file usb_device.h.

Function Documentation

◆ nx_usb_device_address()

nx_result_t nx_usb_device_address	(	const nx_usb_device_port_t *	port,
		uint64_t	epoch,
		uint8_t	address )

Stage SET_ADDRESS for the matching zero-data standard SETUP.

Parameters

[in]	port	Serialized privileged controller owner.
[in]	epoch	Current SETUP identity.
[in]	address	0..127, matching SETUP wValue.

Returns: Success stages only; address applies after real status-IN XFRC.

◆ nx_usb_device_attach_wake()

nx_result_t nx_usb_device_attach_wake	(	const nx_usb_device_port_t *	port,
		const nx_irq_wake_t *	wake,
		uint8_t	syscall_ceiling )

Attach/detach a borrowed task/IRQ-compatible wake hint.

Parameters

[in]	port	Started serialized owner with IRQ masks clear.
[in]	wake	Immutable target, or NULL to detach.
[in]	syscall_ceiling	Additional numerical IRQ priority floor.

Returns: Success after actual priority policy checks, BUSY while publisher remains live; rejection retains no new sink.

◆ nx_usb_device_read_events()

nx_result_t nx_usb_device_read_events	(	const nx_usb_device_port_t *	port,
		nx_usb_event_t *	events,
		size_t	capacity,
		size_t *	count )

Consume bounded value events; output is never retained.

Parameters

[in]	port	Single task consumer and stable controller.
[out]	events	Caller records disjoint from provider and live loans.
[in]	capacity	Positive output count.
[out]	count	Disjoint count output; EMPTY means zero.

Note: Invalid/STATE rejection leaves both outputs unchanged.

Returns: Success, EMPTY or rejection; authoritative latest SETUP is in state.

◆ nx_usb_device_service()

nx_result_t nx_usb_device_service ( const nx_usb_device_port_t * port )

Task-only bounded progress; deadline never depends on USB SOF.

Parameters

[in] port Serialized privileged owner with incoming IRQ masks clear.

Returns: Success requests progress; no clock/endpoint loan is released early.

◆ nx_usb_device_state()

nx_result_t nx_usb_device_state	(	const nx_usb_device_port_t *	port,
		nx_usb_device_state_t *	state )

Task-only authoritative snapshot, independent of event-ring space.

Parameters

[in]	port	Serialized privileged owner with IRQ masks clear.
[out]	state	Disjoint caller snapshot, never retained.

Returns: Success copies state; alias/context rejection leaves output unchanged.

◆ nx_usb_device_stop()

nx_result_t nx_usb_device_stop ( const nx_usb_device_port_t * port )

Disconnect, disable, drain, detach IRQs, then release clock consumer.

Parameters

[in] port Serialized owner; external observers must also join.

Returns: Success ends provider access to endpoint/ring/wake storage; BUSY retains all storage and 48MHz ownership until actual progress.

Note: PIO OUT0 may remain enabled: successful global stop proves disconnect, OUT NAK, no DMA, empty RX FIFO, IRQ withdrawal and publisher join before final SETTLED. No forced reset revokes an unproved accepted borrow.

◆ nx_usb_endpoint_cancel()

nx_result_t nx_usb_endpoint_cancel	(	const nx_usb_endpoint_port_t *	port,
		nx_usb_request_t *	request )

Request endpoint disable/drain without revoking a buffer loan.

Parameters

[in]	port	Same serialized privileged task owner.
[in,out]	request	Live request accepted by this exact endpoint.

Returns: Success requests drain; failures retain all prior accepted loans.

Note: Control OUT0 has no hardware disable command: cancellation may require full device stop to settle. Missing proof becomes QUARANTINED. Reset/SETUP invalidates epochs but releases only after actual source drain.

◆ nx_usb_endpoint_stall()

nx_result_t nx_usb_endpoint_stall	(	const nx_usb_endpoint_port_t *	port,
		bool	stalled )

Set/clear STALL only after the endpoint has no live transfer.

Parameters

[in]	port	Serialized owner, started and IRQ masks clear.
[in]	stalled	Desired STALL; clearing bulk also resets DATA0.

Returns: Success after readback, BUSY retains a pending request.

◆ nx_usb_endpoint_submit()

nx_result_t nx_usb_endpoint_submit	(	const nx_usb_endpoint_port_t *	port,
		nx_usb_request_t *	request )

Admit one packet, never a hidden queue or complete USB transaction.

Parameters

[in]	port	Stable endpoint face and private state.
[in,out]	request	READY packet, buffers alive until acquire SETTLED.

Returns: Success means ACCEPTED; fourth-party buffers are not copied early.

Note: One privileged task executor, IRQ masks clear. IN FIFO writes do not prove host ACK. OUT overrun drains all packet words without overflow.

◆ nx_usb_in_prepare()

nx_result_t nx_usb_in_prepare	(	nx_usb_request_t *	request,
		const uint8_t *	bytes,
		size_t	length,
		nx_usb_stage_t	stage,
		uint64_t	epoch,
		nx_time_us_t	deadline )

Prepare one IN packet without reading or borrowing its bytes.

Parameters

[in,out]	request	Initialized unborrowed request.
[in]	bytes	Immutable packet bytes, NULL only for zero length.
[in]	length	Packet length, no automatic terminating ZLP.
[in]	stage	DATA or control STATUS; STATUS must be zero length.
[in]	epoch	Current SETUP epoch for EP0, zero for bulk endpoints.
[in]	deadline	Absolute independent monotonic clock deadline.

Returns: Success, INVALID or STATE; rejection retains no references.

◆ nx_usb_out_prepare()

nx_result_t nx_usb_out_prepare	(	nx_usb_request_t *	request,
		uint8_t *	bytes,
		size_t	capacity,
		nx_usb_stage_t	stage,
		uint64_t	epoch,
		nx_time_us_t	deadline )

Prepare an OUT packet capacity without modifying its storage.

Parameters

[in,out]	request	Initialized unborrowed request.
[out]	bytes	Borrowed until SETTLED only after accepted submission.
[in]	capacity	At most endpoint MPS; short packets complete normally.
[in]	stage	DATA or zero-capacity control STATUS.
[in]	epoch	Current SETUP epoch for EP0, zero for bulk endpoints.
[in]	deadline	Absolute independent monotonic clock deadline.

Returns: Success, INVALID or STATE; rejection creates no borrow.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ nx_usb_event_kind_t

◆ nx_usb_stage_t

Function Documentation

◆ nx_usb_device_address()

◆ nx_usb_device_attach_wake()

◆ nx_usb_device_read_events()

◆ nx_usb_device_service()

◆ nx_usb_device_state()

◆ nx_usb_device_stop()

◆ nx_usb_endpoint_cancel()

◆ nx_usb_endpoint_stall()

◆ nx_usb_endpoint_submit()

◆ nx_usb_in_prepare()

◆ nx_usb_out_prepare()