Merge branch 'sdio_st_9_nov' into 'master'

FG: STM32 SDIO ST See merge request app-frameworks/esp_hosted!268
espressif · Jan 2, 2023 · 21ff301 · 21ff301
2 parents 77b5195 + 4574a15
commit 21ff301
Show file tree

Hide file tree

Showing 54 changed files with 4,444 additions and 311 deletions.
diff --git a/esp_hosted_fg/README.md b/esp_hosted_fg/README.md
@@ -104,7 +104,7 @@ The below table explains which feature is supported on which transport interface
 
 | ESP device | Transport Interface | WLAN support | Virtual serial interface | Bluetooth support |
 |:------------:|:-------:|:---------:|:--------:|:--------:|
-| ESP32 | SDIO | No | No | No |
+| ESP32 | SDIO | Yes | Yes | BT/BLE 4.2\* |
 | ESP32 | SPI | Yes | Yes | BT/BLE 4.2\* |
 | ESP32 | UART | No | No | BT/BLE 4.2\*\* |
 | ESP32-S2 | SDIO | NA | NA | NA |

diff --git a/esp_hosted_fg/common/include/adapter.h b/esp_hosted_fg/common/include/adapter.h
@@ -53,6 +53,7 @@ typedef enum {
 	ESP_OPEN_DATA_PATH,
 	ESP_CLOSE_DATA_PATH,
 	ESP_RESET,
+	ESP_MAX_HOST_INTERRUPT,
 } ESP_HOST_INTERRUPT;
 
 

diff --git a/esp_hosted_fg/docs/MCU_based_host/Getting_started.md b/esp_hosted_fg/docs/MCU_based_host/Getting_started.md
@@ -1,6 +1,6 @@
-# Getting started with STM32F469I(MCU based Host)
+# Getting started with MCU based Host
 
-This section elaborates about setting up the control path, Wi-Fi connectivity and Bluetooth/BLE connectivity. Before proceeding, ensure pre-requisites [Hardware Setup and Compilation](MCU_based_readme.md#2-wi-fi-connectivity-setup-over-spi) are done.
+This section elaborates about setting up the control path, Wi-Fi connectivity and Bluetooth/BLE connectivity. Before proceeding, ensure pre-requisites [Hardware Setup and Compilation](MCU_based_readme.md#2-setup) are done.
 
 ## 1. Control Path
 
@@ -33,26 +33,41 @@ Host firmware provides Wi-Fi connectivity using control path and data path. Cont
 
 ### 2.1 Start Project with STM32
 
-We have tested project with STM32F469I-Discovery board. If other than STM32F469I-Discovery board is used, peripheral like SPI, USART need to change as per board needs. STM32CubeIDE would be needed to follow next steps.
+#### 2.1.1 Supported Hardware
+We have tested project for `SPI` transport with STM32F469I-Discovery board and `SDIO` transport with STM32F412ZGT6-Nucleo 144 board. If other than STM32F469I-Discovery board and STM32F412ZGT6-Nucleo 144 board are used, peripheral like SDIO, SPI, USART need to change as per board needs.
+
+| ESP32 Board | STM32 Board  | Transport  |
+|:---------:|:------:|:----------:|
+| ESP32 | STM32F412ZGT6-Nucleo 144  | SDIO |
+| ESP32/S2/S3/C2/C3 | STM32F469I-Discovery  | SPI |
+
+:warning: <code>**Note1:** For SDIO, please check [pull up requirements](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sd_pullup_requirements.html) while choosing ESP module</code>
+
+#### 2.1.2 STM32CubeIDE would be needed to follow next steps.
 
 * Create a workspace_directory outside of `ESP-Hosted` git cloned directory.
 * Browse and Open Workspace directory in STM32CubeIDE. It will take few seconds to open STM32CubeIDE.
-* From `Information Center` tab select `Start new project` from existing STM32CubeMX configuration file, i.e. ioc file option. It will take few seconds to open dialog box. In STM32CubeMX .ioc file field, choose appropriate .ioc file from `</path/to/esp_hosted>/esp_hosted_fg/host/stm32/proj/` directory.
+* From `Information Center` tab select `Start new project` from existing STM32CubeMX configuration file, i.e. ioc file option. It will take few seconds to open dialog box. In STM32CubeMX .ioc file field, choose appropriate .ioc file from `</path/to/esp_hosted>/esp_hosted_fg/host/stm32/proj/<transport>` directory.
+* For SPI transport:
 ```
 For ESP32 peripheral: Select stm_spi_host_v1.ioc file
 For ESP32-C2/ESP32-C3/ESP32-S2/ESP32-S3 peripheral: Select stm_spi_host_v2.ioc file
 ```
+* For SDIO transport:
+```
+For ESP32 peripheral: Select stm_sdio_host.ioc file
+```
 * Once file is selected, click `Open` and `Finish`. New dialog box will open as Open Associated Perspective, click on `Yes`. It may take 2-3 minutes to open.
 * Close ioc tab then close STM32CubeIDE and click on `exit`.
 * For Linux and Mac development hosts, In terminal, run
 ```
 $ cd </path/to/esp_hosted>/esp_hosted_fg/host/stm32/proj
-$ bash ./prepare_project.sh </path/to/workspace_directory>
+$ bash ./prepare_project.sh <transport> </path/to/workspace_directory>
 ```
 For Windows based systems, open "cmd.exe" or Windows Power Shell and run -
 ```
 > cd <path\to\esp_hosted>\esp_hosted_fg\host\stm32\proj
-> prepare_project.bat <path\to\workspace_directory>
+> prepare_project.bat <transport> <path\to\workspace_directory>
 ```
 This will copy the project configuration files into workspace_directory
 
@@ -67,7 +82,7 @@ $ minicom -D /dev/ttyACM0
 ```
 Note: /dev/ttyACM0 is used for For Linux, /dev/cu.usbmodemXXXXXX for Mac and COM port for Windows development host. Baud rate used is 115200. Parity bits configuration is 8N1.
 
-* In STM32CubeIDE, go to `Project Explorer`, right click on `stm_spi_host` project. Then `menu -> Run -> Run as -> STM32 Cortex-M C/C++ Application `. This will open Edit Configuration box, Click `OK`.
+* In STM32CubeIDE, go to `Project Explorer`, right click on `stm_<transport>_host` project. Then `menu -> Run -> Run as -> STM32 Cortex-M C/C++ Application `. This will open Edit Configuration box, Click `OK`.
 `Debug as` option can also be alternatively used if debugging is desired.
 
 Expected output on `Console` tab in STM32CubeIDE as follows:
@@ -138,7 +153,7 @@ started ESPWifi softAP
 
 ### 2.2 User configuration parameter
 
-Host firmware has basic user configuration parameters. User needs to manually configure these values. Click on `stm_spi_host` under `Project Explorer` tab. Then `menu -> Project -> Properties -> C/C++ Build -> Build Variables -> < select variable> -> Edit -> OK -> Apply`.
+Host firmware has basic user configuration parameters. User needs to manually configure these values. Click on `stm_<transport>_host` under `Project Explorer` tab. Then `menu -> Project -> Properties -> C/C++ Build -> Build Variables -> < select variable> -> Edit -> OK -> Apply`.
 
 Build Variables are as follows:
 
@@ -206,6 +221,10 @@ ARP response is triggered for requests received. You should be able see ARP resp
 XX bytes from 3c:71:bf:9a:bc:b8 (192.168.1.233): index=0 time=199.144 msec
 ```
 
+## 2.4 RAW throughput Testing :
+
+For raw throughput please check [Raw_TP_Testing.md](./Raw_TP_Testing.md)
+
 ## 3. BT/BLE connectivity
 Bluetooth and BLE handling could be easily ported. Porting details could be found at [ 1.5.2 MCU Host](../../README.md#152-mcu-host) on [README.md](../../README.md)
 

diff --git a/esp_hosted_fg/docs/MCU_based_host/MCU_based_architecture.md b/esp_hosted_fg/docs/MCU_based_host/MCU_based_architecture.md
@@ -7,11 +7,13 @@ Following diagram depicts building blocks of MCU based ESP-Hosted solution.
 ## 1. ESP Host Software
 The host software mainly consists of following building blocks.
 
-### 1.1 SPI Host Driver  
+### 1.1 SPI/SDIO Host Driver
 
-* ESP-Hosted solution provides thin SPI host interface layer which transmits/receives data from SPI hardware driver and makes it available to serial or network interface
+* ESP-Hosted solution provides thin SPI/SDIO host interface layer which transmits/receives data from SPI/SDIO hardware driver and makes it available to serial or network interface
 * Asynchrounous in nature, higher layers have flexibility to transmit and/or receive data as needed
-* Currently, Maximum 1600 bytes of data can be trasmitted in single transmit or receive transaction
+* Currently, Maximum bytes of data trasmitted in single transmit or receive transaction is as follows:
+	* SPI - 1600 bytes
+	* SDIO - 4096 bytes
 
 ---
 
@@ -35,15 +37,15 @@ The host software mainly consists of following building blocks.
 
 ### 1.4 Network interface layer [netif]  
 
-* This is an abstraction layer between SPI host driver and a network stack.
+* This is an abstraction layer between SDIO/SPI host driver and a network stack.
 * This gives flexibility of using any network stack with ESP-Hosted solution.
-* This interface layer defines set of APIs and data structure that network stack must implement in order to make it work with SPI host driver.
+* This interface layer defines set of APIs and data structure that network stack must implement in order to make it work with SDIO/SPI host driver.
 
 ---
 
 ### 1.5 Network stack stub  
 
-* This is a simple network stack stub which demonstrates how a network stack can implement network interface layer and work with SPI host driver.
+* This is a simple network stack stub which demonstrates how a network stack can implement network interface layer and work with SDIO/SPI host driver.
 * This does not represent actual network stack. This should be used as a reference for developing network interface layer [netif] provided by ESP-Hosted solution
 
 ---

diff --git a/esp_hosted_fg/docs/MCU_based_host/MCU_based_design.png b/esp_hosted_fg/docs/MCU_based_host/MCU_based_design.png
diff --git a/esp_hosted_fg/docs/MCU_based_host/MCU_based_readme.md b/esp_hosted_fg/docs/MCU_based_host/MCU_based_readme.md
@@ -1,4 +1,4 @@
-# Getting Started with MCU based host (STM32F469I)
+# Getting Started with MCU based host
 - Directory structure for microprocessor based host is explained [here](directory_structure.md)
 - Below diagram shows hardware and software block diagram for a typical MCU based system built with ESP-Hosted.
 
@@ -36,146 +36,21 @@ $ cd esp-hosted
 $ git submodule update --init --recursive
 ```
 
-# 2. Wi-Fi connectivity Setup over SPI
-## 2.1 Hardware Setup/Connections
-In this setup, ESP board acts as a SPI peripheral and provides Wi-Fi capabilities to host. Please connect ESP peripheral to STM32F469I board's CN12 Extension connecter with jumper cables as mentioned below. It may be good to use small length cables to ensure signal integrity.
-BT/BLE support will be added in upcoming release.
-Power ESP peripheral and STM32F469I separately with a power supply that provide sufficient power. ESP peripheral can be powered through PC using micro-USB cable. STM32 can be powered with mini-B cable. It is also used as USART connection for debug logs from host. Serial port communicaton program like tera term or minicom used to print the logs.
+# 2. Setup
 
+Prepare connections based on interface requirements and setup ESP peripheral as below.
 
-#### Hardware connections for ESP32
-| STM32 Pin | ESP32 Pin | Function |
-|:----------:|:---------:|:--------:|
-| PB4 (pin5) | IO19 | MISO |
-| PA5 (pin7) | IO18 | CLK  |
-| PB5 (pin9) | IO23 | MOSI |
-| PA15 (pin11) | IO5 | CS |
-| GND (pin2) | GND | GND |
-| PC6 (pin6) | IO2 | Handshake |
-| PC7 (pin8) | IO4 | Data Ready from ESP |
-| PB13 (pin10) | EN | Reset ESP |
+* **Wifi over SDIO on STM32F412ZGT6-Nucleo 144**
+	* Connection Setup
+		* Prepare connections as per section [1.1 Hardware Setup](SDIO_setup.md#11-hardware-setupconnections) of [SDIO setup document](SDIO_setup.md)
+	* ESP peripheral setup
+		* ESP peripheral setup as per section [2.2 ESP peripheral setup](SDIO_setup.md#22-setup) of [SDIO setup document](SDIO_setup.md)
 
-Setup image is here.
-
-![alt text](stm32_esp_setup.jpg "setup of STM32F469I as host and ESP32 as peripheral")
-
-#### Hardware connections for ESP32-S2
-| STM32 Pin | ESP32-S2 Pin | Function |
-|:---------:|:-----------:|:--------:|
-| PB4  (pin5) | IO13 | MISO |
-| PA5  (pin7) | IO12 | CLK |
-| PB5  (pin9) | IO11 | MOSI |
-| PA15 (pin11)| IO10 | CS |
-| GND  (pin2) | GND | GND |
-| PC6  (pin6) | IO2 | Handshake |
-| PC7  (pin8) | IO4 | Data ready from ESP |
-| PB13  (pin10) | RST | Reset ESP |
-
-Setup image is here.
-
-![alt text](stm_esp32_s2_setup.jpg "Setup of STM32F469I as host and ESP32-S2 as peripheral")
-
-#### Hardware connections for ESP32-C2
-| STM32 Pin | ESP32-C2 Pin | Function |
-|:---------:|:-----------:|:--------:|
-| PB4  (pin5) | IO02 | MISO |
-| PA5  (pin7) | IO06 | CLK |
-| PB5  (pin9) | IO07 | MOSI |
-| PA15 (pin11)| IO10 | CS |
-| GND  (pin2) | GND | GND |
-| PC6  (pin6) | IO03 | Handshake |
-| PC7  (pin8) | IO04 | Data ready from ESP |
-| PB13  (pin10) | RST | Reset ESP |
-
-Setup image is here.
-
-![alt text](stm_esp32_c2_setup.png "Setup of STM32F469I as host and ESP32-C2 as peripheral")
-
-#### Hardware connections for ESP32-C3
-| STM32 Pin | ESP32-C3 Pin | Function |
-|:---------:|:-----------:|:--------:|
-| PB4  (pin5) | IO02 | MISO |
-| PA5  (pin7) | IO06 | CLK |
-| PB5  (pin9) | IO07 | MOSI |
-| PA15 (pin11)| IO10 | CS |
-| GND  (pin2) | GND | GND |
-| PC6  (pin6) | IO03 | Handshake |
-| PC7  (pin8) | IO04 | Data ready from ESP |
-| PB13  (pin10) | RST | Reset ESP |
-
-Setup image is here.
-
-![alt text](stm_esp32_c3_setup.jpg "Setup of STM32F469I as host and ESP32-C3 as peripheral")
-
-#### Hardware connections for ESP32-S3
-| STM32 Pin | ESP32-S3 Pin | Function |
-|:---------:|:-----------:|:--------:|
-| PB4  (pin5) | IO13 | MISO |
-| PA5  (pin7) | IO12 | CLK |
-| PB5  (pin9) | IO11 | MOSI |
-| PA15 (pin11)| IO10 | CS |
-| GND  (pin2) | GND | GND |
-| PC6  (pin6) | IO02 | Handshake |
-| PC7  (pin8) | IO04 | Data ready from ESP |
-| PB13  (pin10) | RST | Reset ESP |
-
-Setup image is here.
-
-![alt text](stm_esp32_s3_setup.jpg "Setup of STM32F469I as host and ESP32-S3 as peripheral")
-
-# 2. ESP peripheral setup
-## 2.1 ESP-IDF requirement
-:warning:`Note: ESP-IDF is needed to compile ESP-Hosted firmware source. Skip this step if you are planning to use pre-built release binaries.`
-
-- Clone the ESP-IDF [release/v5.0](https://github.com/espressif/esp-idf/tree/release/v5.0)  and checkout to `release/v5.0` branch.
-- The control path between MCU host and ESP peripheral is based on `protobuf`. For that, corresponding stack layer, `protocomm` from ESP-IDF is used. It will be already present in ESP-IDF, no extra setup required for that.
-
-### 2.2 Setup
-#### 2.2.1 Using pre-built binary
-* Download pre-built firmware binaries from [releases](https://github.com/espressif/esp-hosted/releases)
-* Follow `readme.txt` from release tarball to flash the ESP binary
-* :warning: Make sure that you use `Source code (zip)` in `Assets` fold with associated release for host building.
-* Windows user can use ESP Flash Programming Tool to flash the pre-built binary.
-
-#### 2.2.2 Compilation using source
-
-- Note: Please use the same git commit both at ESP and Host
-- Clone the ESP-IDF [release/v5.0](https://github.com/espressif/esp-idf/tree/release/v5.0) and git checkout to `release/v5.0` branch.
-- [Set-up the ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/release-v5.0/esp32/get-started/index.html)
-- Navigate to `esp_hosted_fg/esp/esp_driver/network_adapter` directory.
-
-##### Using cmake
-
-```
-$ idf.py fullclean
-```
-:warning: Skip this step for ESP32. Run for ESP32-S2 / ESP32-C2 / ESP32-C3
-```
-$ idf.py set-target esp32s2
-```
-or
-```
-$ idf.py set-target esp32c2
-```
-or
-```
-$ idf.py set-target esp32c3
-```
-
-Run following command and navigate to `Example Configuration -> Transport layer -> SPI interface -> select` and exit from menuconfig. Read more about [idf.py](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/build-system.html#using-the-build-system) here.
-```
-$ idf.py menuconfig
-```
-
-:warning: Skip below step for ESP32-S2 / ESP32-C2 / ESP32-C3. Run for  ESP32 only.
-
-Change SPI controller to VSPI. Please navigate to `Example Configuration → SPI Configuration` and change value of `SPI controller to use` to `3`
-
-To build and flash the app on ESP peripheral, run
-
-```sh
-$ idf.py -p <serial_port> build flash
-```
+* **Wifi over SPI on STM32F469I-Discovery**
+	* Connection Setup
+		* Prepare connections as per section [1.1 Hardware Setup](SPI_setup.md#11-hardware-setupconnections) of [SPI Setup document](SPI_setup.md)
+	* ESP peripheral setup
+		* ESP peripheral setup as per section [2.2 ESP peripheral setup](SPI_setup.md#22-setup) of [SPI setup document](SPI_setup.md)
 
 # 3. ESP-Hosted Usage Guide
 Following guide explains how to use ESP-Hosted soultion with MCU based platform.

diff --git a/esp_hosted_fg/docs/MCU_based_host/Raw_TP_Testing.md b/esp_hosted_fg/docs/MCU_based_host/Raw_TP_Testing.md
@@ -0,0 +1,34 @@
+# Raw Throughput testing
+
+- This is the optional feature to test throughput over required transport layer (SPI or SDIO).
+- When ENABLED, this will bypass Wi-Fi traffic and push the dummy data traffic on transport layer directly to check maximum throughput on the current transport.
+- This feature will also help you to check if transport layer is properly configured or not.
+- This requires ESP firmware to be manually flashed with below steps.
+
+## Steps to test Raw TP
+
+- On Host side:
+    1. Go to `esp_hosted_fg/host/stm32/common/stats.h`
+	2. Enable raw throughput tetsing feature by making `TEST_RAW_TP` value to `1`.
+	3. There are two directions to test raw throughput and at a time, throughput can be tested only in one direction (simplex).
+	    - ESP to Host : For this, make `TEST_RAW_TP__ESP_TO_HOST` value to 1
+	    - Host to ESP : For this, make `TEST_RAW_TP__ESP_TO_HOST` value to 0
+	4. Build and flash ESP firmware again.
+
+- On ESP side:
+	1. Go to `esp_hosted_fg/esp/esp_driver/network_adapter/main/stats.h`
+	2. Enable raw throughput tetsing feature by making `TEST_RAW_TP` value to `1`.
+	3. There are two directions to test raw throughput and at a time, throughput can be tested only in one direction (simplex).
+	    - ESP to Host : For this, make `TEST_RAW_TP__ESP_TO_HOST` value to 1
+	    - Host to ESP : For this, make `TEST_RAW_TP__ESP_TO_HOST` value to 0
+	4. Build and flash ESP firmware again.
+
+**Note**
+Please revert these configurations once raw throughput testing is done
+
+## Raw Throughput Numbers
+
+| ESP32 Board | STM32 Board  | Transport  | TX case | RX case |
+|:---------:|:------:|:----------:|:---:|:--:|
+| ESP32 | STM32F412ZGT6-Nucleo 144  | SDIO | 5.22 Mbps | 5.32 Mbps |
+| ESP32/ESP32S2/ESP32S3/ESP32C2/ESP32C3 | STM32F469I-Discovery  | SPI | 2.88 Mbps | 2.28 Mbps |
diff --git a/esp_hosted_fg/docs/MCU_based_host/SDIO_setup.md b/esp_hosted_fg/docs/MCU_based_host/SDIO_setup.md
@@ -0,0 +1,60 @@
+# Wi-Fi connectivity Setup over SDIO
+## 1. Setup
+### 1.1 Hardware Setup/Connections
+* In this setup, ESP board acts as a SDIO peripheral and provides Wi-Fi capabilities to host. Please connect ESP peripheral to STM32F412ZGT6-Nucleo 144 board's CN8 Extension connecter with jumper cables as mentioned below. It may be good to use small length cables to ensure signal integrity.
+* Power ESP peripheral and STM32F412ZGT6-Nucleo 144 separately with a power supply that provide sufficient power. ESP peripheral and STM32 can be powered through USB-Hub using micro-USB cable. It is also used as USART connection for debug logs from host. Serial port communicaton program like tera term or minicom used to print the logs.
+* BT/BLE support will be added in upcoming release.
+
+#### Hardware connections for ESP32
+| STM32 Pin | ESP32 Pin | Function |
+|:----------:|:---------:|:--------:|
+| PC8 (pin2) | IO2 | DATA0 |
+| PC9 (pin4) | IO4 | DATA1 |
+| PC10 (pin6) | IO12 | DATA2 |
+| PC11 (pin8) | IO13 | DATA3 |
+| PC12 (pin10)| IO14 | Clock |
+| PD2 (pin12) | IO15 | Command |
+| GND (pin13) | GND | Ground |
+| PG2 (pin14) | EN | Reset ESP |
+
+Setup image is here.
+
+![alt text](stm32_esp32_sdio_setup.jpg "setup of STM32F412ZGT6-Nucleo 144 as host and ESP32 as peripheral")
+
+# 2. ESP peripheral setup
+## 2.1 ESP-IDF requirement
+:warning:`Note: ESP-IDF is needed to compile ESP-Hosted firmware source. Skip this step if you are planning to use pre-built release binaries.`
+
+- Clone the ESP-IDF [release/v5.0](https://github.com/espressif/esp-idf/tree/release/v5.0)  and checkout to `release/v5.0` branch.
+- The control path between MCU host and ESP peripheral is based on `protobuf`. For that, corresponding stack layer, `protocomm` from ESP-IDF is used. It will be already present in ESP-IDF, no extra setup required for that.
+
+### 2.2 Setup
+#### 2.2.1 Using pre-built binary
+* Download pre-built firmware binaries from [releases](https://github.com/espressif/esp-hosted/releases)
+* Follow `readme.txt` from release tarball to flash the ESP binary
+* :warning: Make sure that you use `Source code (zip)` in `Assets` fold with associated release for host building.
+* Windows user can use ESP Flash Programming Tool to flash the pre-built binary.
+
+#### 2.2.2 Compilation using source
+
+- Note: Please use the same git commit both at ESP and Host
+- Clone the ESP-IDF [release/v5.0](https://github.com/espressif/esp-idf/tree/release/v5.0) and git checkout to `release/v5.0` branch.
+- [Set-up the ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/release-v5.0/esp32/get-started/index.html)
+- Navigate to `esp_hosted_fg/esp/esp_driver/network_adapter` directory.
+
+##### Using cmake
+
+```
+$ idf.py fullclean
+```
+
+Run following command and navigate to `Example Configuration -> Transport layer -> SDIO interface -> select` and exit from menuconfig. Read more about [idf.py](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/build-system.html#using-the-build-system) here.
+```
+$ idf.py menuconfig
+```
+
+To build and flash the app on ESP peripheral, run
+
+```sh
+$ idf.py -p <serial_port> build flash
+```