|
ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
|
Native USB host-side MSC (Mass Storage Class) polled enumeration ladder. More...
#include <stdint.h>#include "ra8_attributes.h"#include "ra8_check.h"#include "ra8_err.h"#include "ra8_hal_internal.h"#include "ra8_time.h"#include "ra8_usb.h"#include "ra8_usb_hmsc.h"#include "ra8_usb_hmsc_internal.h"Go to the source code of this file.
Functions | |
| static ra8_err_t | internal_enum_read_dev_desc (uint8_t *desc) |
| Read the 18-byte device descriptor over the polled control engine. | |
| static ra8_err_t | internal_enum_hunt (uint8_t *desc, uint8_t *out_addr) |
| Wait for a device to attach, then hunt for its address. | |
| static ra8_err_t | internal_enum_assign_addr (uint8_t *dev_addr) |
| Move the device to address 1 when it answered at the default. | |
| static void | internal_enum_note_endpoint (const uint8_t *d) |
| Record one bulk endpoint descriptor into the device snapshot. | |
| static bool | internal_enum_iface_is_msc (const uint8_t *d) |
| Test whether an interface descriptor is MSC SCSI Bulk-Only. | |
| static ra8_err_t | internal_enum_walk_cfg (const uint8_t *cfg, uint16_t len) |
| Walk a configuration blob for the MSC interface + bulk endpoints. | |
| static ra8_err_t | internal_enum_read_config (uint8_t *out_cfg_value) |
| Read + parse the configuration descriptor set. | |
| static ra8_err_t | internal_enum_configure (uint8_t dev_addr, uint8_t cfg_value) |
| SET_CONFIGURATION, best-effort GET_MAX_LUN, and pipe setup. | |
| static void | internal_enum_fill_ids (const uint8_t *desc) |
| Unpack VID/PID from a device descriptor into the snapshot. | |
| static void | internal_enum_publish (uint8_t dev_addr, ra8_usb_hmsc_device_t *out_device) |
| Publish a completed enumeration: snapshot, callback, out-copy. | |
| static ra8_err_t | internal_enum_ladder (uint8_t *out_addr) |
| Run the enumeration ladder: hunt, address, configure, pipes. | |
| ra8_err_t | ra8_usb_hmsc_enumerate (ra8_usb_hmsc_device_t *out_device) |
| Implementation of ra8_usb_hmsc_enumerate(). | |
Variables | |
| static const char * | s_tag = "USBHMSC" |
Native USB host-side MSC (Mass Storage Class) polled enumeration ladder.
Sibling translation unit of ra8_usb_hmsc.c, split out purely to satisfy the per-file size cap. Holds the hardware-proven polled enumeration ladder (ra8_usb_hmsc_enumerate) and its internal_enum_* helpers: wait for the D+ attach, hunt the (reset, address) combination the device answers on, assign address 1, read + parse the configuration descriptor set, run SET_CONFIGURATION / GET_MAX_LUN, program the bulk pipes, and fire the attach callback. Every chapter-9 SETUP goes through ra8_usb_host_setup_request.
The singleton shadow state (g_usb_hmsc_state) lives in ra8_usb_hmsc.c and is shared with this TU through ra8_hal_internal.h.
Definition in file ra8_usb_hmsc_enum.c.
| enum ra8_usb_hmsc_enum_tune_t : uint32_t |
Timing / retry tunables for the polled enumeration ladder.
| Enumerator | |
|---|---|
| k_ra8_hmsc_vbus_settle_ms | Supply settle before probing. |
| k_ra8_hmsc_attach_to_ms | Wait for the D+ pull-up. |
| k_ra8_hmsc_debounce_ms | Post-attach debounce (>=100 ms). |
| k_ra8_hmsc_reset_hold_ms | USB bus-reset hold (>=10 ms). |
| k_ra8_hmsc_recovery_ms | Post-reset recovery (TRSTRCY). |
| k_ra8_hmsc_addr_settle_ms | Post-SET_ADDRESS recovery. |
| k_ra8_hmsc_enum_tries | (reset? , addr) hunt attempts. |
| k_ra8_hmsc_no_reset_tries | Attempts before using bus reset. |
| k_ra8_hmsc_addr_alt_mask | Alternate addr 0..3 per attempt. |
| k_ra8_hmsc_cfg_buf_len | Full-configuration read buffer. |
| k_ra8_hmsc_attach_spin_limit | P10 iteration bound on the attach wait: the loop is primarily ms-bounded via ra8_time_ms, but if the tick is frozen (fake builds, SysTick masked) the spin cap guarantees termination. |
Definition at line 49 of file ra8_usb_hmsc_enum.c.
| enum ra8_usb_hmsc_walk_off_t : uint8_t |
Descriptor-walk byte offsets and identity codes.
Definition at line 70 of file ra8_usb_hmsc_enum.c.
|
static |
Move the device to address 1 when it answered at the default.
SET_CONFIGURATION is only legal from the Address state (sticks STALL it at the default address), so assign address 1, honour the set-address recovery, and retarget the DCP. Skipped when the hunt already found the device addressed.
| [in,out] | dev_addr | In: hunt result. Out: the operating address. |
| k_ra8_ok | The DCP targets the operating address. |
Definition at line 206 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, k_ra8_hmsc_addr_settle_ms, k_ra8_hmsc_assigned_address, k_ra8_hmsc_bm_std_dev_out, k_ra8_hmsc_breq_set_address, k_ra8_ok, ra8_delay_ms(), RA8_RETURN_ON_ERROR, ra8_usb_host_control_xfer(), ra8_usb_host_set_target(), and s_tag.
Referenced by internal_enum_ladder().
|
static |
SET_CONFIGURATION, best-effort GET_MAX_LUN, and pipe setup.
Activates the parsed configuration (strict status), issues the class GET_MAX_LUN (devices may STALL it, which legally means LUN 0, so failures default to 0), then programs the bulk pipes against the snapshot endpoints at dev_addr.
| [in] | dev_addr | Address the device answers at. |
| [in] | cfg_value | bConfigurationValue to activate. |
| k_ra8_ok | The device is configured and both pipes are ready. |
dev_addr. Definition at line 417 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, k_ra8_hmsc_bm_class_iface_in, k_ra8_hmsc_bm_std_dev_out, k_ra8_hmsc_breq_set_config, k_ra8_hmsc_get_max_lun_len, k_ra8_hmsc_pipe_bulk_in, k_ra8_hmsc_pipe_bulk_out, k_ra8_hmsc_req_get_max_lun, k_ra8_ok, RA8_RETURN_ON_ERROR, ra8_usb_host_control_xfer(), ra8_usb_host_pipe_setup(), and s_tag.
Referenced by internal_enum_ladder().
|
static |
Unpack VID/PID from a device descriptor into the snapshot.
Little-endian 16-bit fields at idVendor/idProduct.
| [in] | desc | Device descriptor bytes (18 valid bytes). |
desc is non-NULL and holds a device descriptor. desc is unmodified. Definition at line 477 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, k_ra8_hmsc_byte_bits, k_ra8_hmsc_off_dev_pid, and k_ra8_hmsc_off_dev_vid.
Referenced by internal_enum_ladder().
|
static |
Wait for a device to attach, then hunt for its address.
Waits for the D+ pull-up (LNST leaves SE0) plus the spec debounce, then tries each (reset?, address) combination: four gentle attempts at addresses 0..3 without touching the bus, then four more with a full bus reset (which also returns a previously addressed device to address 0). The first combination whose device-descriptor read returns all 18 bytes wins.
| [out] | desc | Receives the winning 18-byte device descriptor. |
| [out] | out_addr | Receives the address the device answered at. |
| k_ra8_ok | The device answered. |
| k_ra8_err_hw_timeout | Nothing attached / nothing answered. |
Definition at line 154 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, internal_enum_read_dev_desc(), k_ra8_err_hw_timeout, k_ra8_hmsc_addr_alt_mask, k_ra8_hmsc_attach_spin_limit, k_ra8_hmsc_attach_to_ms, k_ra8_hmsc_debounce_ms, k_ra8_hmsc_enum_tries, k_ra8_hmsc_no_reset_tries, k_ra8_hmsc_recovery_ms, k_ra8_hmsc_reset_hold_ms, k_ra8_hmsc_vbus_settle_ms, k_ra8_ok, 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 internal_enum_ladder().
|
static |
Test whether an interface descriptor is MSC SCSI Bulk-Only.
Matches class 0x08 (mass storage), subclass 0x06 (SCSI transparent), protocol 0x50 (Bulk-Only Transport) – the trio every consumer thumb drive reports.
| [in] | d | Interface descriptor bytes (9 valid bytes). |
| false | Any of the three class fields differs. |
d is non-NULL and points at an interface descriptor. d is unmodified. Definition at line 283 of file ra8_usb_hmsc_enum.c.
References k_ra8_hmsc_class_msc, k_ra8_hmsc_off_iface_class, k_ra8_hmsc_off_iface_proto, k_ra8_hmsc_off_iface_sub, k_ra8_hmsc_protocol_bbb, and k_ra8_hmsc_subclass_scsi.
Referenced by internal_enum_walk_cfg().
|
static |
Run the enumeration ladder: hunt, address, configure, pipes.
Waits for the attach, hunts the (reset, address) combination the device answers on, unpacks VID/PID, assigns address 1, parses + activates the configuration, and programs the bulk pipes.
| [out] | out_addr | Receives the address the device answers at. |
| k_ra8_ok | The device is configured and both pipes are ready. |
Definition at line 533 of file ra8_usb_hmsc_enum.c.
References internal_enum_assign_addr(), internal_enum_configure(), internal_enum_fill_ids(), internal_enum_hunt(), internal_enum_read_config(), k_ra8_hmsc_dev_desc_len, k_ra8_ok, RA8_RETURN_ON_ERROR, and s_tag.
Referenced by ra8_usb_hmsc_enumerate().
|
static |
Record one bulk endpoint descriptor into the device snapshot.
Filters for bmAttributes == bulk and slots the endpoint into the IN or OUT position (first match wins) with its wMaxPacketSize.
| [in] | d | Pointer to an endpoint descriptor. |
d points at a descriptor with bDescriptorType ENDPOINT. Definition at line 242 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, k_ra8_hmsc_byte_bits, k_ra8_hmsc_ep_attr_bulk, k_ra8_hmsc_ep_attr_mask, k_ra8_hmsc_ep_dir_in_bit, k_ra8_hmsc_ep_num_mask, k_ra8_hmsc_off_ep_addr, k_ra8_hmsc_off_ep_attr, and k_ra8_hmsc_off_ep_mps.
Referenced by internal_enum_walk_cfg().
|
static |
Publish a completed enumeration: snapshot, callback, out-copy.
Stores the address, flips the attached flag, fires the registered attach callback, and copies the snapshot to the caller.
| [in] | dev_addr | Address the device answers at. |
| [out] | out_device | Caller's snapshot copy (may be NULL). |
out_device is non-NULL. Definition at line 503 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state.
Referenced by ra8_usb_hmsc_enumerate().
|
static |
Read + parse the configuration descriptor set.
Reads the 9-byte header for wTotalLength + bConfigurationValue, re-reads the full set (clamped to the local buffer), and walks it for the MSC interface and bulk endpoints.
| [out] | out_cfg_value | Receives bConfigurationValue. |
| k_ra8_ok | The device snapshot carries the MSC endpoints. |
out_cfg_value is non-NULL. Definition at line 367 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, internal_enum_walk_cfg(), k_ra8_hmsc_bm_std_dev_in, k_ra8_hmsc_breq_get_descriptor, k_ra8_hmsc_byte_bits, k_ra8_hmsc_cfg_buf_len, k_ra8_hmsc_cfg_desc_len, k_ra8_hmsc_desc_configuration, k_ra8_hmsc_off_cfg_total, k_ra8_hmsc_off_cfg_value, RA8_RETURN_ON_ERROR, ra8_usb_host_control_xfer(), s_tag, and ra8_usb_setup_t::w_length.
Referenced by internal_enum_ladder().
|
static |
Read the 18-byte device descriptor over the polled control engine.
GET_DESCRIPTOR(DEVICE) at whatever address the DCP currently targets; requires the full 18 bytes back.
| [out] | desc | Receives the descriptor (18 bytes). |
| k_ra8_ok | All 18 bytes arrived. |
| k_ra8_err_hw_error | A short descriptor came back. |
desc holds at least 18 bytes. desc carries the device descriptor on success. Definition at line 109 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, k_ra8_err_hw_error, k_ra8_hmsc_bm_std_dev_in, k_ra8_hmsc_breq_get_descriptor, k_ra8_hmsc_byte_bits, k_ra8_hmsc_desc_device, k_ra8_hmsc_dev_desc_len, k_ra8_ok, RA8_RETURN_ON_ERROR, ra8_usb_host_control_xfer(), and s_tag.
Referenced by internal_enum_hunt().
|
static |
Walk a configuration blob for the MSC interface + bulk endpoints.
Strides descriptor-by-descriptor; an interface descriptor with class 0x08 / subclass 0x06 / protocol 0x50 opens the MSC scope, and the bulk endpoints inside it populate the device snapshot.
| [in] | cfg | Configuration descriptor bytes. |
| [in] | len | Valid byte count in cfg. |
| k_ra8_ok | Both bulk endpoints were found. |
| k_ra8_err_hw_error | No MSC bulk endpoint pair in the blob. |
cfg is non-NULL with len valid bytes. cfg is unmodified. Definition at line 317 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, internal_enum_iface_is_msc(), internal_enum_note_endpoint(), k_ra8_err_hw_error, k_ra8_hmsc_desc_endpoint, k_ra8_hmsc_desc_interface, k_ra8_hmsc_off_dlen, k_ra8_hmsc_off_dtype, k_ra8_hmsc_off_iface_num, and k_ra8_ok.
Referenced by internal_enum_read_config().
|
nodiscard |
Implementation of ra8_usb_hmsc_enumerate().
Enumerate the attached MSC device end to end (polled).
See the public header for the documented contract; runs the hardware-proven polled ladder: attach wait, (reset, address) hunt, address assignment, configuration parse + activate, GET_MAX_LUN, bulk pipe setup, then fires the attach callback.
| [out] | out_device | See header (may be NULL). |
| k_ra8_ok | Device enumerated; SCSI calls may follow. |
Definition at line 566 of file ra8_usb_hmsc_enum.c.
References g_usb_hmsc_state, internal_enum_ladder(), internal_enum_publish(), k_ra8_err_invalid_state, and k_ra8_ok.
Referenced by fileops_run_ladder(), microsd_host_enumerate(), mlun_host_enumerate(), ospirw_host_enumerate(), selftest_host_enumerate(), selftest_host_enumerate(), selftest_host_enumerate(), selftest_host_enumerate(), selftest_host_enumerate(), and wlun_host_enumerate().
|
static |
Definition at line 38 of file ra8_usb_hmsc_enum.c.