ns_usb_internal.h File Reference

Private split-seam shared between ns_usb.c and ns_usb_host.c (#96). More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "tx_api.h"

Include dependency graph for ns_usb_internal.h:

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

Go to the source code of this file.

Enumerations
enum	ns_host_cfg_t : uint32_t {   k_ns_host_stack_bytes = 8192U ,   k_ns_time_slice = 1U }
	HS host worker thread storage geometry + the shared ThreadX time-slice. More...

Functions
void	ra8_delay_ms (uint32_t ms)
	Non-Secure ra8_delay_ms – sleep ms ThreadX ticks.
uint32_t	ra8_time_ms (void)
	Non-Secure ra8_time_ms – monotonic millisecond clock from ThreadX.
VOID	ns_host_worker (ULONG arg)
	HS host worker – enumerate the looped FS device, then echo forever.

Variables
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 []
	HS host worker thread name (defined in ns_usb_host.c; ThreadX CHAR*).

Detailed Description

Private split-seam shared between ns_usb.c and ns_usb_host.c (#96).

Tag

[Ring 6 / APP] {World: NS}

The Non-Secure USB self-loop image is split across two translation units for the 1000-line file-size cap: ns_usb.c holds the USBFS CDC-ACM device (descriptors, callbacks, USBX bring-up, the device worker, and the single tx_application_define), while ns_usb_host.c holds the USBHS polled host ladder (enumerate + bulk echo). tx_application_define lives in ns_usb.c but spawns the host worker defined in ns_usb_host.c, so this header forwards the host worker entry, its ThreadX thread storage, and the thread tunables both TUs need. Everything else stays file-local in its own TU.

Copyright

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

Since

0.1.0

Definition in file ns_usb_internal.h.

Enumeration Type Documentation

ns_host_cfg_t

enum ns_host_cfg_t : uint32_t

HS host worker thread storage geometry + the shared ThreadX time-slice.

Shared by both TUs: ns_usb_host.c sizes s_ns_host_stack with k_ns_host_stack_bytes, and tx_application_define (in ns_usb.c) passes both values to tx_thread_create for the host worker. The same k_ns_time_slice is also applied to the device worker so the two round-robin each tick.

Invariant

k_ns_host_stack_bytes is a multiple of 8 (ThreadX stack align).

Since

0.1.0

Enumerator
k_ns_host_stack_bytes	HS host worker stack (bytes).
k_ns_time_slice	ThreadX time-slice (ticks) per worker.

Definition at line 41 of file ns_usb_internal.h.

Function Documentation

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

ra8_delay_ms()

void ra8_delay_ms

(

uint32_t

ms

)

Non-Secure ra8_delay_ms – sleep ms ThreadX ticks.

Defined in ns_usb.c (the NS image deliberately drops ra8_time.c). The full contract lives on the ra8_time.h declaration; this seam exists so the host ladder in ns_usb_host.c can reach the ThreadX-backed delay.

Parameters

[in]

ms

Milliseconds to block (0 is rounded up to one tick).

Returns

void.

Precondition

Called from ThreadX thread context (the USB / host worker), not an ISR.

The ThreadX scheduler is running (1 ms tick live).

Postcondition

The caller blocked for at least ms ticks.

No SysTick reconfiguration occurs.

Note

Not callable from interrupt context.

See also

ra8_time_ms()

Since

0.1.0

Non-Secure ra8_delay_ms – sleep ms ThreadX ticks.

Busy-wait for at least ms milliseconds.

Loops on s_tick_ms and issues wfi between checks.

Parameters

[in]

ms

Milliseconds to wait. Zero returns immediately.

Precondition

ra8_time_init() has been called.

IRQs are NOT globally masked.

Postcondition

At least ms milliseconds have elapsed.

No internal state modified.

Note

Thread-safe.

Since

0.1.0

Busy-wait for at least ms milliseconds.

ra8_usb calls ra8_delay_ms(1) once during device bring-up. The NS image must NOT link ra8_time.c: its ra8_time_init reprograms the SysTick that ThreadX owns, and its delay else-branch waits on a tick counter the ThreadX SysTick handler never advances. ThreadX's 1 ms tick makes one sleep tick == 1 ms here. Called only from thread context.

Parameters

[in]

ms

Milliseconds to block (0 is rounded up to one tick).

Returns

void.

Precondition

Called from ThreadX thread context (the USB worker), not an ISR.

The ThreadX scheduler is running (1 ms tick live).

Postcondition

The caller blocked for at least ms ticks.

No SysTick reconfiguration occurs.

Note

Not callable from interrupt context.

Since

0.1.0

Definition at line 129 of file ra8_time.c.

References tx_thread_sleep.

ra8_time_ms()

uint32_t ra8_time_ms

(

void

)

Non-Secure ra8_time_ms – monotonic millisecond clock from ThreadX.

Defined in ns_usb.c. The full contract lives on the ra8_time.h declaration; this seam exists so the host ladder in ns_usb_host.c can read the millisecond clock for its attach timeout.

Returns

Milliseconds since the ThreadX scheduler started.

Return values

0	Immediately after the kernel starts.

Precondition

The ThreadX scheduler is running.

Called from thread context.

Postcondition

No state changes (pure read of the kernel tick).

The return value is monotonic between wraps (~49 days).

Note

Thread-safe (single-word kernel read).

See also

ra8_delay_ms()

Since

0.1.0

Non-Secure ra8_time_ms – monotonic millisecond clock from ThreadX.

Get the current 1 kHz tick count.

Returns the SysTick-incremented s_tick_ms counter.

Returns

Milliseconds since ra8_time_init(), modulo 2^32.

Return values

0..UINT32_MAX

Current tick count.

Precondition

ra8_time_init() has been called.

Reader is OK with single-word atomicity.

Postcondition

No state modified.

Successive calls are non-decreasing modulo 2^32.

Note

Thread-safe (atomic single-word read on Cortex-M).

Since

0.1.0

Get the current 1 kHz tick count.

The polled host ladder (cdc_enum_hunt) uses ra8_time_ms for its attach timeout. ThreadX's tick is 1 ms here, so tx_time_get (ticks since boot) is already a millisecond count. Replaces ra8_time.c (dropped from the NS link – see ra8_delay_ms).

Returns

Milliseconds since the ThreadX scheduler started.

Return values

0	Immediately after the kernel starts.

Precondition

The ThreadX scheduler is running.

Called from thread context.

Postcondition

No state changes (pure read of the kernel tick).

The return value is monotonic between wraps (~49 days).

Note

Thread-safe (single-word kernel read).

Since

0.1.0

Definition at line 108 of file ra8_time.c.

References tx_time_get.

Variable Documentation

s_ns_host_stack

UCHAR s_ns_host_stack[k_ns_host_stack_bytes]

extern

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

extern

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[]

extern

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