Shared contract for the USB HID self-loop console + host clusters. More...

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

Include dependency graph for usb_selftest_hid_steps.h:

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

Enumerations
enum	hid_config_t : uint32_t { k_hid_thread_stack = 4096U , k_hid_host_stack = 8192U , k_hid_usbx_pool_bytes = 32768U , k_hid_idle_ticks = 50U , k_hid_boot_wait_ticks = 500U , k_hid_retry_ticks = 3000U , k_hid_baud = 115200U , k_hid_print_cap = 160U , k_hid_dev_priority = 8U , k_hid_host_priority = 24U }
	Compile-time settings: threads, pool, console, cadence. More...
enum	hid_hex_t : uint8_t { k_hid_hex_chars_u16 = 4U , k_hid_hex_chars_u32 = 8U , k_hid_dec_chars_u32 = 10U , k_hid_nibble_bits = 4U , k_hid_hex_digit_split = 10U }
	Hex/decimal text-formatter sizing constants. More...
enum	hid_geom_t : uint32_t { k_hid_mps = 64U , k_hid_report_len = 8U , k_hid_rounds = 8U , k_hid_read_buf = 64U , k_hid_dev_addr = 1U , k_hid_ep_in_num = 1U , k_hid_pipe_in = 1U , k_hid_seq_idx = 0U , k_hid_body_idx = 1U , k_hid_no_mismatch = 0xFFFFFFFFU , k_hid_pat_idx_mul = 7U , k_hid_pat_bias = 0x5AU , k_hid_byte_mask = 0xFFU }
	HID report + interrupt-pipe + pattern constants. More...

Functions
void	hid_fill_report_body (uint8_t *out, uint32_t len)
	Fill the fixed body of a HID report (bytes 1..len-1).
ra8_err_t	hid_print (const char *text)
	Print a NUL-terminated ASCII string over the console.
ra8_err_t	hid_print_dec (uint32_t value)
	Print a uint32_t as ASCII decimal.
ra8_err_t	hid_print_hex (uint32_t value, uint8_t digits)
	Print a value as fixed-width uppercase hex.
ra8_err_t	hid_print_fail (const char *what, ra8_err_t err)
	Print "FAIL <what> err=0xNNNNNNNN" on its own line.
VOID	hid_host_worker (ULONG arg)
	Host-side worker: retry the full pass until it succeeds.

Detailed Description

Shared contract for the USB HID self-loop console + host clusters.

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

The usb_selftest_hid application is split across three translation units to keep every file under the source-size cap:

main.c owns boot bring-up, the USBX HID device side, the ThreadX workers' creation, and startup.
src/usb_selftest_hid_console.c owns the SCI8 -> J-Link OB CDC console formatters (decimal / hex / fail-line printers).
src/usb_selftest_hid_host.c owns the self-contained polled USB host enumeration ladder, the interrupt-IN report reader, and the host worker.

This header is the seam between those units. It carries the compile-time constant enums shared across the three TUs, the console-formatter prototypes, the shared report-pattern helper, and the host worker entry.

Author: Brighton Sikarskie

Date: 2026-06-13

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

Since: 0.1.0

Definition in file usb_selftest_hid_steps.h.

Enumeration Type Documentation

◆ hid_config_t

enum hid_config_t : uint32_t

Compile-time settings: threads, pool, console, cadence.

Enumerator
k_hid_thread_stack	Device worker stack (bytes).
k_hid_host_stack	Host worker stack (bytes).
k_hid_usbx_pool_bytes	USBX memory pool (bytes).
k_hid_idle_ticks	Parked-loop back-off (ticks).
k_hid_boot_wait_ticks	Host start delay (1 ms ticks).
k_hid_retry_ticks	Pause between ladder retries.
k_hid_baud	J-Link OB CDC log baud.
k_hid_print_cap	Bound for console-string scans.
k_hid_dev_priority	Device bring-up worker priority.
k_hid_host_priority	Host worker priority (below USBX).

Definition at line 44 of file usb_selftest_hid_steps.h.

◆ hid_geom_t

enum hid_geom_t : uint32_t

HID report + interrupt-pipe + pattern constants.

Enumerator
k_hid_mps	Interrupt endpoint wMaxPacketSize.
k_hid_report_len	Vendor input report width (bytes).
k_hid_rounds	Reports the host reads + checks.
k_hid_read_buf	One-MPS receive buffer (bytes).
k_hid_dev_addr	Address the host assigns.
k_hid_ep_in_num	Device interrupt-IN endpoint num.
k_hid_pipe_in	Host pipe for the device IN.
k_hid_seq_idx	Report byte 0: rolling seq.
k_hid_body_idx	Report body starts at byte 1.
k_hid_no_mismatch	Probe: no mismatch.
k_hid_pat_idx_mul	Per-index pattern multiplier.
k_hid_pat_bias	Pattern constant bias.
k_hid_byte_mask	Byte mask.

Definition at line 73 of file usb_selftest_hid_steps.h.

◆ hid_hex_t

enum hid_hex_t : uint8_t

Hex/decimal text-formatter sizing constants.

Enumerator
k_hid_hex_chars_u16	16-bit value -> "ABCD".
k_hid_hex_chars_u32	32-bit value -> "ABCDEF01".
k_hid_dec_chars_u32	Max digits for a 32-bit count.
k_hid_nibble_bits	Bits per hex nibble.
k_hid_hex_digit_split	Threshold between '0-9'/'A-F'.

Definition at line 61 of file usb_selftest_hid_steps.h.

Function Documentation

◆ hid_fill_report_body()

void hid_fill_report_body	(	uint8_t *	out,
		uint32_t	len )

Fill the fixed body of a HID report (bytes 1..len-1).

Body byte i = (i*7 + 0x5A) & 0xFF, independent of the report sequence. Byte 0 (the seq) is left untouched – the device stamps it with a rolling counter and the host ignores it for the pattern check. Both the device (to build) and the host (to verify) compute the same body.

Parameters

[out]	out	Report buffer.
[in]	len	Report width in bytes (>= 1).

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

Postcondition: out[1..len-1] hold the fixed pattern bytes.; out[0] is unchanged.

Note: Pure function (apart from the caller's buffer).

Since: 0.1.0

Boot-keyboard report: byte 1 = reserved, bytes 2.. = the typed "RA8D2" keycodes, the remainder 0. Byte 0 (the seq) is left untouched. Both the device (to build) and the host (to verify) compute the same body.

Parameters

[out]	out	Report buffer.
[in]	len	Report width in bytes (>= 1).

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

Postcondition: out[1..len-1] hold the fixed pattern bytes.; out[0] is unchanged.

Note: Pure function (apart from the caller's buffer).

Since: 0.1.0

Fill the fixed body of a HID report (bytes 1..len-1).

Definition at line 302 of file usb_host_keyboard_device.c.

References k_hid_body_idx, k_hid_byte_mask, k_hid_pat_bias, and k_hid_pat_idx_mul.

Referenced by hid_get_callback(), and hid_send_iter().

◆ hid_host_worker()

VOID hid_host_worker ( ULONG arg )

Host-side worker: retry the full pass until it succeeds.

Waits for the device side to attach, then loops the full host pass with a retry pause until every report round verifies; afterwards parks so the verdict stays on the wire.

Parameters

[in] arg ThreadX entry argument (unused).

Precondition: tx_application_define created this thread.; The HS host pins, expander switch, and PLL are up (main).

Postcondition: On success the pass counter and LED2 are latched.; Retries forever otherwise; each failure prints its step.

Note: Blocking calls; ms timeouts via ra8_time.

Since: 0.1.0

Definition at line 502 of file usb_selftest_hid_host.c.

References hid_host_pass(), k_hid_boot_wait_ticks, k_hid_idle_ticks, k_hid_retry_ticks, k_ra8_ok, and tx_thread_sleep.

◆ hid_print()

ra8_err_t hid_print ( const char * text )

nodiscard

Print a NUL-terminated ASCII string over the console.

Length-bounded by the console-string cap.

Parameters

[in] text String to print (CR/LF included by the caller).

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran; text is non-NULL.; text is NUL-terminated within k_hid_print_cap bytes.

Postcondition: The string bytes are in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Parameters

[in] text String to print (CR/LF included by the caller).

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran; text is non-NULL.; text is NUL-terminated within k_hid_print_cap bytes.

Postcondition: The string bytes are in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 56 of file usb_host_keyboard_console.c.

References hid_sci_write(), and hid_str_len().

Referenced by hid_print_fail().

◆ hid_print_dec()

ra8_err_t hid_print_dec ( uint32_t value )

nodiscard

Print a uint32_t as ASCII decimal.

Digit-reversal into a bounded scratch buffer.

Parameters

[in] value Value to print.

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran.; None beyond console readiness.

Postcondition: One ASCII decimal token is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Parameters

[in] value Value to print.

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran.; None beyond console readiness.

Postcondition: One ASCII decimal token is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 61 of file usb_host_keyboard_console.c.

References hid_sci_write(), k_hid_dec_chars_u32, and k_hid_dec_radix.

◆ hid_print_fail()

ra8_err_t hid_print_fail	(	const char *	what,
		ra8_err_t	err )

nodiscard

Print "FAIL <what> err=0xNNNNNNNN" on its own line.

One-line diagnostic; first failing chunk's code returned.

Parameters

[in]	what	Short description of the failed step.
[in]	err	Error code returned by the step.

Returns: ra8_err_t propagated from the SCI helpers.

Return values

k_ra8_ok The diagnostic line is queued.

Precondition: SCI8 init already ran.; what is NUL-terminated within the print cap.

Postcondition: One diagnostic line is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Parameters

[in]	what	Short description of the failed step.
[in]	err	Error code returned by the step.

Returns: ra8_err_t propagated from the SCI helpers.

Return values

k_ra8_ok The diagnostic line is queued.

Precondition: SCI8 init already ran.; what is NUL-terminated within the print cap.

Postcondition: One diagnostic line is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 99 of file usb_host_keyboard_console.c.

References hid_print(), hid_print_hex(), k_hid_hex_chars_u32, and k_ra8_ok.

◆ hid_print_hex()

ra8_err_t hid_print_hex	(	uint32_t	value,
		uint8_t	digits )

nodiscard

Print a value as fixed-width uppercase hex.

Width is clamped to 8 hex digits.

Parameters

[in]	value	Value to print.
[in]	digits	Hex digit count (4 for u16, 8 for u32).

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran.; digits is at most k_hid_hex_chars_u32.

Postcondition: One fixed-width hex token is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Parameters

[in]	value	Value to print.
[in]	digits	Hex digit count (4 for u16, 8 for u32).

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran.; digits is at most k_hid_hex_chars_u32.

Postcondition: One fixed-width hex token is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 85 of file usb_host_keyboard_console.c.

References hid_nibble_to_hex(), hid_sci_write(), k_hid_hex_chars_u32, k_hid_nibble_bits, and k_hid_nibble_mask.

Referenced by hid_print_fail().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ hid_config_t

◆ hid_geom_t

◆ hid_hex_t

Function Documentation

◆ hid_fill_report_body()

◆ hid_host_worker()

◆ hid_print()

◆ hid_print_dec()

◆ hid_print_fail()

◆ hid_print_hex()