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

#include "ra8_usb_pvnd.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_usb.h"

Include dependency graph for ra8_usb_pvnd.c:

Data Structures
struct	ra8_usb_pvnd_state_t
	Singleton shadow state for the device-Vendor function. More...

Functions
static uint16_t	internal_bulk_max_packet (ra8_usb_speed_t speed)
	Pick the bulk-max-packet ceiling matching the negotiated speed.
static void	internal_configure_pipes (ra8_usb_speed_t speed)
	Configure the two bulk pipes.
static void	internal_reset_shadow (ra8_usb_speed_t speed)
	Reset shadow state to spec defaults.
static bool	internal_is_vendor_envelope (uint8_t bm)
	Recognise a vendor-recipient SETUP envelope.
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.

Variables
static const char *	s_tag = "USBPVND"
static ra8_usb_pvnd_state_t	s_state = {}

Detailed Description

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

Tag: [Ring 3 / HAL] {World: NS}

Glues the device-mode ra8_usb driver to a vendor-defined function (class 0xFF) so the EK-RA8D2 can carry application-specific protocols over raw bulk pipes. This file is the native peripheral- Vendor class layer; FSP's r_usb_vendor_descriptor.c.template is reference material only.

Reference: USB 2.0 sec 9.3 "USB Device Requests" (vendor request envelope encoding).

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

Definition in file ra8_usb_pvnd.c.

Function Documentation

◆ internal_bulk_max_packet()

uint16_t internal_bulk_max_packet ( ra8_usb_speed_t speed )

static

Pick the bulk-max-packet ceiling matching the negotiated speed.

See implementation.

Parameters

[in] speed See implementation.

Returns: The bulk-endpoint maximum packet size in bytes for speed.

Return values

k_ra8_pvnd_bulk_max_packet_hs	`speed` is k_ra8_usb_speed_hs.
k_ra8_pvnd_bulk_max_packet_fs	Any other speed.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 76 of file ra8_usb_pvnd.c.

References k_ra8_pvnd_bulk_max_packet_fs, k_ra8_pvnd_bulk_max_packet_hs, and k_ra8_usb_speed_hs.

Referenced by internal_configure_pipes(), and internal_reset_shadow().

◆ internal_configure_pipes()

void internal_configure_pipes ( ra8_usb_speed_t speed )

static

Configure the two bulk pipes.

See implementation.

Parameters

[in] speed See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 95 of file ra8_usb_pvnd.c.

References internal_bulk_max_packet(), k_ra8_pvnd_ep_bulk_in_addr, k_ra8_pvnd_ep_bulk_out_addr, k_ra8_pvnd_pipe_bulk_in, k_ra8_pvnd_pipe_bulk_out, k_ra8_usb_ep_dir_in, k_ra8_usb_ep_dir_out, k_ra8_usb_ep_type_bulk, and ra8_usb_configure_endpoint().

◆ internal_is_vendor_envelope()

bool internal_is_vendor_envelope ( uint8_t bm )

static

Recognise a vendor-recipient SETUP envelope.

Per USB 2.0 sec 9.3 "USB Device Requests", the type field is bits 6:5 of bmRequestType. 0b10 = vendor.

Parameters

[in] bm See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 155 of file ra8_usb_pvnd.c.

References k_ra8_pvnd_bm_vendor_dev_in, k_ra8_pvnd_bm_vendor_dev_out, k_ra8_pvnd_bm_vendor_ep_in, k_ra8_pvnd_bm_vendor_ep_out, k_ra8_pvnd_bm_vendor_iface_in, and k_ra8_pvnd_bm_vendor_iface_out.

Referenced by ra8_usb_pvnd_handle_setup().

◆ internal_reset_shadow()

void internal_reset_shadow ( ra8_usb_speed_t speed )

static

Reset shadow state to spec defaults.

See implementation.

Parameters

[in] speed See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 128 of file ra8_usb_pvnd.c.

References internal_bulk_max_packet(), and s_state.

Referenced by ra8_usb_pvnd_init().

◆ 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().

Variable Documentation

◆ s_state

ra8_usb_pvnd_state_t s_state = {}

static

Definition at line 53 of file ra8_usb_pvnd.c.

◆ s_tag

const char* s_tag = "USBPVND"

static

Definition at line 32 of file ra8_usb_pvnd.c.

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ internal_bulk_max_packet()

◆ internal_configure_pipes()

◆ internal_is_vendor_envelope()

◆ internal_reset_shadow()

◆ 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()

Variable Documentation

◆ s_state

◆ s_tag