Native USB device-side Vendor-defined class layer. More...

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

Include dependency graph for ra8_usb_pvnd.h:

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

Typedefs
typedef ra8_err_t(*	ra8_usb_pvnd_setup_fn_t) (void ctx, const ra8_usb_setup_t setup)
	Caller-supplied vendor class-setup handler signature.

Enumerations
enum	ra8_usb_pvnd_pipe_t : uint8_t { k_ra8_pvnd_pipe_bulk_in = 5U , k_ra8_pvnd_pipe_bulk_out = 1U }
	PIPE numbers used by the device-Vendor function for the local bulk endpoints. More...
enum	ra8_usb_pvnd_ep_t : uint8_t { k_ra8_pvnd_ep_bulk_in_addr = 1U , k_ra8_pvnd_ep_bulk_out_addr = 2U }
	USB endpoint addresses used by the device-Vendor function. More...
enum	ra8_usb_pvnd_packet_t : uint16_t { k_ra8_pvnd_bulk_max_packet_fs = 64U , k_ra8_pvnd_bulk_max_packet_hs = 512U }
	Packet sizing for the bulk endpoints. More...
enum	ra8_usb_pvnd_class_t : uint8_t { k_ra8_pvnd_class_vendor = 0xFFU }
	Class / subclass / protocol triplet that identifies the local Vendor function in the configuration descriptor. More...
enum	ra8_usb_pvnd_envelope_t : uint8_t { k_ra8_pvnd_bm_vendor_dev_in = 0xC0U , k_ra8_pvnd_bm_vendor_dev_out = 0x40U , k_ra8_pvnd_bm_vendor_iface_in = 0xC1U , k_ra8_pvnd_bm_vendor_iface_out = 0x41U , k_ra8_pvnd_bm_vendor_ep_in = 0xC2U , k_ra8_pvnd_bm_vendor_ep_out = 0x42U }
	bmRequestType envelopes that are vendor-recipient SETUPs. More...

Functions
ra8_err_t	ra8_usb_pvnd_init (ra8_usb_speed_t speed)
	Bring up the device-Vendor function on a chosen USB controller.
ra8_err_t	ra8_usb_pvnd_close (void)
	Tear down the device-Vendor function and release the controller.
ra8_err_t	ra8_usb_pvnd_set_descriptors (const uint8_t *desc, uint16_t desc_len)
	Install the caller-supplied descriptor blob.
ra8_err_t	ra8_usb_pvnd_send (const uint8_t *data, uint16_t len)
	Push a payload on the vendor bulk-IN endpoint.
ra8_err_t	ra8_usb_pvnd_recv (uint8_t buf, uint16_t max_len, uint16_t got_len)
	Drain a payload from the vendor bulk-OUT endpoint.
ra8_err_t	ra8_usb_pvnd_attach_setup_handler (ra8_usb_pvnd_setup_fn_t setup_fn, void *ctx)
	Register the application's vendor setup handler.
ra8_err_t	ra8_usb_pvnd_handle_setup (const ra8_usb_setup_t *setup)
	Process a vendor-specific SETUP packet on EP0.

Detailed Description

Native USB device-side Vendor-defined class layer.

Glues the device-mode ra8_usb controller driver to a vendor-defined USB function so the EK-RA8D2 enumerates with class code 0xFF, ready to carry application-specific protocols over raw bulk pipes (LibUSB, WinUSB, custom firmware loaders, board-debug bridges, etc.). The implementation is from-scratch; FSP r_usb_vendor_descriptor.c.template is reference material only – nothing is pulled in verbatim. Mirrors the surface that FSP's peripheral-Vendor descriptor template implies:

Caller-supplied descriptor blob (configuration + interface + bulk EP descriptors).
Bulk-IN pipe (PIPE5) for outbound application data.
Bulk-OUT pipe (PIPE1) for inbound application data.
No defined class requests; everything goes through the optional application setup callback as a vendor-recipient SETUP envelope (USB 2.0 sec 9.3 "USB Device Requests").

Reference: USB 2.0 sec 9.3 "USB Device Requests" (vendor request envelope encoding) and USB 2.0 Class Codes registry, class 0xFF = Vendor Specific.

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

Definition in file ra8_usb_pvnd.h.

Typedef Documentation

◆ ra8_usb_pvnd_setup_fn_t

typedef ra8_err_t(* ra8_usb_pvnd_setup_fn_t) (void *ctx, const ra8_usb_setup_t *setup)

Caller-supplied vendor class-setup handler signature.

The class layer pre-decodes the SETUP envelope (validates it really is a vendor-recipient request) and hands it to the application. Vendor requests have no spec-defined semantics; the application owns the entire request set.

Parameters

[in]	ctx	Caller-supplied context registered alongside the handler.
[in]	setup	The 8-byte SETUP envelope (vendor request).

Returns: ra8_err_t error code; k_ra8_ok lets the class layer ACK the status stage, anything else stalls EP0.

Note: Invoked from the dispatch site (typically ISR context) when a vendor SETUP lands.

Definition at line 133 of file ra8_usb_pvnd.h.

Enumeration Type Documentation

◆ ra8_usb_pvnd_class_t

enum ra8_usb_pvnd_class_t : uint8_t

Class / subclass / protocol triplet that identifies the local Vendor function in the configuration descriptor.

USB-IF Class Codes registry: 0xFF = vendor-specific. Subclass and protocol are wholly application-defined.

Enumerator
k_ra8_pvnd_class_vendor	Vendor-specific interface class.

Definition at line 93 of file ra8_usb_pvnd.h.

◆ ra8_usb_pvnd_envelope_t

enum ra8_usb_pvnd_envelope_t : uint8_t

bmRequestType envelopes that are vendor-recipient SETUPs.

Per USB 2.0 sec 9.3 "USB Device Requests": the type field is 0b10 (vendor) and the recipient field varies (0=device, 1=interface, 2=endpoint). The class layer accepts all four common combinations.

Enumerator
k_ra8_pvnd_bm_vendor_dev_in	Vendor \| Device \| In.
k_ra8_pvnd_bm_vendor_dev_out	Vendor \| Device \| Out.
k_ra8_pvnd_bm_vendor_iface_in	Vendor \| Interface \| In.
k_ra8_pvnd_bm_vendor_iface_out	Vendor \| Interface \| Out.
k_ra8_pvnd_bm_vendor_ep_in	Vendor \| Endpoint \| In.
k_ra8_pvnd_bm_vendor_ep_out	Vendor \| Endpoint \| Out.

Definition at line 105 of file ra8_usb_pvnd.h.

◆ ra8_usb_pvnd_ep_t

enum ra8_usb_pvnd_ep_t : uint8_t

USB endpoint addresses used by the device-Vendor function.

Enumerator
k_ra8_pvnd_ep_bulk_in_addr	EP1 IN address.
k_ra8_pvnd_ep_bulk_out_addr	EP2 OUT address.

Definition at line 68 of file ra8_usb_pvnd.h.

◆ ra8_usb_pvnd_packet_t

enum ra8_usb_pvnd_packet_t : uint16_t

Packet sizing for the bulk endpoints.

Per USB 2.0 sec 5.8.3 "Bulk Transfer Packet Size Constraints", FS bulk = 8/16/32/64 bytes, HS bulk = 512 bytes.

Enumerator
k_ra8_pvnd_bulk_max_packet_fs	Bulk size at FS.
k_ra8_pvnd_bulk_max_packet_hs	Bulk size at HS.

Definition at line 80 of file ra8_usb_pvnd.h.

◆ ra8_usb_pvnd_pipe_t

enum ra8_usb_pvnd_pipe_t : uint8_t

PIPE numbers used by the device-Vendor function for the local bulk endpoints.

FSP / RA8D2 PIPE assignment rules constrain bulk pipes to PIPE1..PIPE5. PIPE5 carries bulk IN (device -> host), PIPE1 carries bulk OUT (host -> device). Pipe5 is chosen so a single controller can host MSC (PIPE3/4), CDC (PIPE1/2/6), and Vendor on PIPE5 / PIPE1 without colliding.

Enumerator
k_ra8_pvnd_pipe_bulk_in	PIPE5 -> EP1 IN (vendor IN).
k_ra8_pvnd_pipe_bulk_out	PIPE1 -> EP2 OUT (vendor OUT).

Definition at line 59 of file ra8_usb_pvnd.h.

Function Documentation

◆ ra8_usb_pvnd_attach_setup_handler()

ra8_err_t ra8_usb_pvnd_attach_setup_handler	(	ra8_usb_pvnd_setup_fn_t	setup_fn,
		void *	ctx )

nodiscard

Register the application's vendor setup handler.

Pass NULL for setup_fn to detach. The class layer pre-decodes the SETUP envelope and forwards it if its bmRequestType indicates a vendor-recipient request.

Parameters

[in]	setup_fn	Application's handler. NULL detaches.
[in]	ctx	Context pointer threaded back into setup_fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handler installed.
k_ra8_err_invalid_state	Driver not initialized.

Precondition: ra8_usb_pvnd_init succeeded.

Postcondition: On the next vendor SETUP, setup_fn(ctx, &setup) fires.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 263 of file ra8_usb_pvnd.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

Referenced by demo_usb_bringup().

◆ ra8_usb_pvnd_close()

ra8_err_t ra8_usb_pvnd_close ( void )

nodiscard

Tear down the device-Vendor function and release the controller.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Released.
k_ra8_err_invalid_state	Driver was never initialized.

Precondition: Single-threaded shutdown context.

Postcondition: ra8_usb_device_deinit ran; D+ pull-up dropped; subsequent device-Vendor API calls return k_ra8_err_invalid_state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 185 of file ra8_usb_pvnd.c.

References k_ra8_err_invalid_state, ra8_usb_device_attach(), ra8_usb_device_deinit(), and s_state.

◆ ra8_usb_pvnd_handle_setup()

ra8_err_t ra8_usb_pvnd_handle_setup ( const ra8_usb_setup_t * setup )

nodiscard

Process a vendor-specific SETUP packet on EP0.

The class layer accepts every bmRequestType whose type field is 0b10 (vendor) and forwards the SETUP to the registered application handler. If no handler is registered, the SETUP is stalled. Standard / class SETUPs are rejected with k_ra8_err_not_supported so the caller can fall back to its own standard / class handler.

Parameters

[in] setup The SETUP packet returned by ra8_usb_read_setup_if_valid.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SETUP handled (status stage queued internally).
k_ra8_err_invalid_state	Driver not initialized.
k_ra8_err_null_ptr	setup was NULL.
k_ra8_err_not_supported	bmRequestType is not a vendor envelope.

Precondition: ra8_usb_pvnd_init succeeded.

Postcondition: Internal state may have been updated by the application callback.

Note: Call from the CTRT ISR path of ra8_usb.

Since: 0.1.0

Definition at line 278 of file ra8_usb_pvnd.c.

References ra8_usb_setup_t::bm_request_type, internal_is_vendor_envelope(), k_ra8_err_invalid_state, k_ra8_err_not_supported, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_usb_control_response(), s_state, and s_tag.

Referenced by demo_dispatch_setup().

◆ ra8_usb_pvnd_init()

ra8_err_t ra8_usb_pvnd_init ( ra8_usb_speed_t speed )

nodiscard

Bring up the device-Vendor function on a chosen USB controller.

Initialises the underlying ra8_usb driver in DEVICE mode for speed, configures PIPE5 (bulk IN) and PIPE1 (bulk OUT), and leaves the D+ pull-up dropped. The caller raises it via ra8_usb_device_attach once descriptors are set.

Parameters

[in] speed Which USB controller (FS or HS).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Device-Vendor ready.
k_ra8_err_invalid_arg	speed out of range.
k_ra8_err_hw_init_failed	Underlying ra8_usb_device_init failed.

Precondition: Single-threaded init context.; ra8_mstp_init and ra8_pwr_init already ran.

Postcondition: Internal state machine armed; descriptor pointer cleared.; Pipe5 / pipe1 configured at the speed's default packet size.

Note: Not thread-safe.

See also: ra8_usb_pvnd_set_descriptors; ra8_usb_pvnd_close

Since: 0.1.0

Definition at line 167 of file ra8_usb_pvnd.c.

References internal_configure_pipes(), internal_reset_shadow(), k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_speed_fs, k_ra8_usb_speed_hs, ra8_log_error_val, ra8_log_info_val, ra8_usb_device_init(), s_state, and s_tag.

Referenced by demo_usb_bringup().

◆ ra8_usb_pvnd_recv()

ra8_err_t ra8_usb_pvnd_recv	(	uint8_t *	buf,
		uint16_t	max_len,
		uint16_t *	got_len )

nodiscard

Drain a payload from the vendor bulk-OUT endpoint.

Parameters

[out]	buf	Receive buffer.
[in]	max_len	Capacity of buf, > 0.
[out]	got_len	Receives the number of bytes actually placed.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes drained.
k_ra8_err_no_data	Pipe was empty.
k_ra8_err_null_ptr	buf or got_len was NULL.
k_ra8_err_invalid_state	Driver not initialized.
k_ra8_err_invalid_arg	max_len == 0.

Precondition: ra8_usb_pvnd_init succeeded.

Postcondition: On success *got_len reflects the actual byte count.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 237 of file ra8_usb_pvnd.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_pvnd_pipe_bulk_out, RA8_CHECK_NULL_PTR, ra8_usb_queue_out(), s_state, and s_tag.

Referenced by demo_drain_vendor().

◆ ra8_usb_pvnd_send()

ra8_err_t ra8_usb_pvnd_send	(	const uint8_t *	data,
		uint16_t	len )

nodiscard

Push a payload on the vendor bulk-IN endpoint.

Parameters

[in]	data	Payload buffer.
[in]	len	Payload byte length.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes queued onto bulk-IN.
k_ra8_err_invalid_state	Driver not initialized.
k_ra8_err_null_ptr	data was NULL with len > 0.
k_ra8_err_invalid_arg	len == 0 or larger than the pipe max.

Precondition: ra8_usb_pvnd_init succeeded.

Postcondition: len bytes sit on PIPE5.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 223 of file ra8_usb_pvnd.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_pvnd_pipe_bulk_in, ra8_usb_queue_in(), and s_state.

Referenced by demo_drain_vendor().

◆ ra8_usb_pvnd_set_descriptors()

ra8_err_t ra8_usb_pvnd_set_descriptors	(	const uint8_t *	desc,
		uint16_t	desc_len )

nodiscard

Install the caller-supplied descriptor blob.

The blob is concatenation of configuration / interface / bulk EP descriptors. The class layer keeps just a pointer + length pair; the caller owns the storage.

Parameters

[in]	desc	Pointer to the caller-owned descriptor blob.
[in]	desc_len	Byte length of desc.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Pointer + length stored.
k_ra8_err_invalid_state	Driver not initialized.
k_ra8_err_null_ptr	desc was NULL.
k_ra8_err_invalid_arg	desc_len == 0.

Precondition: ra8_usb_pvnd_init succeeded.

Postcondition: GET_DESCRIPTOR(Configuration) requests can use this blob.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 204 of file ra8_usb_pvnd.c.

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

Referenced by demo_usb_bringup().

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_usb_pvnd_setup_fn_t

Enumeration Type Documentation

◆ ra8_usb_pvnd_class_t

◆ ra8_usb_pvnd_envelope_t

◆ ra8_usb_pvnd_ep_t

◆ ra8_usb_pvnd_packet_t

◆ ra8_usb_pvnd_pipe_t

Function Documentation

◆ ra8_usb_pvnd_attach_setup_handler()

◆ ra8_usb_pvnd_close()

◆ ra8_usb_pvnd_handle_setup()

◆ ra8_usb_pvnd_init()

◆ ra8_usb_pvnd_recv()

◆ ra8_usb_pvnd_send()

◆ ra8_usb_pvnd_set_descriptors()