can.h File Reference

Classic CAN value frames and caller-owned mailbox requests. More...

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

Go to the source code of this file.

Data Structures
struct	nx_can_frame_t
	Classic 2.0A/B value frame; DLC is always 0..8, never CAN FD. More...
struct	nx_can_tx_request_t
	Caller-owned frame copied at prepare; base must first be initialized. More...
struct	nx_can_event_t
	Value receive fact or ordered loss boundary. More...
struct	nx_can_state_t
	Latched controller state, independent of receive-ring fullness. More...
struct	nx_can_ops_t
	Shared immutable operations; execution owner serializes task methods. More...
struct	nx_can_port_t
	Immutable face; lookup does not allocate, start or acquire hardware. More...

Macros
#define	NX_CAN_LOSS_SOFTWARE   1U
#define	NX_CAN_LOSS_HARDWARE_LOWER_BOUND   2U
#define	NX_CAN_LOSS_SATURATED   4U
#define	NX_CAN_DLC_NORMALIZED   8U

Enumerations
enum	nx_can_format_t { NX_CAN_STANDARD , NX_CAN_EXTENDED }
enum	nx_can_frame_kind_t { NX_CAN_DATA , NX_CAN_REMOTE }
enum	nx_can_event_kind_t { NX_CAN_EVENT_FRAME , NX_CAN_EVENT_LOSS }

Functions
nx_result_t	nx_can_tx_prepare (nx_can_tx_request_t *request, const nx_can_frame_t *frame, nx_time_us_t deadline)
	Validate and copy a classic frame into unborrowed request storage.
nx_result_t	nx_can_port_submit (const nx_can_port_t *port, nx_can_tx_request_t *request)
	Admit one frame into one of three hardware mailboxes.
nx_result_t	nx_can_port_cancel (const nx_can_port_t *port, nx_can_tx_request_t *request)
	Request abort without revoking a borrowed request.
nx_result_t	nx_can_port_service (const nx_can_port_t *port)
	Process latched completions and absolute timeout/drain deadlines.
nx_result_t	nx_can_port_read_events (const nx_can_port_t *port, nx_can_event_t *events, size_t capacity, size_t *count)
	Consume value events without overwriting earlier unconsumed facts.
nx_result_t	nx_can_port_state (const nx_can_port_t *port, nx_can_state_t *state)
	Copy authoritative error/admission state, even when RX is full.
nx_result_t	nx_can_port_stop (const nx_can_port_t *port)
	Close admission, abort TX and detach IRQ/RX publishers.
nx_result_t	nx_can_port_recover (const nx_can_port_t *port)
	Explicitly reenter initialization after bus-off and complete drain.
nx_result_t	nx_can_port_attach_wake (const nx_can_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
	Borrow an optional wake target after checking all four actual IRQs.

Detailed Description

Classic CAN value frames and caller-owned mailbox requests.

Author

Nexus Team

Definition in file can.h.

Macro Definition Documentation

NX_CAN_DLC_NORMALIZED

#define NX_CAN_DLC_NORMALIZED   8U

Definition at line 35 of file can.h.

NX_CAN_LOSS_HARDWARE_LOWER_BOUND

#define NX_CAN_LOSS_HARDWARE_LOWER_BOUND   2U

Definition at line 33 of file can.h.

NX_CAN_LOSS_SATURATED

#define NX_CAN_LOSS_SATURATED   4U

Definition at line 34 of file can.h.

NX_CAN_LOSS_SOFTWARE

#define NX_CAN_LOSS_SOFTWARE   1U

Definition at line 32 of file can.h.

Enumeration Type Documentation

nx_can_event_kind_t

enum nx_can_event_kind_t

Enumerator
NX_CAN_EVENT_FRAME
NX_CAN_EVENT_LOSS

Definition at line 31 of file can.h.

nx_can_format_t

enum nx_can_format_t

Enumerator
NX_CAN_STANDARD
NX_CAN_EXTENDED

Definition at line 15 of file can.h.

nx_can_frame_kind_t

enum nx_can_frame_kind_t

Enumerator
NX_CAN_DATA
NX_CAN_REMOTE

Definition at line 16 of file can.h.

Function Documentation

nx_can_port_attach_wake()

nx_result_t nx_can_port_attach_wake	(	const nx_can_port_t *	port,
		const nx_irq_wake_t *	wake,
		uint8_t	syscall_ceiling )

Borrow an optional wake target after checking all four actual IRQs.

Parameters

[in]	port	Serialized task owner, started and masks clear.
[in]	wake	Immutable target kept alive until successful stop/detach.
[in]	syscall_ceiling	Additional numerical BASEPRI ceiling.

Returns

Success, BUSY while an earlier publisher is live, PERMISSION, INVALID or CONTEXT, with no new borrow on failure.

Note

No implicit OS policy; NULL detaches. Wake is only a hint. The sink must support both task service/cancel and configurable IRQ contexts.

nx_can_port_cancel()

nx_result_t nx_can_port_cancel	(	const nx_can_port_t *	port,
		nx_can_tx_request_t *	request )

Request abort without revoking a borrowed request.

Parameters

[in]	port	Stable face owned by the serialized task executor.
[in,out]	request	Live request previously accepted by this instance.

Returns

Success requests drain; STATE for an unrelated request.

Note

Abort may race real transmission; observed TXOK remains SUCCESS. Failed abort remains QUARANTINED and must keep storage alive.

nx_can_port_read_events()

nx_result_t nx_can_port_read_events	(	const nx_can_port_t *	port,
		nx_can_event_t *	events,
		size_t	capacity,
		size_t *	count )

Consume value events without overwriting earlier unconsumed facts.

Parameters

[in]	port	Stable instance; one task consumer owns this operation.
[out]	events	Caller capacity; no retained output reference.
[in]	capacity	Nonzero number of event records.
[out]	count	Number copied; EMPTY means zero available.

Returns

Success, EMPTY, INVALID or CONTEXT.

Note

Each bounded record copy has a short metadata exclusion; pending loss is ordered after older records and before future frames.

nx_can_port_recover()

nx_result_t nx_can_port_recover

(

const nx_can_port_t *

port

)

Explicitly reenter initialization after bus-off and complete drain.

Parameters

[in]

port

Started owner with no active/quarantined TX slots.

Returns

Success after bounded hardware acknowledgement, BUSY while borrowed.

Note

No automatic recovery or retransmission; domain/filter identity stays.

nx_can_port_service()

nx_result_t nx_can_port_service

(

const nx_can_port_t *

port

)

Process latched completions and absolute timeout/drain deadlines.

Parameters

[in]

port

Serialized task-owner face with incoming masks clear.

Returns

Success, STATE before start, CONTEXT for an illegal caller.

Note

Bounded three-mailbox/six-frame work, no worker, blocking or replay.

nx_can_port_state()

nx_result_t nx_can_port_state	(	const nx_can_port_t *	port,
		nx_can_state_t *	state )

Copy authoritative error/admission state, even when RX is full.

Parameters

[in]	port	Live instance and storage.
[out]	state	Unretained value output.

Returns

Success, INVALID or CONTEXT.

Note

Task-only, bounded; bus-off is latched until explicit recovery.

nx_can_port_stop()

nx_result_t nx_can_port_stop

(

const nx_can_port_t *

port

)

Close admission, abort TX and detach IRQ/RX publishers.

Parameters

[in]

port

Serialized owner; external observers must also join.

Returns

Success after hardware drain; BUSY retains requests/ring/wake loans.

Note

Never resets the shared primary controller to release a peer's loan. Retry after progress. Success ends provider access to RX/wake storage.

nx_can_port_submit()

nx_result_t nx_can_port_submit	(	const nx_can_port_t *	port,
		nx_can_tx_request_t *	request )

Admit one frame into one of three hardware mailboxes.

Parameters

[in]	port	Stable immutable face and private storage.
[in,out]	request	READY value request, kept alive until SETTLED.

Returns

Success means ACCEPTED, not on-wire completion; other results reject.

Note

Serialized privileged task owner, incoming IRQ masks clear. REJECTED retains nothing. TXOK plus completed/empty hardware proves success.

nx_can_tx_prepare()

nx_result_t nx_can_tx_prepare	(	nx_can_tx_request_t *	request,
		const nx_can_frame_t *	frame,
		nx_time_us_t	deadline )

Validate and copy a classic frame into unborrowed request storage.

Parameters

[in,out]	request	Initialized READY or consumed SETTLED storage.
[in]	frame	Value copied here; remote data bytes are ignored.
[in]	deadline	Absolute provider-clock deadline, including admission.

Returns

Success, INVALID for nonclassic frame, STATE while borrowed.

Note

Task owner only; failure retains no reference and changes no frame.