ra8_usb_host.h File Reference

Native USB controller driver public API – host-mode bring-up. More...

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

Include dependency graph for ra8_usb_host.h:

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

Go to the source code of this file.

Functions
ra8_err_t	ra8_usb_host_init (ra8_usb_speed_t speed)
	Bring up a USB controller in HOST mode.
ra8_err_t	ra8_usb_host_deinit (ra8_usb_speed_t speed)
	Tear down a host-mode controller and drop its MSTP reference.
ra8_err_t	ra8_usb_host_bus_reset (ra8_usb_speed_t speed, bool assert_reset)
	Drive (or release) the bus reset line.
ra8_err_t	ra8_usb_host_set_uact (ra8_usb_speed_t speed, bool enable)
	Enable / disable SOF (Start-of-Frame) generation on the bus.
ra8_err_t	ra8_usb_host_setup_request (ra8_usb_speed_t speed, const ra8_usb_setup_t *setup)
	Issue a SETUP packet through the DCP (host -> peripheral).
ra8_err_t	ra8_usb_host_control_xfer (ra8_usb_speed_t speed, const ra8_usb_setup_t *setup, uint8_t *data, uint16_t data_len, uint16_t *out_received)
	Run a complete host control transfer (SETUP, optional DATA, STATUS).
uint8_t	ra8_usb_host_ctrl_stage (void)
	Last stage reached by ra8_usb_host_control_xfer (bring-up diag).
uint16_t	ra8_usb_host_line_state (ra8_usb_speed_t speed)
	Read the host port's D+/D- line state (SYSSTS0.LNST).
ra8_err_t	ra8_usb_host_set_target (ra8_usb_speed_t speed, uint8_t dev_addr)
	Retarget the host's default control pipe at a device address.
ra8_err_t	ra8_usb_host_pipe_setup (ra8_usb_speed_t speed, uint8_t pipe_num, uint8_t dev_addr, uint8_t ep_num, bool device_to_host, uint16_t max_packet)
	Configure a controller pipe against an attached device's bulk endpoint.
ra8_err_t	ra8_usb_host_bulk_out (ra8_usb_speed_t speed, uint8_t pipe_num, const uint8_t *data, uint16_t len)
	Transmit one bulk packet to the device and wait for the ACK.
ra8_err_t	ra8_usb_host_bulk_in (ra8_usb_speed_t speed, uint8_t pipe_num, uint8_t *buf, uint16_t max_len, uint16_t *out_received)
	Receive a bulk transfer from the device into buf.

Detailed Description

Native USB controller driver public API – host-mode bring-up.

Host-mode half of the hand-written, FSP-equivalent driver for the two USB controllers on the Renesas RA8D2 (USBFS @ 0x40250000, USBHS @ 0x40351000). Mirrors the bring-up flow of FSP's r_usb_hreg_access.c (host) but compiled as part of this tree, with no Renesas FSP, CherryUSB, or TinyUSB binaries pulled in. This sub-header carries the host-mode lifecycle, bus-control, target/pipe setup, control-transfer, and bulk-transfer surface; the shared public types and the device-mode surface live in ra8_usb_device.h. Both are aggregated by the thin umbrella ra8_usb.h.

Copyright

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

Since

0.1.0

Definition in file ra8_usb_host.h.

Function Documentation

ra8_usb_host_bulk_in()

ra8_err_t ra8_usb_host_bulk_in ( ra8_usb_speed_t speed, uint8_t pipe_num, uint8_t * buf, uint16_t max_len, uint16_t * out_received )

nodiscard

Receive a bulk transfer from the device into buf.

Arms the IN pipe (PID=BUF, so the SIE issues IN tokens) and consumes BRDY-gated packets from the CFIFO until the device ends the transfer with a short packet or max_len bytes have arrived, then parks the pipe NAK. Used for the MSC data stage and the 13-byte CSW.

Parameters

[in]	speed	Which controller (FS or HS).
[in]	pipe_num	Pipe configured by ra8_usb_host_pipe_setup (IN).
[out]	buf	Destination buffer.
[in]	max_len	Capacity of buf in bytes.
[out]	out_received	Receives the byte count gathered.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Transfer ended (short packet or count).
k_ra8_err_invalid_arg	speed / pipe_num out of range.
k_ra8_err_null_ptr	buf or out_received was NULL.
k_ra8_err_invalid_state	The pipe has no max-packet programmed.
k_ra8_err_hw_error	The device STALLed the endpoint.
k_ra8_err_hw_timeout	No packet before the spin bound.

Precondition

The pipe was configured by ra8_usb_host_pipe_setup.

The device is configured and expecting to send (e.g. post-CBW).

Postcondition

The pipe PID is NAK; *out_received holds the byte count.

On error the partial count gathered so far is still reported.

Note

Blocking; bounded by an internal spin limit per packet.

Since

0.1.0

Receive a bulk transfer from the device into buf.

See the public header for the documented contract; arms the IN pipe (PID=BUF so the SIE issues IN tokens) and consumes packets via internal_host_bulk_rx_packet until a short packet ends the transfer or max_len bytes have been gathered, then parks the pipe NAK.

Parameters

[in]	speed	See header.
[in]	pipe_num	See header.
[out]	buf	See header.
[in]	max_len	See header.
[out]	out_received	See header.

Returns

Result code.

Return values

k_ra8_ok

Transfer ended by short packet or byte count.

Precondition

Module state is consistent.

The pipe was configured by ra8_usb_host_pipe_setup.

Postcondition

The pipe PID is NAK; out_received holds the byte count.

On error the partial count received so far is still reported.

Note

Not thread-safe.

Since

0.1.0

Definition at line 424 of file ra8_usb_host_bulk.c.

References r_usb_regs_t::BRDYENB, internal_host_bulk_rx_loop(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_pid_buf, k_ra8_pid_nak, k_ra8_usb_max_pipe_num, k_ra8_usb_pipemaxp_mxps, r_usb_regs_t::PIPEMAXP, r_usb_regs_t::PIPESEL, priv_pick(), priv_pipe_pid(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by cdc_echo_round(), hid_read_round(), hid_read_round(), internal_recv_bytes(), and ns_host_echo_round().

ra8_usb_host_bulk_out()

ra8_err_t ra8_usb_host_bulk_out ( ra8_usb_speed_t speed, uint8_t pipe_num, const uint8_t * data, uint16_t len )

nodiscard

Transmit one bulk packet to the device and wait for the ACK.

Single-packet host bulk OUT: stages data into the pipe buffer (FRDY-gated FIFO write + BVAL + PID=BUF via ra8_usb_queue_in), then waits for the buffer-empty (BEMP) event that marks the packet on the wire and acknowledged, and parks the pipe NAK. Sized for protocol headers such as the 31-byte MSC CBW; len must not exceed the pipe's max packet size.

Parameters

[in]	speed	Which controller (FS or HS).
[in]	pipe_num	Pipe configured by ra8_usb_host_pipe_setup (OUT).
[in]	data	Packet payload.
[in]	len	Payload length in bytes (<= pipe MPS).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Packet transmitted and ACKed.
k_ra8_err_invalid_arg	speed / pipe_num / len out of range.
k_ra8_err_null_ptr	data was NULL.
k_ra8_err_hw_error	The device STALLed the endpoint.
k_ra8_err_hw_timeout	No ACK before the spin bound.

Precondition

The pipe was configured by ra8_usb_host_pipe_setup.

The device is configured (SET_CONFIGURATION accepted).

Postcondition

The pipe PID is NAK and its BEMP status is cleared.

On k_ra8_ok the device has ACKed the packet.

Note

Blocking; bounded by an internal spin limit.

Since

0.1.0

Transmit one bulk packet to the device and wait for the ACK.

See the public header for the documented contract; pushes one packet (up to the pipe MPS) through the pipe buffer via ra8_usb_queue_in (wait FRDY, FIFO write, BVAL, PID=BUF) and waits for the buffer-empty (BEMP) event that marks the packet transmitted and ACKed, then parks the pipe NAK.

Parameters

[in]	speed	See header.
[in]	pipe_num	See header.
[in]	data	See header.
[in]	len	See header.

Returns

Result code.

Return values

k_ra8_ok

Packet transmitted and acknowledged.

Precondition

Module state is consistent.

The pipe was configured by ra8_usb_host_pipe_setup.

Postcondition

The pipe PID is NAK and its BEMP status is cleared.

On k_ra8_ok the device has ACKed the packet.

Note

Not thread-safe.

Since

0.1.0

Definition at line 253 of file ra8_usb_host_bulk.c.

References r_usb_regs_t::BEMPENB, r_usb_regs_t::BEMPSTS, internal_host_wait_pipe(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_pid_nak, k_ra8_usb_max_pipe_num, priv_pick(), priv_pipe_pid(), RA8_CHECK_NULL_PTR, ra8_usb_queue_in(), and s_tag.

Referenced by cdc_echo_round(), internal_run_data_out(), internal_send_cbw(), and ns_host_echo_round().

ra8_usb_host_bus_reset()

ra8_err_t ra8_usb_host_bus_reset ( ra8_usb_speed_t speed, bool assert_reset )

nodiscard

Drive (or release) the bus reset line.

Sets / clears DVSTCTR0.USBRST. While reset is asserted, UACT is forced low (no SOF). The caller is expected to hold reset for at least the USB-spec-required 10 ms before deasserting and then re-enabling SOF generation via ra8_usb_host_set_uact(true).

Mirrors FSP's usb_hstd_bus_reset SET phase (r_usb_hreg_abs.c).

Parameters

[in]	speed	Which controller.
[in]	assert_reset	true to drive USBRST, false to release.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Reset line updated.
k_ra8_err_invalid_arg	speed out of range.

Precondition

ra8_usb_host_init ran for this speed.

Postcondition

DVSTCTR0.USBRST matches assert_reset.

Note

Not thread-safe.

Since

0.1.0

Drive (or release) the bus reset line.

See the public header for the documented contract; this definition implements it.

Parameters

[in]	speed	See implementation.
[in]	assert_reset	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 455 of file ra8_usb_irq.c.

References r_usb_regs_t::DVSTCTR0, k_ra8_dvstctr_bit_uact, k_ra8_dvstctr_bit_usbrst, k_ra8_err_invalid_arg, k_ra8_ok, priv_pick(), and priv_rmw16().

Referenced by cdc_enum_hunt(), dfu_enum_hunt(), hid_enum_hunt(), hid_enum_hunt(), internal_do_bus_reset(), internal_do_bus_reset(), internal_do_bus_reset(), internal_do_bus_reset(), internal_do_bus_reset(), internal_do_idle(), internal_do_idle(), internal_do_idle(), internal_do_idle(), internal_do_idle(), internal_enum_hunt(), internal_enum_hunt(), internal_port_reset(), and ns_host_enum_hunt().

ra8_usb_host_control_xfer()

ra8_err_t ra8_usb_host_control_xfer ( ra8_usb_speed_t speed, const ra8_usb_setup_t * setup, uint8_t * data, uint16_t data_len, uint16_t * out_received )

nodiscard

Run a complete host control transfer (SETUP, optional DATA, STATUS).

Polled, synchronous control transfer over the DCP (pipe 0). Drives the SETUP stage (SUREQ + wait for self-clear), an optional DATA-IN stage for device-to-host requests (BRDY-gated CFIFO reads), and the zero-length STATUS stage (CCPL). Completion is detected via SUREQ-clear / BRDY / BEMP – the host-mode signals – not CTRT, which only fires in device mode. This is the host counterpart of the device-mode control path and the primitive the host class drivers (MSC/HID/CDC) build enumeration on.

Parameters

[in]	speed	Which controller (FS or HS).
[in]	setup	The 8-byte SETUP packet.
[out]	data	Buffer for the DATA-IN stage (may be NULL for no-data / control-write requests).
[in]	data_len	Capacity of data in bytes.
[out]	out_received	Optional; receives DATA-IN bytes read (0 if none).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Transfer completed through the status stage.
k_ra8_err_invalid_arg	speed out of range.
k_ra8_err_null_ptr	setup was NULL.
k_ra8_err_busy	A control transfer was already pending.
k_ra8_err_hw_timeout	A stage did not complete within the bound.

Precondition

ra8_usb_host_init ran; the bus is reset and DVSTCTR0.UACT = 1.

setup is non-NULL; data holds at least data_len bytes if used.

Postcondition

On k_ra8_ok the device has seen the request and any IN data is in data with the count in out_received.

The DCP PID is left NAK.

Note

Blocking; each stage is bounded by an internal spin limit.

Since

0.1.0

Definition at line 763 of file ra8_usb_host_ctrl.c.

References internal_host_ctrl_setup(), internal_host_ctrl_status(), internal_host_data_phase(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_cs_begin, k_ra8_usb_cs_done, k_ra8_usb_cs_setup, k_ra8_usb_cs_status, priv_pick(), RA8_CHECK_NULL_PTR, s_host_ctrl_stage, and s_tag.

Referenced by cdc_ctrl_get_dev_desc(), cdc_enum_set_address(), cdc_enum_set_config(), dfu_ctrl_get_dev_desc(), dfu_dnload_block(), dfu_download_all(), dfu_enum_set_address(), dfu_enum_set_config(), dfu_getstatus(), dfu_upload_verify(), hid_ctrl_get_dev_desc(), hid_ctrl_get_dev_desc(), hid_enum_set_address(), hid_enum_set_address(), hid_enum_set_config(), hid_enum_set_config(), internal_dnload_block(), internal_download_all(), internal_download_manifest(), internal_enum_assign_addr(), internal_enum_configure(), internal_enum_read_config(), internal_enum_read_dev_desc(), internal_get_dev_desc(), internal_getstatus(), internal_set_address(), internal_set_config(), internal_upload_verify(), ns_host_get_dev_desc(), ns_host_set_address(), and ns_host_set_config().

ra8_usb_host_ctrl_stage()

uint8_t ra8_usb_host_ctrl_stage

(

void

)

Last stage reached by ra8_usb_host_control_xfer (bring-up diag).

0=before SETUP, 1=SETUP done, 2=DATA-IN entered, 3=first packet received, 4=DATA done, 5=STATUS entered, 6=STATUS done. Lets a caller pinpoint where a timed-out control transfer stalled.

Returns

The stage code from the most recent control transfer.

Return values

0	No control transfer has run since reset.
6	The most recent control transfer closed cleanly.

Precondition

ra8_usb_host_init ran for the controller of interest.

At least one ra8_usb_host_control_xfer may have been attempted.

Postcondition

No state is modified.

The returned value reflects the last transfer only.

Note

Diagnostic only; not part of the transfer contract.

Since

0.1.0

Definition at line 69 of file ra8_usb_host_ctrl.c.

References s_host_ctrl_stage.

ra8_usb_host_deinit()

ra8_err_t ra8_usb_host_deinit ( ra8_usb_speed_t speed )

nodiscard

Tear down a host-mode controller and drop its MSTP reference.

Parameters

[in]

speed

Which controller.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Controller released.
k_ra8_err_invalid_arg	speed out of range.

Precondition

Single-threaded shutdown context.

Postcondition

SYSCFG = 0, DVSTCTR0 = 0, MSTP gated.

Note

Not thread-safe.

Since

0.1.0

Tear down a host-mode controller and drop its MSTP reference.

See the public header for the documented contract; this definition implements it.

Parameters

[in]

speed

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 424 of file ra8_usb_irq.c.

References r_usb_regs_t::BEMPENB, r_usb_regs_t::BRDYENB, r_usb_regs_t::DVSTCTR0, r_usb_regs_t::INTENB0, r_usb_regs_t::INTENB1, k_ra8_err_invalid_arg, r_usb_regs_t::NRDYENB, priv_mstp(), priv_pick(), ra8_mstp_disable(), and r_usb_regs_t::SYSCFG.

Referenced by cdc_host_pass(), dfu_host_enumerate(), dfu_host_pass(), hid_host_pass(), hid_host_pass(), ns_host_worker(), ra8_dfu_host_program(), ra8_dfu_host_run(), ra8_usb_haud_close(), ra8_usb_hcdc_close(), ra8_usb_hcdc_ecm_close(), ra8_usb_hhid_close(), ra8_usb_hhub_close(), ra8_usb_hmsc_close(), and ux_hcd_ra8_usb_uninitialize().

ra8_usb_host_init()

ra8_err_t ra8_usb_host_init ( ra8_usb_speed_t speed )

nodiscard

Bring up a USB controller in HOST mode.

Mirrors FSP's hw_usb_hmodule_init (r_usb_basic/src/hw/r_usb_hreg_access.c). Bring-up sequence:

1. Drop the controller's MSTP gate.
2. Drive SYSCFG.SCKE and wait for the clock to be stable.
3. Set SYSCFG.DCFM = 1 (host) and SYSCFG.DRPD = 1 (D+/D- pull-down so the bus floats low when no device is attached).
4. Clear SYSCFG.DPRPU (device pull-up has no meaning in host mode).
5. Set SYSCFG.HSE for the HS instance only.
6. Set SYSCFG.USBE.
7. Configure the DCP (default control pipe) for host control transfers with a 64-byte max packet.

Bus is left idle (UACT = 0). Use ra8_usb_host_set_uact(true) to start SOF generation once a device has been detected on SYSSTS0.LNST.

Parameters

[in]

speed

Which controller (FS or HS).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Controller in host mode, bus floating.
k_ra8_err_invalid_arg	speed out of range.
k_ra8_err_hw_init_failed	MSTP enable failed.

Precondition

Single-threaded init context.

ra8_mstp_init and ra8_pwr_init already ran.

Postcondition

SYSCFG.DCFM = 1, SYSCFG.DRPD = 1, SYSCFG.USBE = 1.

DVSTCTR0.UACT = 0 (bus idle, no SOF).

Note

Not thread-safe.

See also

ra8_usb_host_set_uact

ra8_usb_host_bus_reset

Since

0.1.0

Bring up a USB controller in HOST mode.

See the public header for the documented contract; this definition implements it.

Parameters

[in]

speed

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 375 of file ra8_usb_irq.c.

References r_usb_regs_t::DVSTCTR0, internal_host_hs_bringup(), internal_host_init_defaults(), internal_host_syscfg_word(), k_ra8_dvstctr_bit_vbusen, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_speed_hs, priv_mstp(), priv_pick(), priv_rmw16(), ra8_log_info_val, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_tag, and r_usb_regs_t::SYSCFG.

Referenced by cdc_host_pass(), dfu_host_pass(), hid_host_pass(), hid_host_pass(), ns_host_worker(), ra8_board_usbhs_host_init(), ra8_dfu_host_program(), ra8_dfu_host_run(), ra8_usb_haud_init(), ra8_usb_hcdc_ecm_init(), ra8_usb_hcdc_init(), ra8_usb_hhid_init(), ra8_usb_hhub_init(), ra8_usb_hmsc_init(), and ux_hcd_ra8_usb_initialize().

ra8_usb_host_line_state()

uint16_t ra8_usb_host_line_state

(

ra8_usb_speed_t

speed

)

Read the host port's D+/D- line state (SYSSTS0.LNST).

0 = SE0 (no device pull-up / port idle), 1 = J-state (a full-speed-signalling device is attached), 2 = K-state. Used by host class drivers to wait for a device to attach before driving the bus reset.

Parameters

[in]

speed

Which controller (FS or HS).

Returns

The two-bit line state.

Return values

0	Nothing attached (or invalid speed / unpowered module).
1	A device's D+ pull-up is visible.

Precondition

ra8_usb_host_init ran for a meaningful read.

The controller is clocked.

Postcondition

No state is modified.

The value is a single-moment snapshot.

Note

Safe to call from any context.

Since

0.1.0

Read the host port's D+/D- line state (SYSSTS0.LNST).

Pure MMIO read of SYSSTS0.LNST; no state is modified.

Parameters

[in]

speed

See header.

Returns

LNST[1:0] (0 = SE0 / nothing attached, 1 = J-state).

Return values

0	Invalid speed, controller not powered, or SE0.

Precondition

Module state is consistent.

The controller is clocked for a meaningful read.

Postcondition

No register is modified.

Caller-visible state matches the documented contract.

Note

Safe to call from any context.

Since

0.1.0

Definition at line 476 of file ra8_usb_host_bulk.c.

References k_ra8_usb_lnst_mask, priv_pick(), and r_usb_regs_t::SYSSTS0.

Referenced by cdc_enum_hunt(), dfu_enum_hunt(), hid_enum_hunt(), hid_enum_hunt(), internal_enum_hunt(), internal_enum_hunt(), and ns_host_enum_hunt().

ra8_usb_host_pipe_setup()

ra8_err_t ra8_usb_host_pipe_setup ( ra8_usb_speed_t speed, uint8_t pipe_num, uint8_t dev_addr, uint8_t ep_num, bool device_to_host, uint16_t max_packet )

nodiscard

Configure a controller pipe against an attached device's bulk endpoint.

Host-mode counterpart of ra8_usb_configure_endpoint: programs PIPECFG (bulk type; DIR mapped so device-to-host = receiving), PIPEBUF, and PIPEMAXP including DEVSEL = dev_addr, then forces the DATA0 sequence (SQCLR) and parks the pipe NAK with its BRDY/NRDY/BEMP status bits cleared. Use PIPE1 for the device's bulk-IN endpoint and PIPE2 for its bulk-OUT endpoint in the MSC bring-up.

Parameters

[in]	speed	Which controller (FS or HS).
[in]	pipe_num	Controller pipe to program (1..9).
[in]	dev_addr	Target device address (0..10).
[in]	ep_num	Device endpoint number (1..15, no direction bit).
[in]	device_to_host	true for the device's IN endpoint (host receives), false for its OUT endpoint.
[in]	max_packet	Endpoint wMaxPacketSize from the descriptor.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Pipe configured, DATA0 forced, parked NAK.
k_ra8_err_invalid_arg	An argument is out of range.

Precondition

ra8_usb_host_init ran and SET_CONFIGURATION reset the endpoint.

The pipe is not currently armed (no transfer in flight).

Postcondition

The pipe targets dev_addr endpoint ep_num with PID = NAK.

The pipe's BRDY/NRDY/BEMP status bits are cleared.

Note

Not thread-safe.

Since

0.1.0

Configure a controller pipe against an attached device's bulk endpoint.

See the public header for the documented contract; configures a bulk pipe against an attached device's endpoint. In host mode PIPECFG.DIR keeps its transmit/receive sense: receiving (device-to-host IN) is DIR=0 and transmitting (host-to-device OUT) is DIR=1, so the device-mode encoder is reused with the mapped direction. PIPEnCTR shares the DCPCTR SQCLR bit layout.

Parameters

[in]	speed	See header.
[in]	pipe_num	See header.
[in]	dev_addr	See header.
[in]	ep_num	See header.
[in]	device_to_host	See header.
[in]	max_packet	See header.

Returns

Result code.

Return values

k_ra8_ok

Pipe configured, DATA0 forced, parked NAK.

Precondition

Module state is consistent.

SET_CONFIGURATION has reset the device endpoint to DATA0.

Postcondition

The pipe targets dev_addr endpoint ep_num, PID = NAK.

The pipe's BRDY/NRDY/BEMP status bits are cleared.

Note

Not thread-safe.

Since

0.1.0

Definition at line 200 of file ra8_usb_host_bulk.c.

References r_usb_regs_t::BEMPSTS, r_usb_regs_t::BRDYSTS, internal_host_pipe_args_ok(), k_ra8_dcpctr_bit_sqclr, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_devsel_shift, k_ra8_usb_ep_dir_in, k_ra8_usb_ep_dir_out, k_ra8_usb_ep_type_bulk, k_ra8_usb_pipemaxp_mxps, r_usb_regs_t::NRDYSTS, r_usb_regs_t::PIPEBUF, r_usb_regs_t::PIPECFG, r_usb_regs_t::PIPECTR, r_usb_regs_t::PIPEMAXP, r_usb_regs_t::PIPEPERI, r_usb_regs_t::PIPESEL, priv_pick(), priv_pipe_quiesce(), priv_pipebuf_word(), priv_pipecfg_word(), and priv_rmw16().

Referenced by cdc_open_pipes(), hid_open_pipes(), hid_open_pipes(), internal_enum_configure(), and ns_host_open_pipes().

ra8_usb_host_set_target()

ra8_err_t ra8_usb_host_set_target ( ra8_usb_speed_t speed, uint8_t dev_addr )

nodiscard

Retarget the host's default control pipe at a device address.

Programs the DEVADDn slot for dev_addr with the connected link speed (copied from DVSTCTR0.RHST) and loads DCPMAXP.DEVSEL so subsequent control transfers carry tokens addressed to dev_addr. Call after a successful SET_ADDRESS control transfer (plus the 2 ms set-address recovery the USB spec grants the device).

Parameters

[in]	speed	Which controller (FS or HS).
[in]	dev_addr	Address the device was assigned (0..10).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	The DCP now targets dev_addr.
k_ra8_err_invalid_arg	speed or dev_addr out of range.

Precondition

ra8_usb_host_init ran; the bus reset completed (RHST valid).

No control transfer is in flight on the DCP.

Postcondition

DCPMAXP.DEVSEL equals dev_addr with MXPS preserved.

The DEVADDn slot for dev_addr carries the link speed.

Note

Not thread-safe.

Since

0.1.0

Retarget the host's default control pipe at a device address.

See the public header for the documented contract; programs the DEVADDn slot for dev_addr from the live RHST and retargets the DCP by loading DCPMAXP.DEVSEL while preserving MXPS.

Parameters

[in]	speed	See header.
[in]	dev_addr	See header.

Returns

Result code.

Return values

k_ra8_ok

Target address applied.

Precondition

Module state is consistent.

The DCP is idle (no SUREQ pending).

Postcondition

DCPMAXP.DEVSEL = dev_addr; DEVADDn carries the link speed.

Subsequent control transfers address dev_addr.

Note

Not thread-safe.

Since

0.1.0

Definition at line 112 of file ra8_usb_host_bulk.c.

References r_usb_regs_t::DCPMAXP, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_dcpmaxp_mxps, k_ra8_usb_dev_addr_max, k_ra8_usb_devsel_shift, priv_host_program_devadd(), and priv_pick().

Referenced by cdc_enum_hunt(), cdc_enum_set_address(), dfu_enum_hunt(), dfu_enum_set_address(), hid_enum_hunt(), hid_enum_hunt(), hid_enum_set_address(), hid_enum_set_address(), internal_enum_assign_addr(), internal_enum_hunt(), internal_enum_hunt(), internal_set_address(), ns_host_enum_hunt(), and ns_host_set_address().

ra8_usb_host_set_uact()

ra8_err_t ra8_usb_host_set_uact ( ra8_usb_speed_t speed, bool enable )

nodiscard

Enable / disable SOF (Start-of-Frame) generation on the bus.

Toggles DVSTCTR0.UACT. With UACT = 1 the controller starts generating SOF tokens at the spec-required cadence (1 ms FS / 125 us HS). UACT = 0 leaves the bus idle.

Parameters

[in]	speed	Which controller.
[in]	enable	true to enable SOF generation, false to halt.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	UACT updated.
k_ra8_err_invalid_arg	speed out of range.

Precondition

ra8_usb_host_init ran for this speed.

Postcondition

DVSTCTR0.UACT matches enable.

Note

Not thread-safe.

Since

0.1.0

Enable / disable SOF (Start-of-Frame) generation on the bus.

See the public header for the documented contract; this definition implements it.

Parameters

[in]	speed	See implementation.
[in]	enable	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 487 of file ra8_usb_irq.c.

References r_usb_regs_t::DVSTCTR0, k_ra8_dvstctr_bit_uact, k_ra8_err_invalid_arg, k_ra8_ok, priv_pick(), and priv_rmw16().

Referenced by cdc_enum_hunt(), dfu_enum_hunt(), hid_enum_hunt(), hid_enum_hunt(), internal_enum_hunt(), internal_enum_hunt(), internal_port_set_enabled(), ns_host_enum_hunt(), ra8_usb_haud_close(), ra8_usb_hcdc_close(), ra8_usb_hcdc_ecm_close(), ra8_usb_hhid_close(), ra8_usb_hhub_close(), ra8_usb_hmsc_close(), and ux_hcd_ra8_usb_uninitialize().

ra8_usb_host_setup_request()

ra8_err_t ra8_usb_host_setup_request ( ra8_usb_speed_t speed, const ra8_usb_setup_t * setup )

nodiscard

Issue a SETUP packet through the DCP (host -> peripheral).

Programs USBREQ, USBVAL, USBINDX, USBLENG from setup and sets DCPCTR.SUREQ so the controller transmits an 8-byte SETUP stage on the next bus frame. The data and status stages are driven by ra8_usb_queue_in / ra8_usb_queue_out on the DCP, plus subsequent DCPCTR.PID / DCPCTR.CCPL writes via ra8_usb_control_response. This wraps FSP's usb_hstd_setup_command low-level path.

Parameters

[in]	speed	Which controller.
[in]	setup	The 8-byte SETUP packet to transmit.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	SETUP queued; controller will transmit on next frame.
k_ra8_err_invalid_arg	speed out of range.
k_ra8_err_null_ptr	setup was NULL.
k_ra8_err_busy	DCPCTR.SUREQ was still asserted from a prior request.

Precondition

ra8_usb_host_init ran for this speed.

setup non-NULL.

Postcondition

USBREQ, USBVAL, USBINDX, USBLENG all loaded.

DCPCTR.SUREQ = 1 until the controller clears it.

Note

Not thread-safe.

Since

0.1.0

Issue a SETUP packet through the DCP (host -> peripheral).

See the public header for the documented contract; this definition implements it.

Parameters

[in]	speed	See implementation.
[in]	setup	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 517 of file ra8_usb_irq.c.

References ra8_usb_setup_t::b_request, ra8_usb_setup_t::bm_request_type, r_usb_regs_t::DCPCTR, k_ra8_dcpctr_bit_sureq, k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_byte_bits, priv_pick(), priv_rmw16(), RA8_CHECK_NULL_PTR, s_tag, r_usb_regs_t::USBINDX, r_usb_regs_t::USBLENG, r_usb_regs_t::USBREQ, r_usb_regs_t::USBVAL, ra8_usb_setup_t::w_index, ra8_usb_setup_t::w_length, and ra8_usb_setup_t::w_value.

Referenced by internal_control_xfer(), internal_setup_get_descriptor(), internal_setup_get_descriptor(), internal_setup_get_descriptor(), internal_setup_get_descriptor(), internal_setup_get_descriptor(), internal_setup_get_hub_descriptor(), internal_setup_get_report_descriptor(), internal_setup_set_address(), internal_setup_set_address(), internal_setup_set_address(), internal_setup_set_address(), internal_setup_set_address(), internal_setup_set_config(), internal_setup_set_config(), internal_setup_set_config(), internal_setup_set_config(), internal_setup_set_config(), internal_setup_set_interface(), internal_setup_set_interface(), internal_setup_set_interface(), internal_setup_set_interface_data(), internal_setup_set_packet_filter(), ra8_usb_haud_set_format(), ra8_usb_haud_set_mute(), ra8_usb_haud_set_volume(), ra8_usb_hcdc_ecm_get_link_status(), ra8_usb_hcdc_set_line_coding(), ra8_usb_hhid_get_report(), ra8_usb_hhid_set_idle(), ra8_usb_hhid_set_protocol(), ra8_usb_hhid_set_report(), ra8_usb_hhub_clear_port_feature(), ra8_usb_hhub_get_port_status(), and ra8_usb_hhub_set_port_feature().