Merge pull request #1 from schkovich/pico-sdk-2.2.0-update

Having `LIB_PICO_MULTICORE` enabled by default, and issues raspberrypi/pico-sdk#2527 and raspberrypi/pico-sdk#2433 allowed setting the schkovich/async-tcp@f8eba15 library as a submodule.

Author: schkovich

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "lib/async-tcp"]
+	path = lib/async-tcp
+	url = [email protected]:schkovich/async-tcp.git

README.md

@@ -1,59 +1,50 @@
-# Development Setup Guide
+# async-tcp-tests
 
-This project uses arduino-pico core for debugging RP2040-based Arduino Pico programs with local modifications.
+This repository was initially set as a testbed for debugging and validating fixes for two bugs in the Raspberry Pi Pico SDK. Over time, it evolved into a dedicated environment for developing and testing the async-tcp library.
 
-## Prerequisites
+## Current Purpose
 
-- [Arduino Pico](https://github.com/earlephilhower/arduino-pico) core
-- [PlatformIO](https://platformio.org/)
-- CMSIS-DAP compatible debug probe
+The repository is now focused on testing and demonstrating the async-tcp library, which provides an event-driven, thread-safe TCP client abstraction for the RP2040 platform using async_context and lwIP.
 
-## Setup Process
+## Quick Start
 
-1. Clone those repositories:
-```bash
-git clone https://github.com/schkovich/arduino-pico.git 
-cd arduino-pico
-git checkout execute_sync_2433
-git submodule update --init
-cd ..
-git clone [email protected]:schkovich/pico-sdk-tests.git
-cd pico-sdk-tests
-```
+To evaluate or build this project:
 
-## Project Structure
-```plaintext
+1. **Clone this repository:**
 
-├── arduino-pico # Forked arduino-pico core
-├── pico-sdk-tests
-│   ├── lib
-│   ├── .pio # PlatformIO build directory
-│   ├── scripts # Debug scripts
-│   └── src
-```
+   ```sh
+   git clone https://github.com/schkovich/async-tcp-tests.git
+   cd async-tcp-tests
+   ```
 
-## Project configuration
-The arduino-pico core is configured in [platformio.ini](https://docs.platformio.org/en/latest/projectconf/index.html#platformio-ini-project-configuration-file) via [platform_package](https://docs.platformio.org/en/latest/projectconf/sections/env/options/platform/platform_packages.html#platform-packages) option, pointing to the [local folder](https://docs.platformio.org/en/latest/core/userguide/pkg/cmd_install.html#local-folder) and “Symbolic Link” feature:
-```ini
-[env:debug]
-board = nanorp2040connect
-framework = arduino
-platform = https://github.com/maxgerhardt/platform-raspberrypi.git
-board_build.core = earlephilhower
-platform_packages =
-    framework-arduinopico@symlink://../arduino-pico
-```
-## Building Core Components
-The pico-sdk build process:
+2. **Initialise and update submodules:**
+
+   ```sh
+   git submodule update --init --recursive
+   ```
 
-1. Compiles core SDK libraries
-2. Generates boot stage 2 code for different flash chips
-3. Produces required build artifacts for both RP2040 and RP2350
+3. **Build and monitor with PlatformIO:**
 
-For detailed build steps, see [make-libpico.sh](https://github.com/schkovich/arduino-pico/blob/execute-sync%407c51742/tools/libpico/make-libpico.sh) in the arduino-pico core.
+   ```sh
+   pio run
+   pio device monitor
+   ```
+
+   For instructions on using async-tcp in a new project, see the [async-tcp README](lib/async-tcp/README.md).
+
+## Project Structure
+
+```plaintext
+├── lib
+│   └── async-tcp    # async-tcp library as a submodule
+├── scripts          # Debug scripts
+├── src              # Application source code
+└── docs             # Documentation
+```
 
-### Development Workflow
+## Notes
+- The repo was formerly named `pico-sdk-tests`.
+- The original pico-sdk bugfixes are now upstream and no longer require local patching.
+- The async-tcp library is under active development and testing here.
 
-- Pico SDK and async_context are pre-built statically linked to the project
-- The project is built using [PlatformIO](https://docs.platformio.org/en/latest/core/index.html)
-- Debug using CMSIS-DAP probe
+For more details, see The [Application Workflow](docs/workflow.md).

docs/WriteEvents.puml

@@ -0,0 +1,31 @@
+@startuml Write Events Flow
+
+participant "App Code\n(Core 0)" as App
+participant "TcpClient" as Client
+participant "TcpWriteHandler\n(EventBridge)" as Handler
+participant "async_context\n(Core 0)" as Context
+participant "TcpClientContext" as TcpCtx
+participant "lwIP TCP" as TCP
+participant "Network" as Net
+
+== Write Request ==
+App -> Client: write_async(data, size)
+Client -> Handler: enqueue_write(data, size)
+Handler -> Context: run() [schedule onWork()]
+Context -> Handler: onWork()
+Handler -> TcpCtx: write(data, size)
+TcpCtx -> TCP: tcp_write()
+TCP -> Net: send packet
+
+== ACK Reception ==
+Net -> TCP: ACK received
+TCP -> TcpCtx: _acked(len)
+TcpCtx -> Handler: on_ack_received(len)
+Handler -> Context: run() [schedule onWork()]
+Context -> Handler: onWork()
+
+alt More data to send
+    Handler -> TcpCtx: write(remaining_data)
+    TcpCtx -> TCP: tcp_write()
+    TCP -> Net: send next chunk
+@enduml

docs/uar-2433-log-analysis.md

@@ -3,15 +3,17 @@
 ## Memory Layout Context
 
 ### RP2040 Stack Configuration
+
 - Each Cortex M0+ core has its own stack
 - Stacks grow downward from high to low addresses
 - Default configuration:
-  - Single core: 8KB stack for core 0
-  - Dual core: 4KB per core (shared from same 8KB)
-  - Stacks placed in separate scratch banks (X/Y) for performance
+    - Single core: 8KB stack for core 0
+    - Dual core: 4KB per core (shared from same 8KB)
+    - Stacks placed in separate scratch banks (X/Y) for performance
 - In our case: `bool core1_separate_stack = true;` gives each core 8KB
 
 ### Stack Usage Analysis
+
 - Worker struct allocated at 0x20041f74
 - Printf buffer pushing against worker memory
 - Critical 48-byte alignment causing corruption
@@ -20,13 +22,15 @@
 ## Debugging Setup
 
 ### 1. Timestamp Collection
+
 ```cpp
 timestamp_enter = to_us_since_boot(get_absolute_time());
 const auto rc = async_context_execute_sync(&async_ctx.core, do_some_work, &ref_counter);
 timestamp_exit = to_us_since_boot(get_absolute_time());
 ```
 
 ### 2. GDB Instrumentation
+
 ```gdb
 break async_context_base_execute_once
 commands
@@ -46,6 +50,7 @@ end
 ## Findings
 
 ### 1. Stack Memory Pattern
+
 ```
 0x20041f74 (Worker struct location):
 |-------------------|
@@ -61,6 +66,7 @@ Printf buffer (grows down)
 ```
 
 ### 2. Serial Output and Memory Impact
+
 ```
 // String lengths affecting stack layout
 Cycle 9:  "Counter 9; ..."    // 47 chars, stack safe
@@ -69,6 +75,7 @@ Cycle 11: "[Counter 11]..."   // 48 chars, fatal alignment
 ```
 
 ### 3. Memory Corruption Pattern
+
 ```
 Initial state (cycle 1):
 - work_pending corrupted (1->232)
@@ -83,15 +90,17 @@ Fatal state (cycle 11):
 ```
 
 ### 4. Stack Layout Analysis
+
 - Worker struct (16 bytes) at 0x20041f74
 - Printf buffer allocated above worker
 - 48-byte boundary critical because:
-  1. Stack is 8-byte aligned
-  2. Printf buffer rounded up for alignment
-  3. Counter digits affect buffer size
-  4. At 48 bytes, buffer end perfectly aligns with worker start
+    1. Stack is 8-byte aligned
+    2. Printf buffer rounded up for alignment
+    3. Counter digits affect buffer size
+    4. At 48 bytes, buffer end perfectly aligns with worker start
 
 ### 5. Crash Analysis
+
 ```asm
 // Fatal access in async_context_base_execute_once during list traversal:
 0x1000a7be: ldr r3, [r5, #4]  // Try to read next field from corrupted worker (0xa)
@@ -108,21 +117,23 @@ r0 = 0x20001560 // async_context pointer
 ```
 
 ## Key Insights
+
 1. Stack Layout Significance:
-   - 8KB per core (due to core1_separate_stack = true)
-   - Stack alignment requirements affect corruption pattern
-   - Worker struct position relative to printf buffer critical
+    - 8KB per core (due to core1_separate_stack = true)
+    - Stack alignment requirements affect corruption pattern
+    - Worker struct position relative to printf buffer critical
 
 2. UAR Manifestation:
-   - work_pending corrupted to 232 immediately (early warning)
-   - next field corrupted to 0xa when string hits 48 bytes
-   - Crash happens when trying to traverse corrupted linked list
-   - Fatal because of invalid memory access (0xa is not a valid address)
+    - work_pending corrupted to 232 immediately (early warning)
+    - next field corrupted to 0xa when string hits 48 bytes
+    - Crash happens when trying to traverse corrupted linked list
+    - Fatal because of invalid memory access (0xa is not a valid address)
 
 3. Corruption Chain:
-   - Printf buffer (48 bytes) overwrites worker struct
-   - Worker still in linked list but memory reused
-   - Next traversal attempts to dereference 0xa
-   - System crashes trying to read from invalid address
+    - Printf buffer (48 bytes) overwrites worker struct
+    - Worker still in linked list but memory reused
+    - Next traversal attempts to dereference 0xa
+    - System crashes trying to read from invalid address
 
-This analysis shows how a stack-based UAR vulnerability manifests through linked list corruption, where the crash occurs during list traversal rather than during worker execution.
+This analysis shows how a stack-based UAR vulnerability manifests through linked list corruption, where the crash occurs
+during list traversal rather than during worker execution.