Runtime API Reference

This reference specifies the endpoint and switch HAL functions, their parameters, return values, preconditions, and observable effects. The CSR programming model is specified in HAL Architecture Specification and the generated endpoint CSR reference and switch CSR reference.

Endpoint API

HAL libraries

Each endpoint HAL library has its own page. The hierarchy below lists its documented functions. Shared contracts, types and utilities are specified on this page.

Public contract

Umbrella header: openenoc_endpoint.h

The runtime API follows the principle that existing function names, prototypes, HAL-owned data layouts, and behavior remain stable across compatible RDL changes. New functionality uses additive interfaces. Each group has a public header and implementation. openenoc_endpoint.h includes the group headers; openenoc_endpoint_common.h includes the selected PeakRDL csr.h.

Public function declarations use conditional extern "C" linkage in C++. C++ applications can include the group headers directly and link with the library sources compiled as C, using the same function names and prototypes.

The endpoint argument is the mapped csr__endpoint_interface_t pointer. Mutating operations take volatile csr__endpoint_interface_t *; read-only queries take const volatile csr__endpoint_interface_t *. The pointer is required and word-aligned, except when explicitly unbinding IRQ callbacks. The mapping, callbacks and context must remain valid while in use. Concurrent access to the same command registers requires caller serialization.

openenoc_endpoint_init validates that the endpoint pointer is non-null and aligned to four bytes. It performs no MMIO access. openenoc_endpoint_get_info returns the generated dimensions, capabilities and limits without MMIO. Feature-dependent functions check the generated CSR__HAS_* constants before validating arguments or touching registers. An absent feature returns UNSUPPORTED immediately, except that explicit IRQ unbinding remains available. Register operations access generated .f fields directly through the endpoint pointer, without register-pointer lookup helpers.

Integration supplies the mapped openenoc_endpoint_interface subtree. HAL accesses its generated .f fields directly and uses no manually computed MMIO offsets, additional offset generator, root CSR type, switch block or endpoint-specific base address. CSR values and address calculations use at most 32 bits; MAC values use lower 32-bit and upper 16-bit fields.

The generated register type follows the RDL layout. Integration must supply hardware matching the selected generated header. Rebuild HAL with the matching header after a layout change. The RMEM getter returns a 32-bit pointer to the first generated rmem.word element; the implementation verifies alignment and stride. The software build requires explicit APP and EP selections; PLATFORM selects the CPU support implementation.

For functions returning openenoc_endpoint_status_t, the abbreviated status names below have the OPENENOC_ENDPOINT_STATUS_ prefix. A successful command submission is separate from hardware acceptance and completion.

Local call-result values
Status	Meaning
`OK`	The local call succeeded; submitted work may still be pending.
`NOT_READY`	Active work or pending commands prevent submission, no beat or claim is available, or the stream handshake is pending.
`INVALID_ARGUMENT`	A required pointer, its alignment, an enum, or a value is invalid.
`OUT_OF_RANGE`	An index, address range, length, or configured size exceeds its bounds.
`UNSUPPORTED`	The requested feature is absent from the selected generated specification.
`HARDWARE_MISMATCH`	Reserved for type stability; no current function returns this value.

Hardware errors use the separate openenoc_endpoint_error_t type. DMA error state is sticky: new requests and successful completions preserve it. Explicit error clearing is separate from IRQ claim completion. Peer error state is shared by peer DMA, RMEM, and failures while servicing incoming requests, so it is not a per-operation result. Concurrent failures may replace its code. Failed transfers may leave memory partially updated.

The RMEM region is one contiguous window exposed as a volatile pointer. Peer mapping selects the oETP transaction in hardware. Direct accesses are blocking MMIO with an ACK-only failure boundary; all-ones read data is not a unique failure indicator. Device-memory mapping, supported access widths, memory ordering, and DMA coherency follow the target platform’s requirements. The current CSR bus supports aligned 32-bit accesses.

Public data types

Runtime type semantics
Type	Meaning
`csr__endpoint_interface_t`	Generated endpoint-interface register type; passed as a mapped pointer.
`openenoc_endpoint_mac_t`	Six MAC octets in network address order.
`openenoc_endpoint_info_t`	Peer count, RMEM capacity in words, feature flags, raw-frame and peer-fragment limits in bytes.
`openenoc_endpoint_config_t`	MACs, receive policy, response timeouts in endpoint cycles, and written fragment size in bytes.
`openenoc_endpoint_peer_config_t`	Peer MAC, byte RMEM offset, 32-bit local/remote bus addresses, byte size, mode, and IRQ enable.
`openenoc_endpoint_peer_status_t`	Pending request/clear, local DMA idle/done, and shared sticky error/code.
`openenoc_endpoint_non_oetp_dma_status_t`	Pending commands, idle/armed/done, sticky error/code, and transferred or received byte count.
`openenoc_endpoint_rmem_region_t`	Mapped `volatile uint32_t *words` and capacity `word_count`.
`openenoc_endpoint_irq_claim_t`	Event source, peer index, and sequence identifying the current claim.
`openenoc_endpoint_irq_config_t`	Global output enable and six independent event enables.
`openenoc_endpoint_irq_status_t`	Pending/full/errors/output state and saturated FIFO/reservation counts.
`openenoc_endpoint_irq_callbacks_t`	Six named source callbacks, optional error callback, and opaque application context.

The exact declarations and enum values are included from the common header below and the group headers on their respective library pages.

Initialization and information

Header: openenoc_endpoint_common.h

Implementation: openenoc_endpoint_common.c

openenoc_endpoint_status_t openenoc_endpoint_init(volatile csr__endpoint_interface_t *endpoint)

Validate the endpoint pointer and its alignment.

Parameters:

endpoint – In; required mapped, word-aligned generated endpoint-interface pointer.

Returns:

OK for a non-null pointer aligned to four bytes; INVALID_ARGUMENT otherwise.

Preconditions:

Integration supplies the mapped endpoint-interface subtree and hardware matching the selected generated header.

Side effects:

None. Performs no MMIO access, allocation or state initialization.

openenoc_endpoint_status_t openenoc_endpoint_get_info(volatile const csr__endpoint_interface_t *endpoint, openenoc_endpoint_info_t *info)

Return dimensions, capabilities and limits from the generated specification.

Parameters:

endpoint – In; required mapped, word-aligned endpoint-interface pointer.
info – Out; required generated-information destination.

Returns:

OK; INVALID_ARGUMENT for a null or unaligned endpoint pointer or missing output.

Preconditions:

Integration supplies hardware matching the selected generated header.

Side effects:

Writes metadata from generated constants to the output; performs no MMIO access.

Public declarations

The maintained common header below provides the exact shared type and enum definitions. Group-specific declarations are included on the library pages.

Endpoint common runtime types and declarations

typedef enum {
    OPENENOC_ENDPOINT_STATUS_OK = 0,
    OPENENOC_ENDPOINT_STATUS_NOT_READY = 2,
    OPENENOC_ENDPOINT_STATUS_INVALID_ARGUMENT = 3,
    OPENENOC_ENDPOINT_STATUS_OUT_OF_RANGE = 4,
    OPENENOC_ENDPOINT_STATUS_UNSUPPORTED = 5,
    OPENENOC_ENDPOINT_STATUS_HARDWARE_MISMATCH = 6
} openenoc_endpoint_status_t;

typedef enum {
    OPENENOC_ENDPOINT_ERROR_NONE = 0,
    OPENENOC_ENDPOINT_ERROR_LOCAL_INVALID = 1,
    OPENENOC_ENDPOINT_ERROR_LOCAL_STREAM = 2,
    OPENENOC_ENDPOINT_ERROR_LOCAL_SIZE = 3,
    OPENENOC_ENDPOINT_ERROR_LOCAL_READ_SLVERR = 4,
    OPENENOC_ENDPOINT_ERROR_LOCAL_READ_DECERR = 5,
    OPENENOC_ENDPOINT_ERROR_LOCAL_WRITE_SLVERR = 6,
    OPENENOC_ENDPOINT_ERROR_LOCAL_WRITE_DECERR = 7,
    OPENENOC_ENDPOINT_ERROR_TIMEOUT = 8,
    OPENENOC_ENDPOINT_ERROR_REMOTE_INVALID = 9,
    OPENENOC_ENDPOINT_ERROR_REMOTE_STREAM = 10,
    OPENENOC_ENDPOINT_ERROR_REMOTE_SIZE = 11,
    OPENENOC_ENDPOINT_ERROR_REMOTE_READ_SLVERR = 12,
    OPENENOC_ENDPOINT_ERROR_REMOTE_READ_DECERR = 13,
    OPENENOC_ENDPOINT_ERROR_REMOTE_WRITE_SLVERR = 14,
    OPENENOC_ENDPOINT_ERROR_REMOTE_WRITE_DECERR = 15
} openenoc_endpoint_error_t;

typedef struct {
    uint8_t octet[6];
} openenoc_endpoint_mac_t;

typedef struct {
    uint32_t rmem_word_count;
    uint32_t peer_count;
    uint32_t max_raw_frame_size_bytes;
    uint32_t max_peer_fragment_size_bytes;
    bool peer_dma_supported;
    bool non_oetp_dma_supported;
    bool direct_axis_supported;
    bool rmem_supported;
    bool irq_supported;
} openenoc_endpoint_info_t;

openenoc_endpoint_status_t openenoc_endpoint_init(
    volatile csr__endpoint_interface_t *endpoint);

openenoc_endpoint_status_t openenoc_endpoint_get_info(
    const volatile csr__endpoint_interface_t *endpoint, openenoc_endpoint_info_t *info);

#ifdef __cplusplus
}
#endif

Switch API

HAL libraries

The switch API contains common initialization and information queries, configuration and pause control, and forwarding-table access. Each group has a public header and implementation. The common contract and types are specified here; the group pages describe each function’s arguments and effects.

Public contract

Umbrella header: openenoc_switch.h

openenoc_switch_common.h includes the selected generated csr.h. Public declarations provide conditional extern "C" linkage for C++ callers; the implementations are compiled as C. Existing function names, prototypes, HAL-owned types and behavior follow the same compatibility contract as the endpoint API.

The switch argument is the mapped csr__switch_interface_t subtree. Mutating operations take volatile csr__switch_interface_t *; read-only operations take const volatile csr__switch_interface_t *. It must be non-null and aligned to four bytes. Integration supplies hardware matching the selected generated header and keeps the mapping valid while the API is in use. Register operations access generated .f fields directly. MAC addresses use lower 32-bit and upper 16-bit fields; no software register offsets or root CSR pointer are required by HAL.

openenoc_switch_init only validates the pointer. It does not reset the switch or alter its mode, pause request, default bitmap, or forwarding table. openenoc_switch_get_info returns CSR__NUM_OF_INTERFACES and CSR__TABLE_DEPTH from the selected generated header. Neither function performs MMIO or verifies that live hardware matches the header.

The caller serializes all accesses to the same switch and keeps its mode and pause state stable throughout a data access. Device-memory mapping and MMIO ordering follow the target platform’s requirements. Output arguments are updated only when a getter returns OK.

Pause and access rules

A completed pause requires both forwarding_control.pause_request and forwarding_control.pause_done to be set. A stale pause_done after resume is not sufficient. The pause request is a level held until an explicit openenoc_switch_resume call. openenoc_switch_request_pause and openenoc_switch_resume are idempotent and do not wait for hardware progress. Status and mode queries remain available during forwarding and pause transitions.

Switch access requirements
Operation	Required mode	Pause requirement
Initialization and information	Either	None; no MMIO
Mode and forwarding-status queries	Either	None
Request pause or resume	Either	None
Set operation mode	Either	Completed pause
Read default bitmap or table entry	Either	Completed pause
Write default bitmap, entry, enable state, or clear table	Managed	Completed pause

Default-bitmap and table operations preserve both operation mode and pause request. A caller changes them only through the dedicated control functions. For a safe update, request pause, poll status until both pause fields are set, explicitly select managed mode, perform the desired writes, select any desired final mode while still paused, and resume. The pause establishes a safe state for forwarding-table access; already routed frames may remain in egress queues.

Arguments are validated before state-dependent MMIO checks or writes. For valid write arguments, unmanaged mode returns NOT_ALLOWED before pause readiness is checked. A managed write or any data read without a completed pause returns NOT_READY. Returning an error does not modify switch configuration or caller output destinations.

For openenoc_switch_status_t, abbreviated values below use the OPENENOC_SWITCH_STATUS_ prefix.

Switch local call-result values
Status	Value	Meaning
`OK`	0	The local call succeeded. Pause or resume may still be propagating in hardware.
`NOT_READY`	2	A data access or operation-mode change requires a completed pause.
`INVALID_ARGUMENT`	3	The switch pointer, its alignment, a required argument, or a mode enum is invalid.
`OUT_OF_RANGE`	4	A table index or destination bitmap exceeds the generated dimensions.
`UNSUPPORTED`	5	Reserved for compatibility with endpoint statuses; currently not returned.
`HARDWARE_MISMATCH`	6	Reserved for compatibility with endpoint statuses; currently not returned.
`NOT_ALLOWED`	7	A data write was attempted in unmanaged mode.

Public data types

Switch runtime type semantics
Type	Meaning
`csr__switch_interface_t`	Generated switch-interface register type; passed as a mapped subtree pointer.
`openenoc_switch_status_t`	Local call result, separate from forwarding state.
`openenoc_switch_mac_t`	Six destination-MAC octets in network address order.
`openenoc_switch_info_t`	Generated interface count and forwarding-table entry count.
`openenoc_switch_operation_mode_t`	`OPENENOC_SWITCH_UNMANAGED` (0) or `OPENENOC_SWITCH_MANAGED` (1).
`openenoc_switch_forwarding_status_t`	Current pause-request and pause-done fields; both are required for data access.
`openenoc_switch_table_entry_t`	Destination MAC, 32-bit output-interface bitmap, and entry enable state.

Bitmap bits follow the RDL interface order: bit interface_count - 1 selects the first interface and bit zero selects the last. Bits above the implemented interface count must be zero. An empty bitmap is valid: it drops unmatched frames when used as the default, or matching frames when used in an enabled entry. A disabled entry is ignored by lookup. Multicast and broadcast MAC keys are valid forwarding-table destinations.

Initialization and information

Header: openenoc_switch_common.h

Implementation: openenoc_switch_common.c

openenoc_switch_status_t openenoc_switch_init(volatile csr__switch_interface_t *switch_interface)

Validate the switch pointer and its alignment.

Parameters:

switch_interface – In; required mapped, word-aligned generated switch-interface pointer.

Returns:

OK for a non-null pointer aligned to four bytes; INVALID_ARGUMENT otherwise.

Preconditions:

Integration supplies the mapped switch subtree and hardware matching the selected generated header.

Side effects:

None. Performs no MMIO, allocation, or switch initialization writes.

openenoc_switch_status_t openenoc_switch_get_info(volatile const csr__switch_interface_t *switch_interface, openenoc_switch_info_t *info)

Return the switch dimensions from the generated specification.

Parameters:

switch_interface – In; required mapped, word-aligned switch-interface pointer.
info – Out; required destination for interface_count and table_depth.

Returns:

OK; INVALID_ARGUMENT for a null or unaligned switch pointer or missing output.

Side effects:

Writes generated dimensions into the output; performs no MMIO and preserves switch state.

Public declarations

The maintained common header provides the exact public status values, common types, and declarations. Group-specific types appear on their library pages.

Switch common runtime types and declarations

typedef enum {
    OPENENOC_SWITCH_STATUS_OK = 0,
    OPENENOC_SWITCH_STATUS_NOT_READY = 2,
    OPENENOC_SWITCH_STATUS_INVALID_ARGUMENT = 3,
    OPENENOC_SWITCH_STATUS_OUT_OF_RANGE = 4,
    OPENENOC_SWITCH_STATUS_UNSUPPORTED = 5,
    OPENENOC_SWITCH_STATUS_HARDWARE_MISMATCH = 6,
    OPENENOC_SWITCH_STATUS_NOT_ALLOWED = 7
} openenoc_switch_status_t;

// MAC octets use network address order.
typedef struct {
    uint8_t octet[6];
} openenoc_switch_mac_t;

typedef struct {
    uint32_t interface_count;
    uint32_t table_depth;
} openenoc_switch_info_t;

openenoc_switch_status_t openenoc_switch_init(
    volatile csr__switch_interface_t *switch_interface);

openenoc_switch_status_t openenoc_switch_get_info(
    const volatile csr__switch_interface_t *switch_interface, openenoc_switch_info_t *info);

#ifdef __cplusplus
}
#endif

Runtime assertions

Header: assert.h

Implementation: assert.c

These utilities are shared by endpoint and switch applications.

The shared assert.h provides runtime assertions alongside the generated header’s C11 static_assert compatibility definition. Defining NDEBUG disables runtime assertions: the macro expands to ((void)0) without evaluating its argument. Calls and other required side effects must execute before an assertion checks their results. Compile-time assertions remain enabled.

assert(expression)

Parameters:

expression – Scalar condition; evaluated exactly once when NDEBUG is absent. Not evaluated when NDEBUG is defined.

Returns:

A void expression when disabled or when the condition is true. An enabled false condition never returns.

Side effects:

An enabled failure passes __FILE__ and __LINE__ to openenoc_assert_fail, which records diagnostics and traps the CPU. A disabled assertion has no side effects and generates no runtime operation.

void openenoc_assert_fail(const char *file, uint32_t line)

Parameters:

file – In; pointer to the source filename, normally the __FILE__ string literal.
line – In; source line number, normally __LINE__.

Returns:

Never returns.

Side effects:

Writes failure_file and failure_line into _openenoc_assert_status, publishes OPENENOC_ASSERT_STATUS_FAILED, then executes __builtin_trap(). Completed coverage remains available.

openenoc_assert_status_t and the volatile instance _openenoc_assert_status are declared in assert.h. Its conditional definition is enabled only by assert.c through OPENENOC_ASSERT_IMPLEMENTATION; other translation units receive an extern declaration. The instance is initialized to zero in .data._openenoc_assert_status, which the PicoRV32 linker retains at the start of DMEM. Applications write completed coverage and successful completion; the failure handler writes diagnostics and the failure status before trapping.

Assertion status fields
Field	Type	Meaning
`status`	`uint32_t`	Zero before a result; `OPENENOC_ASSERT_STATUS_PASSED` (`0x600d600d`) after success, or `OPENENOC_ASSERT_STATUS_FAILED` (`0xbad0bad0`) on failure.
`completed_checks`	`uint32_t`	Application-defined bitmask of successfully completed test groups.
`failure_line`	`uint32_t`	Failing source line; zero before failure.
`failure_file`	`const char *`	Pointer to the failing source filename; null before failure.

Contract verification

sw/apps/endpoint_test/main.c implements capability-dependent endpoint API and transfer checks. The dv/endpoints/openenoc_endpoint_full/ suite checks frames, memory, DMA and IRQ claims against RTL. Broader hardware/software verification is documented in Verification Infrastructure.