usb_host_keyboard_steps.h File Reference

Shared seam between usb_host_keyboard main.c and its sibling TUs. More...

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

Include dependency graph for usb_host_keyboard_steps.h:

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

Go to the source code of 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_mask_t : uint32_t {   k_hid_nibble_mask = 0xFU ,   k_hid_dec_radix = 10U }
	Bit-mask constants used by the text formatters. 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 ,   k_hid_key0_idx = 2U ,   k_hid_nkeys = 5U }
	HID report + interrupt-pipe + pattern constants. More...
enum	hid_keycode_t : uint8_t {   k_hid_kc_a = 0x04U ,   k_hid_kc_z = 0x1DU ,   k_hid_kc_1 = 0x1EU ,   k_hid_kc_0 = 0x27U ,   k_hid_kc_r = 0x15U ,   k_hid_kc_8 = 0x25U ,   k_hid_kc_d = 0x07U ,   k_hid_kc_2 = 0x1FU }
	HID Usage-Table keycode ranges for decoding keycodes back to ASCII. 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).
VOID	hid_device_worker (ULONG arg)
	Device-side worker: bring the HID device up, then send reports.
void	usb_host_keyboard_device_thread_create (void)
	Create + auto-start the USBX HID device worker thread.
uint8_t	hid_nibble_to_hex (uint32_t nibble)
	Format one nibble (0..15) into an uppercase hex character.
uint32_t	hid_str_len (const char *text)
	Bounded ASCII string length (cap k_hid_print_cap).
ra8_err_t	hid_sci_write (const uint8_t *data, uint32_t len)
	Push a literal block over SCI8 polled.
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.

Variables
TX_SEMAPHORE	s_usb_host_keyboard_hid_active_sem
	Activation semaphore shared by the device worker and main.c.

Detailed Description

Shared seam between usb_host_keyboard main.c and its sibling TUs.

Tag

[Ring 6 / APP] {World: S}

Declares the helper clusters carved out of the oversized usb_host_keyboard/main.c so that every translation unit stays under the 1000-line cap. Two siblings sit behind this header:

• usb_host_keyboard_console.c – the SCI8 -> J-Link OB CDC console formatters (hid_print*, hid_sci_write, hid_str_len, hid_nibble_to_hex). main.c's host-side ladder calls these.
• usb_host_keyboard_device.c – the USBX HID device worker (descriptors, activate / deactivate callbacks, report send loop, and the device-thread bring-up helper). main.c's tx_application_define spawns the worker.

Only the symbols that genuinely cross a TU boundary are published here. The shared compile-time enums live in this header so both siblings and main.c agree on one definition. The shared report-pattern builder (hid_fill_report_body) is computed by the device side and re-computed by the host side to verify, so it is published too. The activation semaphore is the single mutable object the device worker and main.c share; it is defined once in main.c as s_usb_host_keyboard_hid_active_sem and externed here.

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_host_keyboard_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 53 of file usb_host_keyboard_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: modifier / 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.
k_hid_key0_idx	Boot-keyboard first-keycode byte.
k_hid_nkeys	Keycodes typed ("RA8D2").

Definition at line 91 of file usb_host_keyboard_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 70 of file usb_host_keyboard_steps.h.

hid_keycode_t

enum hid_keycode_t : uint8_t

HID Usage-Table keycode ranges for decoding keycodes back to ASCII.

Enumerator
k_hid_kc_a	Keycode for 'a' / 'A'.
k_hid_kc_z	Keycode for 'z' / 'Z'.
k_hid_kc_1	Keycode for '1'.
k_hid_kc_0	Keycode for '0' (top of digits).
k_hid_kc_r	Keycode for 'r' / 'R'.
k_hid_kc_8	Keycode for '8'.
k_hid_kc_d	Keycode for 'd' / 'D'.
k_hid_kc_2	Keycode for '2'.

Definition at line 113 of file usb_host_keyboard_steps.h.

hid_mask_t

enum hid_mask_t : uint32_t

Bit-mask constants used by the text formatters.

Enumerator
k_hid_nibble_mask	4-bit nibble mask.
k_hid_dec_radix	Base for decimal conversion.

Definition at line 82 of file usb_host_keyboard_steps.h.

Function Documentation

hid_device_worker()

VOID hid_device_worker

(

ULONG

arg

)

Device-side worker: bring the HID device up, then send reports.

USBX system + device stack + HID class + DCD bridge on the USBFS controller, then DPRPU attach. Blocks on the activation semaphore until the host configures the device, then loops to keep the interrupt-IN report queue fed.

Parameters

[in]

arg

ThreadX entry argument (unused).

Precondition

tx_application_define created this thread.

USB-FS pins + 48 MHz clock are up (main did both).

Postcondition

The FS device is attached and streaming input reports.

On any bring-up failure the thread exits.

Note

Runs once; loops forever on success.

Since

0.1.0

Definition at line 515 of file usb_host_keyboard_device.c.

References hid_class_register(), hid_send_iter(), hid_usbx_stack_up(), k_hid_dev_step_attach, k_hid_dev_step_class, k_hid_dev_step_dcd, k_hid_dev_step_send, k_hid_dev_step_stack, k_ra8_ok, k_ra8_usb_speed_fs, ra8_usb_device_attach(), s_dbg_dev_err, s_dbg_dev_step, s_hid_class, s_usb_host_keyboard_hid_active_sem, TX_WAIT_FOREVER, and ux_dcd_ra8_usb_initialize().

Referenced by tx_application_define(), and usb_host_keyboard_device_thread_create().

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

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_key0_idx, k_hid_nkeys, and s_kbd_keys.

Referenced by hid_get_callback(), hid_read_round(), hid_read_round(), and hid_send_iter().

hid_nibble_to_hex()

uint8_t hid_nibble_to_hex

(

uint32_t

nibble

)

Format one nibble (0..15) into an uppercase hex character.

Parameters

[in]

nibble

4-bit value.

Returns

ASCII '0'..'9' or 'A'..'F'.

Return values

'0'	For a zero nibble.

Precondition

Caller has masked the value to 4 bits.

None beyond the mask contract.

Postcondition

Returned byte is printable hex.

No state changes.

Note

Pure function.

Since

0.1.0

Definition at line 31 of file usb_host_keyboard_console.c.

References k_hid_hex_digit_split.

Referenced by hid_print_hex().

hid_print()

ra8_err_t hid_print ( const char * text )

nodiscard

Print a NUL-terminated ASCII string over the console.

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_host_pass(), hid_host_pass(), hid_print_enum(), hid_print_enum(), hid_print_pass(), and hid_print_pass().

hid_print_dec()

ra8_err_t hid_print_dec ( uint32_t value )

nodiscard

Print a uint32_t as ASCII decimal.

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.

Referenced by hid_print_pass(), and hid_print_pass().

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.

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.

Referenced by hid_enumerate(), hid_enumerate(), hid_host_pass(), hid_host_pass(), hid_read_round(), and hid_read_round().

hid_print_hex()

ra8_err_t hid_print_hex ( uint32_t value, uint8_t digits )

nodiscard

Print a value as fixed-width uppercase hex.

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_enum(), and hid_print_enum().

hid_sci_write()

ra8_err_t hid_sci_write ( const uint8_t * data, uint32_t len )

nodiscard

Push a literal block over SCI8 polled.

Parameters

[in]	data	Buffer to send.
[in]	len	Byte count.

Returns

ra8_err_t passthrough from ra8_board_uart_console_write.

Return values

k_ra8_ok

All bytes queued.

Precondition

data is non-NULL; SCI8 init already ran.

len excludes any NUL terminator.

Postcondition

Bytes are in the SCI8 TX FIFO.

No other state changes.

Note

Blocking polled TX.

Since

0.1.0

Definition at line 51 of file usb_host_keyboard_console.c.

References ra8_board_uart_console_write().

Referenced by hid_print(), hid_print_dec(), and hid_print_hex().

hid_str_len()

uint32_t hid_str_len

(

const char *

text

)

Bounded ASCII string length (cap k_hid_print_cap).

Parameters

[in]

text

NUL-terminated string.

Returns

Number of bytes before the NUL, capped.

Return values

0	For an empty string.

Precondition

text is non-NULL.

text points to readable storage of at least the length.

Postcondition

No state changes.

Return value never exceeds k_hid_print_cap.

Note

Bounded scan.

Since

0.1.0

Definition at line 39 of file usb_host_keyboard_console.c.

References k_hid_print_cap.

Referenced by hid_print().

usb_host_keyboard_device_thread_create()

void usb_host_keyboard_device_thread_create

(

void

)

Create + auto-start the USBX HID device worker thread.

Owns the device thread's TCB + stack storage at file scope in the device sibling and spawns hid_device_worker at k_hid_dev_priority. Called once from tx_application_define in main.c.

Precondition

Called from tx_kernel_enter after scheduler init.

The activation semaphore exists.

Postcondition

One auto-start device worker is queued.

The device thread runs at k_hid_dev_priority.

Note

Called once at boot; not thread-safe.

Since

0.1.0

Definition at line 555 of file usb_host_keyboard_device.c.

References hid_device_worker(), k_hid_dev_priority, k_hid_thread_stack, s_device_stack, s_device_thread, s_device_thread_name, TX_AUTO_START, TX_NO_TIME_SLICE, and tx_thread_create.

Referenced by tx_application_define().

Variable Documentation

s_usb_host_keyboard_hid_active_sem

TX_SEMAPHORE s_usb_host_keyboard_hid_active_sem

extern

Activation semaphore shared by the device worker and main.c.

Posted by the activate callback so the send worker blocks on it instead of polling s_hid_class with tx_thread_sleep (which has been observed never returning on this silicon under load).

Posted by the HID activate callback (device sibling) so the send worker blocks on it instead of polling; created by tx_application_define in main.c. Defined once in main.c.

Note

Single-producer (class thread), single-consumer (send worker).

Since

0.1.0

Defined here; the device worker (sibling TU) and this main.c both reference it via the extern in usb_host_keyboard_steps.h.

Note

Single-producer (class thread), single-consumer (send worker).

Since

0.1.0

Definition at line 163 of file main.c.

Referenced by hid_activate(), hid_device_worker(), and tx_application_define().