Switch configuration and pause control

Header: openenoc_switch_config.h

Implementation: openenoc_switch_config.c

These functions manage the default forwarding bitmap, operation mode, and explicit pause handshake. The shared pointer, serialization and return-value contracts are specified in Switch API. Abbreviated status names use the OPENENOC_SWITCH_STATUS_ prefix.

The default bitmap applies when no enabled forwarding-table entry matches. Its bits follow the RDL interface order; bits above the generated interface count must be zero. A zero bitmap drops unmatched frames. Bitmap reads require a completed pause in either mode, and bitmap writes require managed mode and a completed pause. Neither operation changes mode or pause state.

Mode and status queries are available while forwarding is active. Changing mode requires a completed pause and leaves the pause request asserted. The caller controls when to resume after finishing an update. Pause and resume submissions are non-blocking: a successful call is separate from hardware reaching the requested state. The HAL supplies no polling loop or software timeout.

Default forwarding

openenoc_switch_status_t openenoc_switch_get_default_forwarding(volatile const csr__switch_interface_t *switch_interface, uint32_t *bitmap)

Read the bitmap used for unmatched frames.

Parameters:

switch_interface – In; required mapped, word-aligned switch-interface pointer.
bitmap – Out; required destination for the current output-interface bitmap. In RDL interface order, bit interface_count - 1 selects the first interface.

Returns:

OK; INVALID_ARGUMENT for an invalid switch pointer or missing output; NOT_READY without a completed pause.

Preconditions:

pause_request and pause_done must both be set. Either operation mode is allowed.

Side effects:

Reads forwarding-control and default-bitmap CSRs. Updates the output only on success; preserves mode and pause state.

openenoc_switch_status_t openenoc_switch_set_default_forwarding(volatile csr__switch_interface_t *switch_interface, uint32_t bitmap)

Set the bitmap used for unmatched frames.

Parameters:

switch_interface – In; required mapped, word-aligned switch-interface pointer.
bitmap – In; output-interface selection, including zero for drop. In RDL interface order, bit interface_count - 1 selects the first interface. Unimplemented bits must be zero.

Returns:

OK; INVALID_ARGUMENT for an invalid switch pointer; OUT_OF_RANGE for bits outside the generated interface count; NOT_ALLOWED in unmanaged mode; NOT_READY in managed mode without a completed pause.

Preconditions:

Managed mode and a completed pause. Argument validation precedes mode and pause checks; the mode check precedes the pause check.

Side effects:

Writes the default bitmap after validation. Preserves mode, pause state, and table entries.

Operation mode

openenoc_switch_status_t openenoc_switch_get_operation_mode(volatile const csr__switch_interface_t *switch_interface, openenoc_switch_operation_mode_t *mode)

Read the current managed or unmanaged operation mode.

Parameters:

switch_interface – In; required mapped, word-aligned switch-interface pointer.
mode – Out; required destination for the current operation-mode enum.

Returns:

OK; INVALID_ARGUMENT for an invalid switch pointer or missing output.

Preconditions:

No pause is required.

Side effects:

Reads the mode CSR field and updates the output only on success; preserves all switch state.

openenoc_switch_status_t openenoc_switch_set_operation_mode(volatile csr__switch_interface_t *switch_interface, openenoc_switch_operation_mode_t mode)

Explicitly change the switch operation mode.

Parameters:

switch_interface – In; required mapped, word-aligned switch-interface pointer.
mode – In; OPENENOC_SWITCH_UNMANAGED or OPENENOC_SWITCH_MANAGED.

Returns:

OK; INVALID_ARGUMENT for an invalid switch pointer or mode; NOT_READY without a completed pause, including a request to retain the current mode.

Preconditions:

pause_request and pause_done must both be set. The current mode may be managed or unmanaged.

Side effects:

Writes only the operation-mode field. Preserves pause request, default bitmap, and table contents. Unmanaged mode permits hardware learning after forwarding resumes.

Pause handshake

openenoc_switch_status_t openenoc_switch_get_status(volatile const csr__switch_interface_t *switch_interface, openenoc_switch_forwarding_status_t *status)

Read the current pause request and hardware completion indication.

Parameters:

switch_interface – In; required mapped, word-aligned switch-interface pointer.
status – Out; required destination for pause_requested and pause_done.

Returns:

OK; INVALID_ARGUMENT for an invalid switch pointer or missing output.

Preconditions:

No pause is required; callers can poll this function during a pause transition.

Side effects:

Reads both forwarding-control fields and updates the output only on success. Does not clear status or change mode or pause request.

openenoc_switch_status_t openenoc_switch_request_pause(volatile csr__switch_interface_t *switch_interface)

Explicitly request a pause at a safe forwarding boundary.

Parameters:

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

Returns:

OK after setting the request; INVALID_ARGUMENT for an invalid switch pointer.

Preconditions:

Either mode and any current pause state are allowed.

Side effects:

Sets pause_request to one and preserves operation mode. Repeated calls are idempotent. Does not wait for pause_done; the caller polls status before data access.

openenoc_switch_status_t openenoc_switch_resume(volatile csr__switch_interface_t *switch_interface)

Explicitly release the pause request.

Parameters:

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

Returns:

OK after clearing the request; INVALID_ARGUMENT for an invalid switch pointer.

Preconditions:

Either mode and any current pause state are allowed.

Side effects:

Clears pause_request and preserves operation mode. Repeated calls are idempotent. Does not wait for pause_done to clear; a remaining completion indication does not authorize data access after resume.

Public declarations

The maintained header below provides the exact public mode and status types.

Switch operation-mode and forwarding-status types

typedef enum {
    OPENENOC_SWITCH_UNMANAGED = 0,
    OPENENOC_SWITCH_MANAGED = 1
} openenoc_switch_operation_mode_t;

typedef struct {
    bool pause_requested;
    bool pause_done;
} openenoc_switch_forwarding_status_t;