improve flow

6 files changed, 34 insertions, 84 deletions

diff --git a/docs/explanation/architecture.rst b/docs/explanation/architecture.rst
index 4c63b198d..aa0c76128 100644
--- a/docs/explanation/architecture.rst
+++ b/docs/explanation/architecture.rst
@@ -12,10 +12,7 @@ Memory Safety
 
 TinyUSB is designed for resource-constrained embedded systems with strict memory requirements:
 
-- **No dynamic allocation**: All memory is statically allocated at compile time
-- **Bounded buffers**: All buffers have compile-time defined sizes
-- **Stack-based design**: No heap usage in the core stack
-- **Predictable memory usage**: Memory consumption is deterministic
+TinyUSB uses **no dynamic allocation** - all memory is statically allocated at compile time for predictability. All buffers have bounded, compile-time defined sizes to prevent overflow issues. The TinyUSB core avoids heap allocation, resulting in **predictable memory usage** where consumption is fully deterministic.
 
 Thread Safety
 -------------
@@ -54,7 +51,7 @@ TinyUSB follows a layered architecture from hardware to application:
    ├─────────────────────────────────────────┤
    │        Device/Host Stack Core           │ ← USB protocol handling
    ├─────────────────────────────────────────┤
-   │      Hardware Abstraction (DCD/HCD)    │ ← MCU-specific drivers
+   │      Hardware Abstraction (DCD/HCD)     │ ← MCU-specific drivers
    ├─────────────────────────────────────────┤
    │         OS Abstraction (OSAL)           │ ← RTOS integration
    ├─────────────────────────────────────────┤
@@ -79,6 +76,8 @@ Component Overview
 Device Stack Architecture
 =========================
 
+This section is concerned with the **Device Stack**, i.e., the component of TinyUSB used in USB devices (that talk to a USB host).
+
 Core Components
 ---------------
 
@@ -138,6 +137,8 @@ TinyUSB uses a deferred interrupt model for thread safety:
 Host Stack Architecture
 =======================
 
+This section is concerned with the **Host Stack**, i.e., the component of TinyUSB used in USB hosts, managing connected USB devices.
+
 Core Components
 ---------------
 
@@ -223,12 +224,7 @@ Memory Management
 Static Allocation Model
 -----------------------
 
-TinyUSB uses only static memory allocation:
-
-- **Endpoint Buffers**: Fixed-size buffers for each endpoint
-- **Class Buffers**: Static buffers for class-specific data
-- **Control Buffers**: Fixed buffer for control transfers
-- **Queue Buffers**: Static event queues
+TinyUSB uses only static memory allocation; it allocates fixed-size endpoint buffers for each configured endpoint, static buffers for class-specific data handling, a fixed buffer dedicated to control transfers, and static event queues for deferred interrupt processing.
 
 Buffer Management
 -----------------
@@ -254,12 +250,7 @@ Threading Model
 Task-Based Design
 -----------------
 
-TinyUSB uses a cooperative task model:
-
-- **Main Tasks**: ``tud_task()`` for device, ``tuh_task()`` for host
-- **Regular Execution**: Tasks must be called regularly (< 1ms typical)
-- **Event Processing**: All USB events processed in task context
-- **Callback Execution**: Application callbacks run in task context
+TinyUSB uses a cooperative task model; it provides main tasks - ``tud_task()`` for device and ``tuh_task()`` for host operation. These tasks must be called regularly (typically less than 1ms intervals) to ensure all USB events are processed in task context, where application callbacks also execute.
 
 RTOS Integration
 ----------------
diff --git a/docs/explanation/usb_concepts.rst b/docs/explanation/usb_concepts.rst
index e276b4c96..8b315aea2 100644
--- a/docs/explanation/usb_concepts.rst
+++ b/docs/explanation/usb_concepts.rst
@@ -134,27 +134,16 @@ Endpoint Basics
 Endpoint Configuration
 ----------------------
 
-Each endpoint is configured with:
-- **Transfer type**: Control, bulk, interrupt, or isochronous
-- **Direction**: IN, OUT, or bidirectional (control only)
-- **Maximum packet size**: Depends on USB speed and transfer type
-- **Interval**: For interrupt and isochronous endpoints
+Each endpoint is configured with a specific **transfer type** (control, bulk, interrupt, or isochronous), a **direction** (IN, OUT, or bidirectional for control only), a **maximum packet size** that depends on USB speed and transfer type, and an **interval** for interrupt and isochronous endpoints.
 
 **TinyUSB Configuration**: Endpoint characteristics are defined in descriptors (``usb_descriptors.c``) and automatically configured by the stack. Buffer sizes are set via ``CFG_TUD_*_EP_BUFSIZE`` macros.
 
 Error Handling and Flow Control
 -------------------------------
 
-**Transfer Results**: USB transfers can complete with different results:
-- **ACK**: Successful transfer
-- **NAK**: Device not ready (used for flow control)
-- **STALL**: Error condition or unsupported request
-- **Timeout**: Transfer failed to complete in time
+**Transfer Results**: USB transfers can complete with different results. An **ACK** indicates a successful transfer, while a **NAK** signals that the device is not ready (commonly used for flow control). A **STALL** response indicates an error condition or unsupported request, and **Timeout** occurs when a transfer fails to complete within the expected time frame.
 
-**Flow Control in USB**: Unlike network protocols, USB doesn't use congestion control. Instead:
-- Devices use NAK responses when not ready to receive data
-- Applications implement buffering and proper timing
-- Some classes (like CDC) support hardware flow control (RTS/CTS)
+**Flow Control in USB**: Unlike network protocols, USB doesn't use traditional congestion control. Instead, devices use NAK responses when not ready to receive data, applications implement buffering and proper timing strategies, and some classes (like CDC) support hardware flow control mechanisms such as RTS/CTS.
 
 **TinyUSB Handling**: Transfer results are represented as ``xfer_result_t`` enum values. The stack automatically handles NAK responses and timing. STALL conditions indicate application-level errors that should be addressed in class drivers.
 
@@ -278,11 +267,7 @@ Controller Fundamentals
 - Generate interrupts for USB events
 - Implement USB electrical specifications
 
-**Key Components**:
-- **Physical Layer**: USB signal drivers and receivers
-- **Protocol Engine**: Handles USB packets, ACK/NAK responses
-- **Endpoint Buffers**: Hardware FIFOs or RAM for data storage
-- **Interrupt Controller**: Generates events for software processing
+**Key Components**: USB controllers consist of several key components working together. The **Physical Layer** provides USB signal drivers and receivers for electrical interfacing. The **Protocol Engine** handles USB packets and ACK/NAK responses according to the USB specification. **Endpoint Buffers** provide hardware FIFOs or RAM for data storage during transfers. Finally, the **Interrupt Controller** generates events for software processing when USB activities occur.
 
 Controller Architecture Types
 -----------------------------
diff --git a/docs/reference/configuration.rst b/docs/reference/configuration.rst
index 79aeb15d8..fa0a874f5 100644
--- a/docs/reference/configuration.rst
+++ b/docs/reference/configuration.rst
@@ -173,15 +173,21 @@ Memory Management
 RTOS Configuration
 ------------------
 
-**FreeRTOS**:
+TinyUSB supports multiple operating systems through its OSAL (Operating System Abstraction Layer). Choose the appropriate configuration based on your target environment.
+
+**FreeRTOS Integration**:
+
+When using FreeRTOS, configure the task queue sizes to handle USB events efficiently:
 
 .. code-block:: c
 
    #define CFG_TUSB_OS                 OPT_OS_FREERTOS
-   #define CFG_TUD_TASK_QUEUE_SZ       16
-   #define CFG_TUH_TASK_QUEUE_SZ       16
+   #define CFG_TUD_TASK_QUEUE_SZ       16  // Device task queue size
+   #define CFG_TUH_TASK_QUEUE_SZ       16  // Host task queue size
+
+**RT-Thread Integration**:
 
-**RT-Thread**:
+RT-Thread requires only the OS selection, as it uses the RTOS's built-in primitives:
 
 .. code-block:: c
 
diff --git a/docs/reference/usb_classes.rst b/docs/reference/usb_classes.rst
index 00a251ffb..387587b48 100644
--- a/docs/reference/usb_classes.rst
+++ b/docs/reference/usb_classes.rst
@@ -268,10 +268,7 @@ Most classes require callback functions:
 Performance Considerations
 --------------------------
 
-- **Buffer Sizes**: Match endpoint buffer sizes to expected data rates
-- **Transfer Types**: Use appropriate USB transfer types (bulk, interrupt, isochronous)
-- **CPU Usage**: Minimize processing in interrupt context
-- **Memory Usage**: Static allocation only, no dynamic memory
+When implementing USB classes, match **buffer sizes** to expected data rates to avoid bottlenecks. Choose appropriate **transfer types** based on your application's requirements. Keep **callback processing** lightweight for optimal performance. Avoid **memory allocations in critical paths** where possible to maintain consistent performance.
 
 Testing and Validation
 ----------------------
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index 1f0f388df..e30210d01 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -177,11 +177,7 @@ Slow Transfer Speeds
 
 **Symptoms**: Lower than expected USB transfer rates
 
-*Causes and solutions*:
-- **Task scheduling**: Call ``tud_task()``/``tuh_task()`` more frequently
-- **Endpoint buffer sizes**: Increase buffer sizes for bulk transfers
-- **DMA usage**: Enable DMA for USB transfers if supported
-- **USB speed**: Use High Speed (480 Mbps) instead of Full Speed (12 Mbps)
+*Causes and solutions*: Improve **task scheduling** by calling ``tud_task()``/``tuh_task()`` more frequently to ensure timely USB event processing. Consider increasing **endpoint buffer sizes** for bulk transfers to reduce the frequency of small transfers. Enable **DMA usage** for USB transfers if your hardware supports it to offload CPU processing. Finally, use **High Speed** (480 Mbps) instead of Full Speed (12 Mbps) when possible to achieve better throughput.
 
 High CPU Usage
 --------------
@@ -194,34 +190,6 @@ High CPU Usage
 - Optimize descriptor parsing
 - Use DMA for data transfers
 
-Memory Issues
-=============
-
-Stack Overflow
---------------
-
-**Symptoms**: Hard faults, random crashes, especially during enumeration
-
-*Diagnosis*:
-- Build with ``DEBUG=1`` and use debugger
-- Check stack pointer before/after USB operations
-- Monitor stack usage with RTOS tools
-
-*Solutions*:
-- Increase stack size in linker script
-- Reduce local variable usage in callbacks
-- Use static buffers instead of large stack arrays
-
-Heap Issues
------------
-
-**Note**: TinyUSB doesn't use dynamic allocation, but your application might.
-
-*Check*:
-- Application code using malloc/free
-- RTOS heap usage
-- Third-party library allocations
-
 Hardware-Specific Issues
 ========================
 
@@ -246,10 +214,6 @@ RP2040 Issues
 - CPU overclocking may be needed for reliable operation
 - Timing-sensitive - avoid long interrupt disable periods
 
-**Flash/RAM constraints**:
-- Large USB applications may exceed RP2040 limits
-- Use code optimization and remove unused features
-
 ESP32 Issues
 ------------
 
@@ -273,6 +237,9 @@ For complex issues, hardware USB analyzers provide detailed protocol traces:
 Debugging with GDB
 ------------------
 
+Debugging with traditional debuggers is limited due to the real time nature of USB.
+However, especially for diagnosis of crashes, it can still be useful.
+
 .. code-block:: bash
 
    # Build with debug info
@@ -315,4 +282,4 @@ When reporting issues:
 **Resources**:
 - GitHub Discussions: https://github.com/hathach/tinyusb/discussions
 - Issue Tracker: https://github.com/hathach/tinyusb/issues
-- Documentation: https://docs.tinyusb.org
\ No newline at end of file
+- Documentation: https://docs.tinyusb.org
diff --git a/docs/tutorials/first_device.rst b/docs/tutorials/first_device.rst
index 9fac2df49..1b9ed5b0a 100644
--- a/docs/tutorials/first_device.rst
+++ b/docs/tutorials/first_device.rst
@@ -40,7 +40,7 @@ Key files in the example:
 * ``usb_descriptors.c`` - USB device descriptors
 * ``tusb_config.h`` - TinyUSB stack configuration
 
-**Main Loop Pattern**:
+The main loop follows a simple pattern that combines board initialization, TinyUSB initialization, and continuous task processing:
 
 .. code-block:: c
 
@@ -54,11 +54,13 @@ Key files in the example:
      }
    }
 
-**Device Task**: ``tud_task()`` must be called regularly to handle USB events and maintain the connection.
+The ``tud_task()`` function must be called regularly to handle USB events and maintain the connection with the host. This function processes all queued USB events and triggers appropriate callbacks in your application code.
 
 Step 3: Build and Test
 ======================
 
+With a clear understanding of the code structure, you're ready to build and test the example. This process involves fetching dependencies, compiling for your target board, and flashing the firmware:
+
 .. code-block:: bash
 
    # Fetch dependencies for your board family
@@ -78,6 +80,8 @@ Step 3: Build and Test
 Step 4: Customize for Your Needs
 =================================
 
+Once you have the basic example working, you can customize it for your specific application. The following modifications demonstrate common customization patterns.
+
 **Simplify to CDC-only**:
 
 1. In ``tusb_config.h``, disable MSC: