|
ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
|
Native USB host-side HID (Human Interface Device) class layer. More...
Go to the source code of this file.
Data Structures | |
| struct | ra8_usb_hhid_device_t |
| Snapshot of the attached HID device, passed to the attach callback. More... | |
Typedefs | |
| typedef void(* | ra8_usb_hhid_attach_fn_t) (void *ctx, const ra8_usb_hhid_device_t *device) |
| Attach-callback signature. | |
Enumerations | |
| enum | ra8_usb_hhid_pipe_t : uint8_t { k_ra8_hhid_pipe_intr_in = 6U , k_ra8_hhid_pipe_intr_out = 7U } |
| PIPE numbers used by the host-HID driver for the attached peripheral's interrupt endpoints. More... | |
| enum | ra8_usb_hhid_packet_t : uint16_t { k_ra8_hhid_intr_max_packet_default = 8U , k_ra8_hhid_intr_max_packet_fs = 64U , k_ra8_hhid_intr_max_packet_hs = 1024U } |
| Packet sizing for the attached device's interrupt endpoints. More... | |
| enum | ra8_usb_hhid_class_t : uint8_t { k_ra8_hhid_class_hid = 0x03U , k_ra8_hhid_subclass_none = 0x00U , k_ra8_hhid_subclass_boot = 0x01U , k_ra8_hhid_protocol_other = 0x00U , k_ra8_hhid_protocol_keyboard = 0x01U , k_ra8_hhid_protocol_mouse = 0x02U } |
| Class / subclass / protocol triplet that identifies an HID function within an attached USB device's descriptor walk. More... | |
| enum | ra8_usb_hhid_request_t : uint8_t { k_ra8_hhid_req_get_report = 0x01U , k_ra8_hhid_req_get_idle = 0x02U , k_ra8_hhid_req_get_protocol = 0x03U , k_ra8_hhid_req_set_report = 0x09U , k_ra8_hhid_req_set_idle = 0x0AU , k_ra8_hhid_req_set_protocol = 0x0BU } |
| HID class-specific request codes the host issues to the attached device. More... | |
| enum | ra8_usb_hhid_report_type_t : uint8_t { k_ra8_hhid_report_type_input = 0x01U , k_ra8_hhid_report_type_output = 0x02U , k_ra8_hhid_report_type_feature = 0x03U } |
| HID report-type selector encoded in wValue's high byte for GET_REPORT / SET_REPORT. More... | |
| enum | ra8_usb_hhid_protocol_select_t : uint8_t { k_ra8_hhid_proto_boot = 0U , k_ra8_hhid_proto_report = 1U } |
| wValue payload for SET_PROTOCOL. More... | |
| enum | ra8_usb_hhid_desc_t : uint8_t { k_ra8_hhid_desc_hid = 0x21U , k_ra8_hhid_desc_report = 0x22U , k_ra8_hhid_desc_physical = 0x23U } |
| HID-specific descriptor types (USB HID 1.11 sec 7.1). More... | |
| enum | ra8_usb_hhid_report_buf_t : uint16_t { k_ra8_hhid_report_desc_max = 256U } |
| Compile-time ceiling on the cached HID Report descriptor. More... | |
Functions | |
| ra8_err_t | ra8_usb_hhid_init (ra8_usb_speed_t speed) |
| Bring up the host-HID driver on a chosen USB controller. | |
| ra8_err_t | ra8_usb_hhid_close (void) |
| Tear down the host-HID driver and release the controller. | |
| ra8_err_t | ra8_usb_hhid_attach_callback (ra8_usb_hhid_attach_fn_t on_attach, void *ctx) |
| Register (or detach) the attach callback. | |
| ra8_err_t | ra8_usb_hhid_get_report (ra8_usb_hhid_report_type_t target_report_type, uint8_t target_report_id, uint8_t *out_buf, uint16_t max_len, uint16_t *got_len) |
| Issue GET_REPORT (USB HID 1.11 sec 7.2.1) over the DCP. | |
| ra8_err_t | ra8_usb_hhid_set_report (ra8_usb_hhid_report_type_t target_report_type, uint8_t target_report_id, const uint8_t *in_buf, uint16_t len) |
| Issue SET_REPORT (USB HID 1.11 sec 7.2.2) over the DCP. | |
| ra8_err_t | ra8_usb_hhid_set_idle (uint8_t duration, uint8_t report_id) |
| Issue SET_IDLE (USB HID 1.11 sec 7.2.4) over the DCP. | |
| ra8_err_t | ra8_usb_hhid_set_protocol (ra8_usb_hhid_protocol_select_t boot_or_report) |
| Issue SET_PROTOCOL (USB HID 1.11 sec 7.2.6) over the DCP. | |
| ra8_err_t | ra8_usb_hhid_get_input_report (uint8_t *out_buf, uint16_t max_len, uint16_t *got_len) |
| Drain the next input report from the interrupt-IN pipe. | |
| ra8_err_t | ra8_usb_hhid_step (void) |
| Drive the enumeration step machine forward by one step. | |
Native USB host-side HID (Human Interface Device) class layer.
Glues the host-mode bring-up paths in ra8_usb to a USB HID peripheral - typically a keyboard, mouse, or gamepad - attached on the EK-RA8D2's USB-host port. Mirrors FSP's r_usb_hhid host-HID class flow but compiled as part of this tree with no FSP / CherryUSB / TinyUSB binaries pulled in.
Lifecycle (mirrors ra8_usb_hcdc.h / ra8_usb_hmsc.h shape):
The starter only tracks a single attached HID device; hubs and multi-interface composite HID devices are deferred follow-ups.
Reference: USB Device Class Definition for Human Interface Devices (HID) revision 1.11 (USB-IF, 2001-06-27).
Definition in file ra8_usb_hhid.h.
| typedef void(* ra8_usb_hhid_attach_fn_t) (void *ctx, const ra8_usb_hhid_device_t *device) |
Attach-callback signature.
| [in] | ctx | Caller-supplied context registered with ra8_usb_hhid_attach_callback. |
| [in] | device | Snapshot of the attached HID device. The pointer remains valid only for the duration of the call; copy out anything you need. |
Definition at line 215 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_class_t : uint8_t |
Class / subclass / protocol triplet that identifies an HID function within an attached USB device's descriptor walk.
Numbered from the USB-IF "Class Codes" registry and USB HID 1.11 sec 4.2 "Subclass". Subclass 1 = "Boot Interface Subclass", protocol 1 = keyboard, protocol 2 = mouse.
Definition at line 99 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_desc_t : uint8_t |
HID-specific descriptor types (USB HID 1.11 sec 7.1).
| Enumerator | |
|---|---|
| k_ra8_hhid_desc_hid | HID class descriptor. |
| k_ra8_hhid_desc_report | HID Report descriptor. |
| k_ra8_hhid_desc_physical | HID Physical descriptor. |
Definition at line 154 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_packet_t : uint16_t |
Packet sizing for the attached device's interrupt endpoints.
Per USB HID 1.11 sec 8.2 "Maximum Packet Size", a low- / full-speed HID interrupt endpoint is at most 64 bytes, and a high- speed one is at most 1024 bytes. Most keyboards / mice land at 8.
| Enumerator | |
|---|---|
| k_ra8_hhid_intr_max_packet_default | Boot-protocol default. |
| k_ra8_hhid_intr_max_packet_fs | FS ceiling. |
| k_ra8_hhid_intr_max_packet_hs | HS ceiling. |
Definition at line 84 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_pipe_t : uint8_t |
PIPE numbers used by the host-HID driver for the attached peripheral's interrupt endpoints.
FSP / RA8D2 PIPE assignment rules constrain interrupt pipes to PIPE6..PIPE9. The host-HID class only uses two pipes: an interrupt-IN pipe to drain input reports, and an optional interrupt-OUT pipe (used by some keyboards for LED state). See USB HID 1.11 sec 4.4 "Interrupt Pipes".
| Enumerator | |
|---|---|
| k_ra8_hhid_pipe_intr_in | PIPE6 -> attached EP intr IN. |
| k_ra8_hhid_pipe_intr_out | PIPE7 -> attached EP intr OUT. |
Definition at line 71 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_protocol_select_t : uint8_t |
wValue payload for SET_PROTOCOL.
Per USB HID 1.11 sec 7.2.6 "Set_Protocol Request". 0 = boot protocol, 1 = report protocol.
| Enumerator | |
|---|---|
| k_ra8_hhid_proto_boot | Boot protocol. |
| k_ra8_hhid_proto_report | Report protocol. |
Definition at line 145 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_report_buf_t : uint16_t |
Compile-time ceiling on the cached HID Report descriptor.
The HID spec puts an absolute ceiling at 65535 bytes (wDescriptorLength is 16-bit), but real-world HID descriptors are essentially always under 256 bytes. We pick a small-but-generous ceiling here so the starter doesn't carry a kilobyte of zeroes around.
| Enumerator | |
|---|---|
| k_ra8_hhid_report_desc_max | Cached Report desc max len. |
Definition at line 170 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_report_type_t : uint8_t |
HID report-type selector encoded in wValue's high byte for GET_REPORT / SET_REPORT.
Per USB HID 1.11 sec 7.2.1 "Get_Report Request".
| Enumerator | |
|---|---|
| k_ra8_hhid_report_type_input | Input report. |
| k_ra8_hhid_report_type_output | Output report. |
| k_ra8_hhid_report_type_feature | Feature report. |
Definition at line 132 of file ra8_usb_hhid.h.
| enum ra8_usb_hhid_request_t : uint8_t |
HID class-specific request codes the host issues to the attached device.
Per USB HID 1.11 sec 7.2 "Class-Specific Requests". Values match the standard HID class request register.
Definition at line 116 of file ra8_usb_hhid.h.
|
nodiscard |
Register (or detach) the attach callback.
The supplied callback fires exactly once per attach event, after the descriptor walk identifies an HID interface (class=0x03) and the matching interrupt-IN endpoint and HID class descriptor are cached. Pass NULL to detach.
| [in] | on_attach | Callback. NULL detaches. |
| [in] | ctx | Context pointer threaded back into on_attach. |
| k_ra8_ok | Callback installed. |
| k_ra8_err_invalid_state | Driver was never initialized. |
Definition at line 700 of file ra8_usb_hhid.c.
References k_ra8_err_invalid_state, k_ra8_ok, and s_state.
|
nodiscard |
Tear down the host-HID driver and release the controller.
| k_ra8_ok | Released. |
| k_ra8_err_invalid_state | Driver was never initialized. |
Definition at line 679 of file ra8_usb_hhid.c.
References k_ra8_err_invalid_state, k_ra8_hhid_step_idle, ra8_usb_host_deinit(), ra8_usb_host_set_uact(), and s_state.
|
nodiscard |
Drain the next input report from the interrupt-IN pipe.
Polling / non-blocking. Pulls bytes from the configured PIPE6 (interrupt IN) into out_buf. Returns k_ra8_err_no_data if the pipe has no bytes ready.
| [out] | out_buf | Destination buffer. |
| [in] | max_len | Capacity of out_buf, > 0. |
| [out] | got_len | Receives the number of bytes actually placed. |
| k_ra8_ok | Bytes drained; *got_len reflects the count. |
| k_ra8_err_no_data | Pipe was empty. |
| k_ra8_err_null_ptr | out_buf or got_len was NULL. |
| k_ra8_err_invalid_state | Driver not initialized, or no device attached. |
| k_ra8_err_invalid_arg | max_len == 0. |
Definition at line 961 of file ra8_usb_hhid.c.
References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhid_pipe_intr_in, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_usb_queue_out(), s_state, and s_tag.
|
nodiscard |
Issue GET_REPORT (USB HID 1.11 sec 7.2.1) over the DCP.
Builds an 8-byte SETUP packet with bmRequestType = 0xA1 (Class | Interface | Device-to-Host), bRequest = 0x01 (GET_REPORT), and wValue = (report_type << 8) | report_id. Hands it to ra8_usb_host_setup_request; the controller drives the data + status stages.
| [in] | target_report_type | Input / Output / Feature. |
| [in] | target_report_id | Report ID (0 if the device uses a single unnamed report). |
| [out] | out_buf | Destination buffer for the report payload. |
| [in] | max_len | Capacity of out_buf, > 0. |
| [out] | got_len | Receives the number of bytes actually received. |
| k_ra8_ok | Control transfer queued; on completion *got_len reflects the count. |
| k_ra8_err_null_ptr | out_buf or got_len was NULL. |
| k_ra8_err_invalid_state | Driver not initialized, or no device attached. |
| k_ra8_err_invalid_arg | Bogus target_report_type or max_len == 0. |
| k_ra8_err_busy | Controller busy with a prior SETUP. |
Definition at line 820 of file ra8_usb_hhid.c.
References internal_dcp_in_drain(), internal_pick_regs(), internal_report_type_ok(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhid_bm_class_iface_in, k_ra8_hhid_req_get_report, k_ra8_hhid_shift_byte1, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_usb_host_setup_request(), s_state, and s_tag.
|
nodiscard |
Bring up the host-HID driver on a chosen USB controller.
Initialises the underlying ra8_usb driver in HOST mode for speed, leaves the bus in the "wait for attach" state (UACT cleared), and arms the internal enumeration step machine.
| [in] | speed | Which USB controller (FS or HS). |
| k_ra8_ok | Host-HID ready, awaiting attach. |
| k_ra8_err_invalid_arg | speed out of range. |
| k_ra8_err_hw_init_failed | Underlying ra8_usb_host_init failed. |
Definition at line 656 of file ra8_usb_hhid.c.
References k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_hhid_step_idle, k_ra8_ok, k_ra8_usb_speed_fs, k_ra8_usb_speed_hs, ra8_log_error_val, ra8_log_info_val, ra8_usb_host_init(), s_state, and s_tag.
|
nodiscard |
Issue SET_IDLE (USB HID 1.11 sec 7.2.4) over the DCP.
Tells the device how often to silently re-send an unchanged input report. duration is in 4 ms units (0 = "only report on change"). Builds bmRequestType = 0x21, bRequest = 0x0A, wValue = (duration << 8) | report_id.
| [in] | duration | Idle rate, in 4 ms ticks (0..255). |
| [in] | report_id | Report ID, or 0 for "all reports". |
| k_ra8_ok | Control transfer queued. |
| k_ra8_err_invalid_state | Driver not initialized, or no device attached. |
| k_ra8_err_busy | Controller busy with a prior SETUP. |
Definition at line 910 of file ra8_usb_hhid.c.
References k_ra8_err_invalid_state, k_ra8_hhid_bm_class_iface_out, k_ra8_hhid_req_set_idle, k_ra8_hhid_shift_byte1, ra8_usb_host_setup_request(), and s_state.
|
nodiscard |
Issue SET_PROTOCOL (USB HID 1.11 sec 7.2.6) over the DCP.
Switches the device between boot protocol (wValue = 0) and report protocol (wValue = 1). Builds bmRequestType = 0x21, bRequest = 0x0B.
| [in] | boot_or_report | Boot or report protocol selector. |
| k_ra8_ok | Control transfer queued. |
| k_ra8_err_invalid_state | Driver not initialized, or no device attached. |
| k_ra8_err_invalid_arg | boot_or_report out of range. |
| k_ra8_err_busy | Controller busy with a prior SETUP. |
Definition at line 935 of file ra8_usb_hhid.c.
References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhid_bm_class_iface_out, k_ra8_hhid_proto_boot, k_ra8_hhid_proto_report, k_ra8_hhid_req_set_protocol, ra8_usb_host_setup_request(), and s_state.
|
nodiscard |
Issue SET_REPORT (USB HID 1.11 sec 7.2.2) over the DCP.
Builds an 8-byte SETUP packet with bmRequestType = 0x21 (Class | Interface | Host-to-Device), bRequest = 0x09 (SET_REPORT), and wValue = (report_type << 8) | report_id. The data stage payload is in_buf[0..len-1].
| [in] | target_report_type | Input / Output / Feature. |
| [in] | target_report_id | Report ID. |
| [in] | in_buf | Report payload. |
| [in] | len | Payload length. |
| k_ra8_ok | Control transfer queued. |
| k_ra8_err_null_ptr | in_buf was NULL with non-zero len. |
| k_ra8_err_invalid_state | Driver not initialized, or no device attached. |
| k_ra8_err_invalid_arg | Bogus target_report_type. |
| k_ra8_err_busy | Controller busy with a prior SETUP. |
Definition at line 870 of file ra8_usb_hhid.c.
References internal_report_type_ok(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_hhid_bm_class_iface_out, k_ra8_hhid_req_set_report, k_ra8_hhid_shift_byte1, ra8_usb_host_setup_request(), and s_state.
|
nodiscard |
Drive the enumeration step machine forward by one step.
Test / debug entry point. The production path drives this from the ra8_usb_dispatch callback when the controller fires a CTRT or BRDY interrupt; tests call it directly to walk the state machine deterministically.
| k_ra8_ok | Step advanced. |
| k_ra8_err_invalid_state | Driver not initialized. |
Definition at line 990 of file ra8_usb_hhid.c.
References internal_step_advance(), k_ra8_err_invalid_state, and s_state.