reduce code size, use state to replace active + pending

Author: hathach

.claude/commands/build-doc.md

@@ -0,0 +1,24 @@
+# build-doc
+
+Scan all example READMEs and build the Sphinx documentation.
+
+## Instructions
+
+1. Install docs dependencies:
+   ```bash
+   pip install -r docs/requirements.txt
+   ```
+
+2. Build the docs from the repo root:
+   ```bash
+   sphinx-build -b html docs docs/_build
+   ```
+   `conf.py` automatically scans all `examples/{device,host,dual}/*/README.md`, copies them into `docs/examples/`, and regenerates `examples.rst` with the toctree.
+
+3. Use a timeout of at least 60 seconds.
+
+4. After the build completes:
+   - Show the build output to the user.
+   - Report total warnings and errors.
+   - List which example READMEs were discovered and included.
+   - If there are errors, suggest fixes.

.claude/commands/hil.md

@@ -0,0 +1,30 @@
+# hil
+
+Run Hardware-in-the-Loop (HIL) tests on physical boards.
+
+## Arguments
+- $ARGUMENTS: Optional flags (e.g. board name, extra args). If empty, runs all boards with default config.
+
+## Instructions
+
+1. Determine the HIL config file:
+   ```bash
+   HIL_CONFIG=$( (systemctl list-units --type=service --state=running 2>/dev/null; systemctl --user list-units --type=service --state=running 2>/dev/null) | grep -q 'actions\.runner' && echo tinyusb.json || echo local.json )
+   ```
+   Default is `local.json` for local development.
+
+2. Parse $ARGUMENTS:
+   - If $ARGUMENTS contains `-b BOARD_NAME`, run for that specific board only.
+   - If $ARGUMENTS is empty or has no `-b`, run for all boards in the config.
+   - Pass through any other flags (e.g. `-v` for verbose) directly to the command.
+
+3. Run the HIL test from the repo root directory:
+   - Specific board: `python test/hil/hil_test.py -b BOARD_NAME -B examples $HIL_CONFIG $EXTRA_ARGS`
+   - All boards: `python test/hil/hil_test.py -B examples $HIL_CONFIG $EXTRA_ARGS`
+
+4. Use a timeout of at least 20 minutes (600000ms). HIL tests take 2-5 minutes. NEVER cancel early.
+
+5. After the test completes:
+   - Show the test output to the user.
+   - Summarize pass/fail results per board.
+   - If there are failures, suggest re-running with `-v` flag for verbose output to help debug.

examples/host/msc_file_explorer/README.md

@@ -0,0 +1,105 @@
+# MSC File Explorer
+
+This host example implements an interactive command-line file browser for USB Mass Storage devices.
+When a USB flash drive is connected, the device is automatically mounted using FatFS and a shell-like
+CLI is presented over the board's serial console.
+
+## Features
+
+- Automatic mount/unmount of USB storage devices
+- FAT12/16/32 filesystem support via FatFS
+- Interactive CLI with command history
+- Read speed benchmarking with `dd`
+- Support for up to 4 simultaneous USB storage devices (via hub)
+
+## Supported Commands
+
+| Command | Usage              | Description                                          |
+|---------|--------------------|------------------------------------------------------|
+| help    | `help`             | Print list of available commands                     |
+| cat     | `cat <file>`       | Print file contents to the console                   |
+| cd      | `cd <dir>`         | Change current working directory                     |
+| cp      | `cp <src> <dest>`  | Copy a file                                          |
+| dd      | `dd [count]`       | Read sectors and report speed (default 1024 sectors) |
+| ls      | `ls [dir]`         | List directory contents                              |
+| pwd     | `pwd`              | Print current working directory                      |
+| mkdir   | `mkdir <dir>`      | Create a directory                                   |
+| mv      | `mv <src> <dest>`  | Rename/move a file or directory                      |
+| rm      | `rm <file>`        | Remove a file                                        |
+
+## Build
+
+Build for a specific board using CMake (see [Getting Started](https://docs.tinyusb.org/en/latest/getting_started.html)):
+
+```bash
+# Example: build for Raspberry Pi Pico
+cmake -B build -DBOARD=raspberry_pi_pico -DFAMILY=rp2040 examples/host/msc_file_explorer
+cmake --build build
+```
+
+## Usage
+
+1. Flash the firmware to your board.
+2. Open a serial terminal (e.g. `minicom`, `screen`, `PuTTY`) at 115200 baud.
+3. Plug a USB flash drive into the board's USB host port.
+4. The device is auto-mounted and the prompt appears:
+
+```
+TinyUSB MSC File Explorer Example
+
+Device connected
+  Vendor  : Kingston
+  Product : DataTraveler 2.0
+  Rev     : 1.0
+  Capacity: 1.9 GB
+
+0:/> _
+```
+
+### Browsing Files
+
+```
+0:/> ls
+----a    1234  readme.txt
+d----       0  photos
+d----       0  docs
+
+0:/> cd photos
+0:/photos> ls
+----a  520432  vacation.jpg
+----a  312088  family.png
+
+0:/> cat readme.txt
+Hello from USB drive!
+```
+
+### Copying and Moving Files
+
+```
+0:/> cp readme.txt backup.txt
+0:/> mv backup.txt docs/backup.txt
+```
+
+### Measuring Read Speed
+
+```
+0:/> dd
+Reading 1024 sectors...
+  Data speed: 823 KB/s
+```
+
+### Multiple Devices
+
+When using a USB hub, multiple drives are mounted as `0:`, `1:`, etc. Use the drive prefix to
+navigate between them:
+
+```
+0:/> cd 1:
+1:/> ls
+```
+
+## Testing
+
+This example is part of the TinyUSB HIL (Hardware-in-the-Loop) test suite. The HIL test
+automatically flashes, runs the example, and verifies MSC enumeration and file operations
+against a known USB drive.

src/portable/raspberrypi/rp2040/dcd_rp2040.c

@@ -111,7 +111,6 @@ static void hw_endpoint_open(uint8_t ep_addr, uint16_t wMaxPacketSize, uint8_t t
     // double buffered Bulk endpoint
     if (transfer_type == TUSB_XFER_BULK) {
       size *= 2u;
-
   #if CFG_TUSB_RP2_ERRATA_E15
       if (dir == TUSB_DIR_IN) {
         ep->e15_bulk_in = true;
@@ -195,7 +194,7 @@ TU_ATTR_ALWAYS_INLINE static inline void reset_ep0(void) {
   for (uint8_t dir = 0; dir < 2; dir++) {
     struct hw_endpoint *ep = hw_endpoint_get(0, dir);
     ep->next_pid = 1u;
-    if (ep->active) {
+    if (ep->state == EPSTATE_ACTIVE) {
       hw_endpoint_abort_xfer(ep); // Abort any pending transfer per USB specs
     }
   }
@@ -254,12 +253,12 @@ static void __tusb_irq_path_func(dcd_rp2040_irq)(void) {
       struct hw_endpoint *ep = hw_endpoint_get(i, TUSB_DIR_IN);
 
       // Active Bulk IN endpoint requires SOF
-      if (ep->e15_bulk_in && ep->active) {
+      if (ep->e15_bulk_in && ep->state == EPSTATE_ACTIVE) {
         keep_sof_alive = true;
         hw_endpoint_lock_update(ep, 1);
 
-        if (ep->pending) {
-          ep->pending         = 0;
+        if (ep->state == EPSTATE_PENDING) {
+          ep->state = EPSTATE_ACTIVE;
 
           io_rw_32 *buf_reg32 = get_buf_ctrl(i, TUSB_DIR_IN);
           io_rw_16 *buf_reg16 = (io_rw_16 *)buf_reg32;
@@ -276,7 +275,7 @@ static void __tusb_irq_path_func(dcd_rp2040_irq)(void) {
           if (buf0_idle && buf1_idle) {
             // both are idle, start fresh
             io_rw_32 *ep_reg = get_ep_ctrl(i, TUSB_DIR_IN);
-            rp2usb_buffer_start(ep, ep_reg, buf_reg32, false, false);
+            rp2usb_buffer_start(ep, ep_reg, buf_reg32, false);
           } else if (buf0_idle) {
             uint16_t buf0 = bufctrl_prepare16(ep, ep->dpram_buf, false);
             bufctrl_write16(buf_reg16, buf0);
@@ -501,7 +500,7 @@ bool dcd_edpt_iso_activate(uint8_t rhport, const tusb_desc_endpoint_t *ep_desc)
   struct hw_endpoint *ep    = hw_endpoint_get(epnum, dir);
   TU_ASSERT(ep->dpram_buf != NULL); // must be inited and allocated previously
 
-  if (ep->active) {
+  if (ep->state == EPSTATE_ACTIVE) {
     hw_endpoint_abort_xfer(ep); // abort any pending transfer
   }
   ep->max_packet_size = ep_desc->wMaxPacketSize;