Non-Secure USBHS polled HOST ladder: enumerate + bulk echo (#96). More...

#include <stdint.h>
#include <string.h>
#include "ns_usb_internal.h"
#include "ra8_usb.h"
#include "tx_api.h"

Include dependency graph for ns_usb_host.c:

Enumerations
enum	ns_host_req_t : uint16_t { k_ns_bm_std_dev_in = 0x80U , k_ns_bm_std_dev_out = 0x00U , k_ns_breq_get_desc = 0x06U , k_ns_breq_set_addr = 0x05U , k_ns_breq_set_config = 0x09U , k_ns_desc_device = 0x01U , k_ns_dev_desc_len = 18U , k_ns_off_dev_pid = 10U , k_ns_byte_bits = 8U , k_ns_config_value = 1U }
	Chapter-9 standard request / descriptor constants for the host. More...
enum	ns_host_tune_t : uint32_t { k_ns_vbus_settle_ms = 200U , k_ns_attach_to_ms = 2000U , k_ns_debounce_ms = 500U , k_ns_reset_hold_ms = 50U , k_ns_recovery_ms = 20U , k_ns_addr_settle_ms = 5U , k_ns_enum_tries = 8U , k_ns_attach_spin = 50000000U , k_ns_dev_addr = 1U , k_ns_mps = 64U , k_ns_payload = 60U , k_ns_echo_buf = 64U , k_ns_ep_in_num = 1U , k_ns_ep_out_num = 2U , k_ns_host_pipe_in = 1U , k_ns_host_pipe_out = 2U , k_ns_pat_round_mul = 97U , k_ns_pat_idx_mul = 7U , k_ns_pat_bias = 0x5AU , k_ns_byte_mask = 0xFFU , k_ns_boot_wait_tk = 500U , k_ns_retry_tk = 1000U }
	Host enumeration timing / retry / geometry tunables. More...

Functions
static void	ns_host_pattern_fill (uint32_t round, uint8_t *out, uint32_t len)
	Fill an echo payload with this round's deterministic bytes.
static ra8_err_t	ns_host_get_dev_desc (uint8_t *desc)
	GET_DESCRIPTOR(DEVICE) over the polled host control engine.
static ra8_err_t	ns_host_enum_hunt (uint8_t *desc)
	Wait for attach, then bus-reset + read the device descriptor.
static ra8_err_t	ns_host_set_address (void)
	SET_ADDRESS to k_ns_dev_addr, then retarget the DCP.
static ra8_err_t	ns_host_set_config (void)
	SET_CONFIGURATION(::k_ns_config_value) on the addressed device.
static ra8_err_t	ns_host_open_pipes (void)
	Open the host bulk pipes for the device's CDC data endpoints.
static ra8_err_t	ns_host_enumerate (uint32_t *out_pid)
	Full enumeration ladder: hunt, SET_ADDRESS, SET_CONFIG, open pipes.
static ra8_err_t	ns_host_echo_round (uint32_t round)
	One echo round: bulk-OUT a pattern, bulk-IN the echo, compare.
VOID	ns_host_worker (ULONG arg)
	HS host worker – enumerate the looped FS device, then echo forever.

Variables
volatile uint32_t	g_tz_usb_host_phase
	HS-host ladder phase: 0 boot, 1 host-init, 2 enumerating, 3 echoing, 4 first full pass done.
volatile uint32_t	g_tz_usb_host_pid
	idProduct the HS host read from the looped FS device (expect 0x000A).
volatile uint32_t	g_tz_usb_host_rounds_ok
	Bulk echo rounds the HS host has verified byte-equal (advances forever once the loop is healthy – the HIL gate probes this).
volatile uint32_t	g_tz_usb_host_err
	First non-OK ra8_err_t from the host ladder (0 = none yet).
TX_THREAD	s_ns_host_thread
	ThreadX TCB for the HS host worker (defined in ns_usb_host.c).
UCHAR	s_ns_host_stack [k_ns_host_stack_bytes]
	Stack backing storage for s_ns_host_thread (defined in ns_usb_host.c).
CHAR	s_ns_host_thread_name [] = "ns_usb_host"
	HS host worker thread name (defined in ns_usb_host.c; ThreadX CHAR*).

Detailed Description

Non-Secure USBHS polled HOST ladder: enumerate + bulk echo (#96).

Tag: [Ring 6 / APP] {World: NS}

Split out of ns_usb.c for the 1000-line file-size cap. This TU owns the J7 USBHS HOST side of the self-loop: USBHS (J7) is wired host-side by the Secure boot (PSARB12, host-mode expander, J7 VBUS, UTMI PLL). The ns_host_worker enumerates the FS CDC device over the loop cable using the first-party ra8_usb_host_* polled primitives – no IRQ – and then bulk round-trips a deterministic pattern through the device's auto-echo. It runs at the SAME ThreadX priority as the device dispatch worker (defined in ns_usb.c) with time-slicing, so each thread yields the CPU each tick; the device's chapter-9

auto-echo lands well inside the host primitives' ~10 ms polling windows. Ported from usb_selftest_cdc, with the SCI console dropped (J-Link probes report the verdict instead).

The single tx_application_define that spawns this worker lives in ns_usb.c and reaches ns_host_worker plus this TU's thread storage through ns_usb_internal.h. The ThreadX-backed ra8_delay_ms / ra8_time_ms this ladder uses are likewise defined in ns_usb.c (ra8_time.c is intentionally not linked).

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

Since: 0.1.0

Definition in file ns_usb_host.c.

Enumeration Type Documentation

◆ ns_host_req_t

enum ns_host_req_t : uint16_t

Chapter-9 standard request / descriptor constants for the host.

Enumerator
k_ns_bm_std_dev_in	bmRequestType: Std \| Device \| In.
k_ns_bm_std_dev_out	bmRequestType: Std \| Device \| Out.
k_ns_breq_get_desc	GET_DESCRIPTOR.
k_ns_breq_set_addr	SET_ADDRESS.
k_ns_breq_set_config	SET_CONFIGURATION.
k_ns_desc_device	DEVICE descriptor type.
k_ns_dev_desc_len	DEVICE descriptor length.
k_ns_off_dev_pid	idProduct LSB byte offset.
k_ns_byte_bits	Bits per byte.
k_ns_config_value	bConfigurationValue to select.

Definition at line 105 of file ns_usb_host.c.

◆ ns_host_tune_t

enum ns_host_tune_t : uint32_t

Host enumeration timing / retry / geometry tunables.

Enumerator
k_ns_vbus_settle_ms	VBUS settle before probing.
k_ns_attach_to_ms	Wait for the D+ pull-up.
k_ns_debounce_ms	Post-attach debounce (>=100 ms).
k_ns_reset_hold_ms	USB bus-reset hold (>=10 ms).
k_ns_recovery_ms	Post-reset recovery (TRSTRCY).
k_ns_addr_settle_ms	Post-SET_ADDRESS recovery.
k_ns_enum_tries	Reset+probe attempts.
k_ns_attach_spin	Attach spin cap (frozen-tick guard).
k_ns_dev_addr	Address the host assigns.
k_ns_mps	Bulk endpoint wMaxPacketSize (FS).
k_ns_payload	Bytes per echo round (sub-MPS).
k_ns_echo_buf	One-MPS host scratch buffer.
k_ns_ep_in_num	Device bulk-IN endpoint number.
k_ns_ep_out_num	Device bulk-OUT endpoint number.
k_ns_host_pipe_in	Host pipe for the device bulk-IN.
k_ns_host_pipe_out	Host pipe for the device bulk-OUT.
k_ns_pat_round_mul	Per-round pattern multiplier.
k_ns_pat_idx_mul	Per-index pattern multiplier.
k_ns_pat_bias	Pattern constant bias.
k_ns_byte_mask	Byte mask.
k_ns_boot_wait_tk	Host start delay (ticks).
k_ns_retry_tk	Pause between failed enum passes.

Definition at line 119 of file ns_usb_host.c.

Function Documentation

◆ ns_host_echo_round()

ra8_err_t ns_host_echo_round ( uint32_t round )

staticnodiscard

One echo round: bulk-OUT a pattern, bulk-IN the echo, compare.

Parameters

[in] round The echo round index (pattern key).

Returns: ra8_err_t verdict.

Return values

k_ra8_ok	The echo matched the sent payload.
k_ra8_err_invalid_size	The echo length differed.
k_ra8_err_invalid_state	The echo bytes differed.

Precondition: The bulk pipes were opened by ns_host_open_pipes.; The device dispatch worker is auto-echoing.

Postcondition: Nothing is retained between rounds.; On a mismatch the caller records g_tz_usb_host_err.

Note: Blocking; one bulk-OUT then one bulk-IN over the self-loop.

Since: 0.1.0

Definition at line 368 of file ns_usb_host.c.

References k_ns_echo_buf, k_ns_host_pipe_in, k_ns_host_pipe_out, k_ns_payload, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_usb_speed_hs, memcmp(), ns_host_pattern_fill(), ra8_usb_host_bulk_in(), and ra8_usb_host_bulk_out().

Referenced by ns_host_worker().

◆ ns_host_enum_hunt()

ra8_err_t ns_host_enum_hunt ( uint8_t * desc )

staticnodiscard

Wait for attach, then bus-reset + read the device descriptor.

Parameters

[out] desc Receives the winning 18-byte device descriptor.

Returns: Hunt outcome.

Return values

k_ra8_ok	The device answered at address 0.
k_ra8_err_hw_timeout	Nothing attached / nothing answered.

Precondition: ra8_usb_host_init ran (host up, J7 VBUS supplied).; The ThreadX 1 ms tick is live (ms delays / timeout).

Postcondition: On success the DCP targets address 0 with UACT on.; On failure the bus is left in the last attempt's state.

Note: Blocking; worst case a few seconds.

Since: 0.1.0

Definition at line 212 of file ns_usb_host.c.

References k_ns_attach_spin, k_ns_attach_to_ms, k_ns_debounce_ms, k_ns_enum_tries, k_ns_recovery_ms, k_ns_reset_hold_ms, k_ns_vbus_settle_ms, k_ra8_err_hw_timeout, k_ra8_ok, k_ra8_usb_speed_hs, ns_host_get_dev_desc(), ra8_delay_ms(), ra8_time_ms(), ra8_usb_host_bus_reset(), ra8_usb_host_line_state(), ra8_usb_host_set_target(), and ra8_usb_host_set_uact().

Referenced by ns_host_enumerate().

◆ ns_host_enumerate()

ra8_err_t ns_host_enumerate ( uint32_t * out_pid )

staticnodiscard

Full enumeration ladder: hunt, SET_ADDRESS, SET_CONFIG, open pipes.

Parameters

[out] out_pid Receives the device idProduct on success.

Returns: First failing step's error, or k_ra8_ok.

Return values

k_ra8_ok Device enumerated; bulk pipes open.

Precondition: ra8_usb_host_init succeeded on this pass.; out_pid is non-NULL.

Postcondition: out_pid holds the device idProduct on success.; On failure the bus is left mid-ladder for the caller to deinit.

Note: Blocking; runs on the host worker thread.

Since: 0.1.0

Definition at line 334 of file ns_usb_host.c.

References k_ns_byte_bits, k_ns_dev_desc_len, k_ns_off_dev_pid, k_ra8_ok, ns_host_enum_hunt(), ns_host_open_pipes(), ns_host_set_address(), and ns_host_set_config().

Referenced by ns_host_worker().

◆ ns_host_get_dev_desc()

ra8_err_t ns_host_get_dev_desc ( uint8_t * desc )

staticnodiscard

GET_DESCRIPTOR(DEVICE) over the polled host control engine.

Parameters

[out] desc Receives the 18-byte device descriptor.

Returns: Read outcome.

Return values

k_ra8_ok	All 18 bytes arrived.
k_ra8_err_hw_error	A short descriptor came back.

Precondition: The bus is reset and the DCP targets the device's current address.; desc holds at least k_ns_dev_desc_len bytes.

Postcondition: desc carries the device descriptor on success.; No global state changes.

Note: Blocking (polled control transfer).

Since: 0.1.0

Definition at line 181 of file ns_usb_host.c.

References k_ns_bm_std_dev_in, k_ns_breq_get_desc, k_ns_byte_bits, k_ns_desc_device, k_ns_dev_desc_len, k_ra8_err_hw_error, k_ra8_ok, k_ra8_usb_speed_hs, and ra8_usb_host_control_xfer().

Referenced by ns_host_enum_hunt().

◆ ns_host_open_pipes()

ra8_err_t ns_host_open_pipes ( void )

staticnodiscard

Open the host bulk pipes for the device's CDC data endpoints.

Returns: First failing pipe-setup error, or k_ra8_ok.

Return values

k_ra8_ok Both bulk pipes configured.

Precondition: ns_host_set_config succeeded.; The pipes are not currently armed.

Postcondition: Pipe OUT -> device EP2 OUT, pipe IN -> device EP1 IN, both at MPS.; The pipes target k_ns_dev_addr.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 303 of file ns_usb_host.c.

References k_ns_dev_addr, k_ns_ep_in_num, k_ns_ep_out_num, k_ns_host_pipe_in, k_ns_host_pipe_out, k_ns_mps, k_ra8_ok, k_ra8_usb_speed_hs, and ra8_usb_host_pipe_setup().

Referenced by ns_host_enumerate().

◆ ns_host_pattern_fill()

void ns_host_pattern_fill	(	uint32_t	round,
		uint8_t *	out,
		uint32_t	len )

static

Fill an echo payload with this round's deterministic bytes.

Byte i = (round*97 + i*7 + 0x5A) & 0xFF – distinct per round so the host proves it read back what it sent for that round.

Parameters

[in]	round	The echo round index.
[out]	out	Destination buffer.
[in]	len	Bytes to fill.

Returns: void.

Precondition: out has len writable bytes.; len is at most k_ns_payload.

Postcondition: out[0..len-1] hold the round's pattern bytes.; No global state changes.

Note: Pure function.

Since: 0.1.0

Definition at line 159 of file ns_usb_host.c.

References k_ns_byte_mask, k_ns_pat_bias, k_ns_pat_idx_mul, and k_ns_pat_round_mul.

Referenced by ns_host_echo_round().

◆ ns_host_set_address()

ra8_err_t ns_host_set_address ( void )

staticnodiscard

SET_ADDRESS to k_ns_dev_addr, then retarget the DCP.

Returns: First failing step's error, or k_ra8_ok.

Return values

k_ra8_ok The DCP now targets the operating address.

Precondition: ns_host_enum_hunt succeeded (device answering at address 0).; The bus is active (UACT on).

Postcondition: Later transfers carry tokens to k_ns_dev_addr.; The set-address recovery delay has elapsed.

Note: Blocking (one control transfer + settle).

Since: 0.1.0

Definition at line 252 of file ns_usb_host.c.

References k_ns_addr_settle_ms, k_ns_bm_std_dev_out, k_ns_breq_set_addr, k_ns_dev_addr, k_ra8_ok, k_ra8_usb_speed_hs, ra8_delay_ms(), ra8_usb_host_control_xfer(), and ra8_usb_host_set_target().

Referenced by ns_host_enumerate().

◆ ns_host_set_config()

ra8_err_t ns_host_set_config ( void )

staticnodiscard

SET_CONFIGURATION(::k_ns_config_value) on the addressed device.

Returns: Control-transfer outcome.

Return values

k_ra8_ok The device entered the Configured state.

Precondition: ns_host_set_address succeeded.; The DCP targets k_ns_dev_addr.

Postcondition: On success the device's endpoints are usable.; No global state changes.

Note: Blocking (one control transfer).

Since: 0.1.0

Definition at line 280 of file ns_usb_host.c.

References k_ns_bm_std_dev_out, k_ns_breq_set_config, k_ns_config_value, k_ra8_usb_speed_hs, and ra8_usb_host_control_xfer().

Referenced by ns_host_enumerate().

◆ ns_host_worker()

VOID ns_host_worker ( ULONG arg )

HS host worker – enumerate the looped FS device, then echo forever.

Defined in ns_usb_host.c; forwarded here so the single tx_application_define in ns_usb.c can pass it to tx_thread_create. Enumerates the FS CDC device over the J7 loop cable (GET_DESCRIPTOR / SET_ADDRESS / SET_CONFIGURATION), opens the bulk pipes, then bulk round-trips a deterministic pattern forever, advancing g_tz_usb_host_rounds_ok (the HIL gate).

Parameters

[in] arg Unused (ThreadX entry signature).

Returns: Never returns.

Precondition: tx_application_define auto-started this thread.; The Secure boot delegated USBHS (PSARB12), set host mode + J7 VBUS, and enabled the UTMI PLL; the device worker is bringing the FS device up.

Postcondition: On success g_tz_usb_host_rounds_ok advances forever (HIL gate).; Each failed enumeration pass retries after a pause; the first error code is latched in g_tz_usb_host_err.

Note: Polled host (no IRQ); shares a time-sliced priority with the device.

Since: 0.1.0

Definition at line 398 of file ns_usb_host.c.

References g_tz_usb_host_err, g_tz_usb_host_phase, g_tz_usb_host_pid, g_tz_usb_host_rounds_ok, k_ns_boot_wait_tk, k_ns_retry_tk, k_ra8_ok, k_ra8_usb_speed_hs, ns_host_echo_round(), ns_host_enumerate(), ra8_usb_host_deinit(), ra8_usb_host_init(), and tx_thread_sleep.

Referenced by tx_application_define().

Variable Documentation

◆ g_tz_usb_host_err

volatile uint32_t g_tz_usb_host_err

First non-OK ra8_err_t from the host ladder (0 = none yet).

Note: Read externally by J-Link only.

Since: 0.1.0

Definition at line 75 of file ns_usb_host.c.

Referenced by ns_host_worker().

◆ g_tz_usb_host_phase

volatile uint32_t g_tz_usb_host_phase

HS-host ladder phase: 0 boot, 1 host-init, 2 enumerating, 3 echoing, 4 first full pass done.

Note: Read externally by J-Link only.

Since: 0.1.0

Definition at line 50 of file ns_usb_host.c.

Referenced by ns_host_worker().

◆ g_tz_usb_host_pid

volatile uint32_t g_tz_usb_host_pid

idProduct the HS host read from the looped FS device (expect 0x000A).

Note: Read externally by J-Link only.

Since: 0.1.0

Definition at line 58 of file ns_usb_host.c.

Referenced by ns_host_worker().

◆ g_tz_usb_host_rounds_ok

volatile uint32_t g_tz_usb_host_rounds_ok

Bulk echo rounds the HS host has verified byte-equal (advances forever once the loop is healthy – the HIL gate probes this).

Note: Read externally by J-Link only.

Since: 0.1.0

Definition at line 67 of file ns_usb_host.c.

Referenced by ns_host_worker().

◆ s_ns_host_stack

UCHAR s_ns_host_stack[k_ns_host_stack_bytes]

Stack backing storage for s_ns_host_thread (defined in ns_usb_host.c).

Stack backing storage for s_ns_host_thread.

Sized by k_ns_host_stack_bytes; passed verbatim by the spawner.

Note: Owned by ThreadX once the worker is created.

Warning: Do not write outside the ThreadX stack frame.

Since: 0.1.0; 0.1.0

Definition at line 95 of file ns_usb_host.c.

Referenced by tx_application_define().

◆ s_ns_host_thread

TX_THREAD s_ns_host_thread

ThreadX TCB for the HS host worker (defined in ns_usb_host.c).

ThreadX TCB for the HS host worker.

Spawned by tx_application_define in ns_usb.c; the host worker itself runs from ns_usb_host.c. Declared here so the spawner TU can reference the storage.

Note: Single-writer (ThreadX in the NS image).

Warning: Do not modify outside ThreadX; J-Link / spawner reference only.

Since: 0.1.0

Note: Single-writer (ThreadX in the NS image).

Since: 0.1.0

Definition at line 88 of file ns_usb_host.c.

Referenced by tx_application_define().

◆ s_ns_host_thread_name

CHAR s_ns_host_thread_name[] = "ns_usb_host"

HS host worker thread name (defined in ns_usb_host.c; ThreadX CHAR*).

HS host worker thread name (writable NS data; ThreadX name is CHAR*).

Writable NS data because ThreadX's name_ptr field is CHAR*.

Note: Read by ThreadX / J-Link only.

Warning: Do not mutate after thread creation.

Since: 0.1.0; 0.1.0

Definition at line 102 of file ns_usb_host.c.

Referenced by tx_application_define().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ns_host_req_t

◆ ns_host_tune_t

Function Documentation

◆ ns_host_echo_round()

◆ ns_host_enum_hunt()

◆ ns_host_enumerate()

◆ ns_host_get_dev_desc()

◆ ns_host_open_pipes()

◆ ns_host_pattern_fill()

◆ ns_host_set_address()

◆ ns_host_set_config()

◆ ns_host_worker()

Variable Documentation

◆ g_tz_usb_host_err

◆ g_tz_usb_host_phase

◆ g_tz_usb_host_pid

◆ g_tz_usb_host_rounds_ok

◆ s_ns_host_stack

◆ s_ns_host_thread

◆ s_ns_host_thread_name