ra8_usb_pal.h File Reference

USB device-mode Platform Abstraction Layer. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_usb.h"

Include dependency graph for ra8_usb_pal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void(*	ra8_usb_pal_event_fn_t) (void *ctx, ra8_usb_speed_t speed, uint16_t event_mask)
	Async event callback shape.

Enumerations
enum	ra8_usb_pal_limits_t : uint16_t {   k_ra8_usb_pal_ep_max = 10U ,   k_ra8_usb_pal_ep0_max_packet = 64U ,   k_ra8_usb_pal_bulk_max_fs = 64U ,   k_ra8_usb_pal_bulk_max_hs = 512U ,   k_ra8_usb_pal_xfer_max = 1024U ,   k_ra8_usb_pal_ep_addr_mask = 0x7FU }
	USB sizing constants. More...
enum	ra8_usb_pal_ep_dir_t : uint8_t {   k_ra8_usb_pal_ep_dir_out = 0U ,   k_ra8_usb_pal_ep_dir_in = 1U }
	Endpoint direction. More...
enum	ra8_usb_pal_ep_type_t : uint8_t {   k_ra8_usb_pal_ep_type_control = 0U ,   k_ra8_usb_pal_ep_type_iso = 1U ,   k_ra8_usb_pal_ep_type_bulk = 2U ,   k_ra8_usb_pal_ep_type_intr = 3U }
	USB endpoint transfer type. More...
enum	ra8_usb_pal_state_t : uint8_t {   k_ra8_usb_pal_state_detached = 0U ,   k_ra8_usb_pal_state_attached = 1U ,   k_ra8_usb_pal_state_default = 2U ,   k_ra8_usb_pal_state_addressed = 3U ,   k_ra8_usb_pal_state_configd = 4U ,   k_ra8_usb_pal_state_suspended = 5U }
	USB device state per chapter 9 of USB 2.0. More...
enum	ra8_usb_pal_event_t : uint16_t {   k_ra8_usb_pal_event_none = 0x0000U ,   k_ra8_usb_pal_event_reset = 0x0001U ,   k_ra8_usb_pal_event_suspend = 0x0002U ,   k_ra8_usb_pal_event_resume = 0x0004U ,   k_ra8_usb_pal_event_setup = 0x0008U ,   k_ra8_usb_pal_event_ep_in = 0x0010U ,   k_ra8_usb_pal_event_ep_out = 0x0020U ,   k_ra8_usb_pal_event_sof = 0x0040U ,   k_ra8_usb_pal_event_attach = 0x0080U ,   k_ra8_usb_pal_event_detach = 0x0100U ,   k_ra8_usb_pal_event_error = 0x8000U }
	Event mask bits passed to ra8_usb_pal_event_fn_t. More...

Functions
ra8_err_t	ra8_usb_pal_init (ra8_usb_speed_t speed)
	Initialise the USB PAL on a specific controller speed.
ra8_err_t	ra8_usb_pal_deinit (void)
	Tear down the USB PAL.
ra8_err_t	ra8_usb_pal_attach (bool attached)
	Raise / drop the D+ pull-up to advertise the device.
ra8_err_t	ra8_usb_pal_get_state (ra8_usb_pal_state_t *out_state)
	Read the current PAL state machine.
ra8_err_t	ra8_usb_pal_ep_open (uint8_t ep_addr, ra8_usb_pal_ep_dir_t dir, ra8_usb_pal_ep_type_t type, uint16_t max_packet)
	Open a non-control endpoint with a given type / direction / size.
ra8_err_t	ra8_usb_pal_ep_send (uint8_t ep_addr, const uint8_t *data, uint16_t len)
	Submit data on an IN endpoint (device -> host).
ra8_err_t	ra8_usb_pal_ep_recv (uint8_t ep_addr, uint8_t *out_buf, uint16_t *inout_len)
	Receive data from an OUT endpoint (host -> device).
ra8_err_t	ra8_usb_pal_set_event_handler (ra8_usb_pal_event_fn_t fn, void *ctx)
	Attach a single event handler for bus / endpoint events.

Detailed Description

USB device-mode Platform Abstraction Layer.

Tag

[Ring 4 / PAL] {World: NS}

scaffold for the USB PAL. Sits between the Ring-3 ra8_usb driver and any higher-level USB stack (CherryUSB today, possibly TinyUSB or a custom stack later).

Responsibilities:

• Own the choice of FS vs HS controller.
• Reset / attach / detach lifecycle.
• Translate ra8_usb status masks into PAL-level event bits.
• Hide the MSTP / clock-gate dance behind ra8_usb_pal_init.

The PAL is intentionally stack-agnostic. CherryUSB's usb_dc_ra8d2_*.c port (added) wraps this API; no CherryUSB types appear in this header.

Layering

+------------------------—+ ra8_usb_pal_attach | USB stack (CherryUSB) | ra8_usb_pal_set_event_handler +--------—+------------—+ | v +------------------------—+ | ra8_usb_pal (this file) | wraps Ring-3 ra8_usb +--------—+------------—+ | v +------------------------—+ | ra8_usb (Ring 3 / HAL) | +------------------------—+

Threading

Single-threaded. Init runs from the boot path; the event handler fires from ra8_usb ISR context.

Endpoint I/O backing store

Each endpoint gets a small software ring (depth k_ra8_usb_pal_ring_slots, per-packet capacity k_ra8_usb_pal_pkt_max) the stack writes to with ra8_usb_pal_ep_send and drains with ra8_usb_pal_ep_recv. On real hardware the ring is backed by the controller pipe FIFOs; in host tests it is a plain RAM buffer. The stack-facing contract is identical in both paths, so CherryUSB's usb_dc_ra8d2_*.c port talks to the same API.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_usb_pal.h.

Typedef Documentation

ra8_usb_pal_event_fn_t

typedef void(* ra8_usb_pal_event_fn_t) (void *ctx, ra8_usb_speed_t speed, uint16_t event_mask)

Async event callback shape.

Parameters

[in]	ctx	Caller-supplied context.
[in]	speed	Which controller fired the event.
[in]	event_mask	OR of k_ra8_usb_pal_event_* bits.

Note

Invoked from ra8_usb ISR context. Must return quickly and must not call back into ra8_usb_pal_init / deinit.

Definition at line 163 of file ra8_usb_pal.h.

Enumeration Type Documentation

ra8_usb_pal_ep_dir_t

enum ra8_usb_pal_ep_dir_t : uint8_t

Endpoint direction.

Enumerator
k_ra8_usb_pal_ep_dir_out	Host -> device.
k_ra8_usb_pal_ep_dir_in	Device -> host.

Definition at line 100 of file ra8_usb_pal.h.

ra8_usb_pal_ep_type_t

enum ra8_usb_pal_ep_type_t : uint8_t

USB endpoint transfer type.

Enumerator
k_ra8_usb_pal_ep_type_control	RA8 USB pal ep type control.
k_ra8_usb_pal_ep_type_iso	RA8 USB pal ep type iso.
k_ra8_usb_pal_ep_type_bulk	RA8 USB pal ep type bulk.
k_ra8_usb_pal_ep_type_intr	RA8 USB pal ep type intr.

Definition at line 109 of file ra8_usb_pal.h.

ra8_usb_pal_event_t

enum ra8_usb_pal_event_t : uint16_t

Event mask bits passed to ra8_usb_pal_event_fn_t.

Enumerator
k_ra8_usb_pal_event_none	RA8 USB pal event none.
k_ra8_usb_pal_event_reset	Bus reset.
k_ra8_usb_pal_event_suspend	Bus suspend (idle).
k_ra8_usb_pal_event_resume	Bus resume.
k_ra8_usb_pal_event_setup	SETUP packet on EP0.
k_ra8_usb_pal_event_ep_in	IN endpoint complete.
k_ra8_usb_pal_event_ep_out	OUT endpoint complete.
k_ra8_usb_pal_event_sof	Start-of-Frame.
k_ra8_usb_pal_event_attach	VBUS rose / cable in.
k_ra8_usb_pal_event_detach	VBUS dropped / cable out.
k_ra8_usb_pal_event_error	Controller error.

Definition at line 138 of file ra8_usb_pal.h.

ra8_usb_pal_limits_t

enum ra8_usb_pal_limits_t : uint16_t

USB sizing constants.

USB 2.0 endpoint count: the RA8D2 USBFS controller has 10 pipes (ENDPN 0..9), USBHS has 16. The PAL exposes the smaller value (10) as the project-wide guarantee; controller-specific extensions land.

Enumerator
k_ra8_usb_pal_ep_max	Maximum endpoint number.
k_ra8_usb_pal_ep0_max_packet	EP0 max packet on FS / HS-FS.
k_ra8_usb_pal_bulk_max_fs	Bulk max packet at full-speed.
k_ra8_usb_pal_bulk_max_hs	Bulk max packet at high-speed.
k_ra8_usb_pal_xfer_max	Single-shot xfer cap.
k_ra8_usb_pal_ep_addr_mask	Strip USB-IN dir bit (bit 7) from ep_addr.

Definition at line 87 of file ra8_usb_pal.h.

ra8_usb_pal_state_t

enum ra8_usb_pal_state_t : uint8_t

USB device state per chapter 9 of USB 2.0.

Enumerator
k_ra8_usb_pal_state_detached	D+ pull-up off.
k_ra8_usb_pal_state_attached	D+ pull-up on, no reset.
k_ra8_usb_pal_state_default	Reset received.
k_ra8_usb_pal_state_addressed	Address assigned.
k_ra8_usb_pal_state_configd	SET_CONFIGURATION done.
k_ra8_usb_pal_state_suspended	Bus idle > 3 ms.

Definition at line 120 of file ra8_usb_pal.h.

Function Documentation

ra8_usb_pal_attach()

ra8_err_t ra8_usb_pal_attach ( bool attached )

nodiscard

Raise / drop the D+ pull-up to advertise the device.

Parameters

[in]

attached

true to assert pull-up, false to drop.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Pull-up state updated.
k_ra8_err_invalid_state	PAL not initialized.

Precondition

PAL has been initialized.

Postcondition

On success, ra8_usb_pal_get_state returns attached or detached to match.

Note

Thread safety: not thread-safe.

Since

0.1.0

Raise / drop the D+ pull-up to advertise the device.

Wraps ra8_usb_device_attach and updates the cached PAL state so subsequent ra8_usb_pal_get_state calls reflect the request.

Parameters

[in]

attached

true to assert attach, false to detach.

Returns

ra8_err_t error code from the underlying driver.

Return values

k_ra8_ok	Attach state updated.
k_ra8_err_invalid_state	PAL not initialized.

Precondition

PAL has been initialized.

Bus is in a stable enumeration state (host connected if attaching).

Postcondition

On success, s_state.state reflects attached.

On error, no PAL state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 381 of file ra8_usb_pal.c.

References k_ra8_err_invalid_state, k_ra8_ok, k_ra8_usb_pal_state_attached, k_ra8_usb_pal_state_detached, ra8_usb_device_attach(), and s_state.

ra8_usb_pal_deinit()

ra8_err_t ra8_usb_pal_deinit ( void )

nodiscard

Tear down the USB PAL.

Drops the D+ pull-up, detaches the event handler, and calls ra8_usb_device_deinit to drop the controller MSTP reference.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	PAL released.
k_ra8_err_invalid_state	PAL was never initialized.

Precondition

IRQs masked or single-threaded shutdown context.

Postcondition

Subsequent send/recv calls return k_ra8_err_invalid_state.

Note

Thread safety: not thread-safe.

Since

0.1.0

Tear down the USB PAL.

Detaches the device, removes the ra8_usb event handler, deinits the underlying driver, clears stack callback state, marks the state as detached, and resets every endpoint slot.

Returns

ra8_err_t error code from ra8_usb_device_deinit.

Return values

k_ra8_ok	Released cleanly.
k_ra8_err_invalid_state	PAL was never initialized.

Precondition

IRQs masked or single-threaded shutdown context.

PAL was previously initialized (otherwise returns invalid_state).

Postcondition

s_state.initialized == false.

Subsequent EP calls return k_ra8_err_invalid_state.

Note

Not thread-safe.

See also

ra8_usb_pal_init

Since

0.1.0

Definition at line 344 of file ra8_usb_pal.c.

References internal_reset_eps(), k_ra8_err_invalid_state, k_ra8_usb_pal_state_detached, ra8_usb_attach_handler(), ra8_usb_device_attach(), ra8_usb_device_deinit(), and s_state.

ra8_usb_pal_ep_open()

ra8_err_t ra8_usb_pal_ep_open ( uint8_t ep_addr, ra8_usb_pal_ep_dir_t dir, ra8_usb_pal_ep_type_t type, uint16_t max_packet )

nodiscard

Open a non-control endpoint with a given type / direction / size.

Stores the EP configuration in the PAL's per-endpoint slot and resets its software queue to empty. Subsequent ep_send / ep_recv calls route through this slot.

Parameters

[in]	ep_addr	Endpoint address (1..k_ra8_usb_pal_ep_max).
[in]	dir	IN or OUT.
[in]	type	Bulk / interrupt / iso (control = EP0 only).
[in]	max_packet	Maximum packet size in bytes.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Endpoint configured.
k_ra8_err_invalid_arg	Bad ep_addr / dir / type / size.
k_ra8_err_invalid_state	PAL not initialized.

Precondition

PAL has been initialized.

Postcondition

On success, the endpoint is ready for transfers.

Note

Thread safety: not thread-safe.

Since

0.1.0

Open a non-control endpoint with a given type / direction / size.

Records direction, transfer type, and max packet size in the per-EP slot; resets the slot's queue cursors so subsequent ra8_usb_pal_ep_send / ra8_usb_pal_ep_recv start at slot 0.

Parameters

[in]	ep_addr	Endpoint address (1..k_ra8_usb_pal_ep_max).
[in]	dir	OUT or IN direction.
[in]	type	Control / bulk / iso / intr transfer type.
[in]	max_packet	Maximum packet size; 1..k_ra8_usb_pal_xfer_max.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Endpoint opened.
k_ra8_err_invalid_state	PAL not initialized.
k_ra8_err_invalid_arg	Address, direction, type, or max_packet out of range.

Precondition

PAL has been initialized.

Endpoint is not currently opened (re-opens are allowed and reset state).

Postcondition

On success, the slot is opened and the per-EP ring is empty.

On error, no slot state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 434 of file ra8_usb_pal.c.

References ra8_usb_pal_ep_slot_t::count, ra8_usb_pal_ep_slot_t::dir, ra8_usb_pal_ep_slot_t::head, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_usb_pal_ep_addr_mask, k_ra8_usb_pal_ep_dir_in, k_ra8_usb_pal_ep_dir_out, k_ra8_usb_pal_ep_max, k_ra8_usb_pal_ep_type_intr, k_ra8_usb_pal_ring_slots, k_ra8_usb_pal_xfer_max, ra8_usb_pal_packet_t::len, ra8_usb_pal_ep_slot_t::max_packet, ra8_usb_pal_ep_slot_t::opened, priv_usb_pal_ep_out_of_range(), ra8_usb_pal_ep_slot_t::ring, s_state, ra8_usb_pal_ep_slot_t::tail, and ra8_usb_pal_ep_slot_t::type.

ra8_usb_pal_ep_recv()

ra8_err_t ra8_usb_pal_ep_recv ( uint8_t ep_addr, uint8_t * out_buf, uint16_t * inout_len )

nodiscard

Receive data from an OUT endpoint (host -> device).

Parameters

[in]	ep_addr	Endpoint number 1..k_ra8_usb_pal_ep_max.
[out]	out_buf	Destination buffer.
[in,out]	inout_len	On entry: capacity. On exit: bytes received.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Bytes received.
k_ra8_err_no_data	No data ready (poll-friendly).
k_ra8_err_null_ptr	out_buf / inout_len NULL.
k_ra8_err_invalid_arg	ep_addr or capacity bad.
k_ra8_err_invalid_state	PAL not initialized or EP not opened.

Precondition

PAL has been initialized.

Endpoint previously opened via ra8_usb_pal_ep_open.

Postcondition

On success, *inout_len holds the byte count.

Note

Thread safety: not thread-safe.

Since

0.1.0

Receive data from an OUT endpoint (host -> device).

Copies up to *inout_len bytes from the head of the per-EP ring into out_buf and updates *inout_len with the byte count actually written. When the ring is empty the call returns k_ra8_err_no_data so the stack can poll without blocking.

Parameters

[in]	ep_addr	Endpoint address (1..k_ra8_usb_pal_ep_max).
[out]	out_buf	Destination buffer.
[in,out]	inout_len	On entry: capacity of out_buf. On exit: bytes written.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Packet copied.
k_ra8_err_no_data	Ring empty.
k_ra8_err_null_ptr	out_buf or inout_len NULL.
k_ra8_err_invalid_state	PAL not initialized or EP not opened.
k_ra8_err_invalid_arg	Address out of range or capacity zero.

Precondition

PAL has been initialized.

Endpoint was opened via ra8_usb_pal_ep_open.

Postcondition

On success, the per-EP ring depth is decremented by one.

On error, no slot state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 563 of file ra8_usb_pal.c.

References ra8_usb_pal_ep_slot_t::count, ra8_usb_pal_packet_t::data, ra8_usb_pal_ep_slot_t::head, internal_copy_bytes(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_no_data, k_ra8_ok, k_ra8_usb_pal_ep_addr_mask, k_ra8_usb_pal_ep_max, k_ra8_usb_pal_ring_slots, ra8_usb_pal_packet_t::len, ra8_usb_pal_ep_slot_t::opened, priv_usb_pal_ep_out_of_range(), RA8_CHECK_NULL_PTR, ra8_usb_pal_ep_slot_t::ring, s_state, and s_tag.

ra8_usb_pal_ep_send()

ra8_err_t ra8_usb_pal_ep_send ( uint8_t ep_addr, const uint8_t * data, uint16_t len )

nodiscard

Submit data on an IN endpoint (device -> host).

Parameters

[in]	ep_addr	Endpoint number 1..k_ra8_usb_pal_ep_max.
[in]	data	Buffer to send.
[in]	len	Number of bytes; 0..max_packet.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Transfer queued.
k_ra8_err_null_ptr	data was NULL with non-zero len.
k_ra8_err_invalid_arg	ep_addr or len out of range.
k_ra8_err_invalid_state	PAL not initialized or EP not opened.
k_ra8_err_no_mem	EP TX ring full; try again later.

Precondition

PAL has been initialized.

Endpoint previously opened via ra8_usb_pal_ep_open.

Postcondition

On success, the data has been queued for TX.

Note

Thread safety: not thread-safe.

Since

0.1.0

Submit data on an IN endpoint (device -> host).

Copies data[0..len-1] into the next free slot of the per-EP ring. Fires k_ra8_usb_pal_event_ep_in when an event handler is installed. len == 0 is allowed (zero-length packet); when len == 0 the data pointer may be NULL.

Parameters

[in]	ep_addr	Endpoint address (1..k_ra8_usb_pal_ep_max).
[in]	data	Packet bytes; non-NULL when len > 0.
[in]	len	Packet length in bytes (<= max_packet).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Packet queued.
k_ra8_err_invalid_state	PAL not initialized or EP not opened.
k_ra8_err_null_ptr	data NULL with len > 0.
k_ra8_err_invalid_arg	Address out of range or length above limit.
k_ra8_err_no_mem	Per-EP ring full; drain and retry.

Precondition

PAL has been initialized.

Endpoint was opened via ra8_usb_pal_ep_open.

Postcondition

On success, the per-EP ring depth is incremented by one.

On error, no slot state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 498 of file ra8_usb_pal.c.

References ra8_usb_pal_ep_slot_t::count, ra8_usb_pal_packet_t::data, internal_copy_bytes(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_usb_pal_ep_addr_mask, k_ra8_usb_pal_ep_max, k_ra8_usb_pal_event_ep_in, k_ra8_usb_pal_ring_slots, k_ra8_usb_pal_xfer_max, ra8_usb_pal_packet_t::len, ra8_usb_pal_ep_slot_t::max_packet, ra8_usb_pal_ep_slot_t::opened, priv_usb_pal_ep_out_of_range(), ra8_usb_pal_ep_slot_t::ring, s_state, and ra8_usb_pal_ep_slot_t::tail.

Referenced by internal_usbcdc_write().

ra8_usb_pal_get_state()

ra8_err_t ra8_usb_pal_get_state ( ra8_usb_pal_state_t * out_state )

nodiscard

Read the current PAL state machine.

Parameters

[out]

out_state

Receives the state.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Copied.
k_ra8_err_null_ptr	out_state was NULL.
k_ra8_err_invalid_state	PAL not initialized.

Precondition

out_state is non-NULL.

PAL has been initialized.

Postcondition

No PAL state is modified.

Note

Thread safety: not thread-safe; the state can be updated from ra8_usb ISR context concurrently.

Since

0.1.0

Definition at line 397 of file ra8_usb_pal.c.

References k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_state, and s_tag.

ra8_usb_pal_init()

ra8_err_t ra8_usb_pal_init ( ra8_usb_speed_t speed )

nodiscard

Initialise the USB PAL on a specific controller speed.

Calls ra8_usb_device_init(speed) to power on the chosen controller, attaches a status-translation handler, and resets the PAL state machine to detached. Does NOT raise the D+ pull-up; the caller must call ra8_usb_pal_attach(true) to advertise the device to the host.

Parameters

[in]

speed

Which controller (FS or HS) to bring up.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	PAL ready, state = detached.
k_ra8_err_invalid_arg	speed out of range.
k_ra8_err_hw_init_failed	Underlying ra8_usb_device_init.

Precondition

IRQs masked or single-threaded init context.

ra8_mstp_init and ra8_pwr_init have been called.

Postcondition

On success, the controller is clocked but D+ pull-up off.

ra8_usb_pal_get_state returns detached.

Note

Thread safety: not thread-safe.

See also

ra8_usb_pal_deinit

ra8_usb_pal_attach

Since

0.1.0

Initialise the USB PAL on a specific controller speed.

Validates the speed, powers up the ra8_usb device-mode driver, resets every endpoint slot, and installs the internal event handler so the stack callback can fire.

Parameters

[in]

speed

FS or HS speed selector.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	PAL ready, state = detached.
k_ra8_err_invalid_arg	speed not FS or HS.
k_ra8_err_hw_init_failed	ra8_usb_device_init failed.

Precondition

ra8_mstp_init and ra8_pwr_init have been called.

IRQs masked or single-threaded init context.

Postcondition

On success, s_state.initialized == true and every EP slot is in the unopened state.

On failure, s_state.initialized == false and the underlying ra8_usb driver has been torn down.

Note

Not thread-safe; must run from boot init context.

See also

ra8_usb_pal_deinit

Since

0.1.0

Definition at line 299 of file ra8_usb_pal.c.

References internal_reset_eps(), internal_usb_event(), k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_pal_state_detached, k_ra8_usb_speed_fs, k_ra8_usb_speed_hs, ra8_log_error_val, ra8_log_info, ra8_usb_attach_handler(), ra8_usb_device_init(), s_state, and s_tag.

ra8_usb_pal_set_event_handler()

ra8_err_t ra8_usb_pal_set_event_handler ( ra8_usb_pal_event_fn_t fn, void * ctx )

nodiscard

Attach a single event handler for bus / endpoint events.

Replaces any previously installed handler. The PAL relays ra8_usb ISR events into this callback after translating them into the PAL-level k_ra8_usb_pal_event_* bit set.

Parameters

[in]	fn	Callback. Pass NULL to detach.
[in]	ctx	Context passed to the callback.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Handler installed (or detached).
k_ra8_err_invalid_state	PAL not initialized.

Precondition

PAL has been initialized.

Postcondition

Subsequent ra8_usb events are routed through fn.

Note

Thread safety: not thread-safe; only call from single-threaded init or with IRQs masked.

Since

0.1.0

Attach a single event handler for bus / endpoint events.

Replaces any previously installed callback. Pass fn == nullptr to detach. The callback is invoked from ra8_usb ISR/task context via internal_usb_event and from the per-EP send/recv hot path.

Parameters

[in]	fn	Event callback, or NULL to detach.
[in]	ctx	Opaque context handed back to fn.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Handler installed/cleared.
k_ra8_err_invalid_state	PAL not initialized.

Precondition

PAL has been initialized.

fn is callable from ISR context if it is non-NULL.

Postcondition

s_state.event_fn == fn and s_state.event_ctx == ctx.

No other PAL state is mutated.

Note

Not thread-safe with respect to a concurrent event delivery.

Since

0.1.0

Definition at line 620 of file ra8_usb_pal.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.