examples: fix echo example crash when UART interrupt handler placed in IRAM

Author: alisitsyn

examples/peripherals/uart/uart_echo/README.md

@@ -2,39 +2,51 @@
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 
-This example demonstrates how to utilize UART interfaces of ESP32 by echoing back to the sender any data received on
-UART1.
+This example demonstrates how to utilize UART interfaces by echoing back to the sender any data received on
+configured UART.
 
 ## How to use example
 
 ### Hardware Required
 
-The example can be run on any ESP32 development board connected to a PC with a single USB cable for flashing and
+The example can be run on any ESP32 or ESP32-S2 based development board connected to a PC with a single USB cable for flashing and
 monitoring. The external interface should have 3.3V outputs. You may use e.g. 3.3V compatible USB-to-Serial dongle.
 
 ### Setup the Hardware
 
-Connect the external serial interface to the ESP32 board as follows.
-
-  | ESP32 Interface | #define | ESP32 Pin | External UART Pin |
-  | --- | --- | --- | --- |
-  | Transmit Data (TxD) | ECHO_TEST_TXD | GPIO4 | RxD |
-  | Receive Data (RxD) | ECHO_TEST_RXD | GPIO5 | TxD |
-  | Ground | n/a | GND | GND |
+Connect the external serial interface to the ESP32(S2) board as follows.
+  
+```
+  ---------------------------------------------------------------------------------------
+  | Target chip Interface | #define          | Default ESP32(S2) Pin| External UART Pin |
+  | ----------------------|------------------|----------------------|--------------------
+  | Transmit Data (TxD)   | EXAMPLE_UART_TXD | GPIO4                | RxD               |
+  | Receive Data (RxD)    | EXAMPLE_UART_RXD | GPIO5                | TxD               |
+  | Ground                | n/a              | GND                  | GND               |
+  ---------------------------------------------------------------------------------------
+```
+Note: The GPIO22 - GPIO25 can not be used with ESP32-S2 chip because they are reserved for internal use. Please refer to UART documentation for selected target.
 
 Optionally, you can set-up and use a serial interface that has RTS and CTS signals in order to verify that the
 hardware control flow works. Connect the extra signals according to the following table, configure both extra pins in
 the example code by replacing existing `UART_PIN_NO_CHANGE` macros with the appropriate pin numbers and configure
 UART1 driver to use the hardware flow control by setting `.flow_ctrl = UART_HW_FLOWCTRL_CTS_RTS` and adding
 `.rx_flow_ctrl_thresh = 122`.
 
-  | ESP32 Interface | #define | ESP32 Pin | External UART Pin |
-  | --- | --- | --- | --- |
-  | Request to Send (RTS) | ECHO_TEST_RTS | GPIO18 | CTS |
-  | Clear to Send (CTS) | ECHO_TEST_CTS | GPIO19 | RTS |
+```
+  --------------------------------------------------------------------------------------
+  | Target chip Interface | #define         | Default ESP32(S2) Pin| External UART Pin |
+  | ----------------------|-----------------|----------------------|--------------------
+  | Transmit Data (TxD)   | ECHO_TEST_RTS   | GPIO18               | CTS               |
+  | Receive Data (RxD)    | ECHO_TEST_CTS   | GPIO19               | RTS               |
+  | Ground                | n/a             | GND                  | GND               |
+  --------------------------------------------------------------------------------------
+```
 
 ### Configure the project
 
+Use the command below to configure project using Kconfig menu as showed in the table above.
+The default Kconfig values can be changed such as: EXAMPLE_TASK_STACK_SIZE, EXAMPLE_UART_BAUD_RATE, EXAMPLE_UART_PORT_NUM (Refer to Kconfig file).
 ```
 idf.py menuconfig
 ```
@@ -54,10 +66,9 @@ See the Getting Started Guide for full steps to configure and use ESP-IDF to bui
 ## Example Output
 
 Type some characters in the terminal connected to the external serial interface. As result you should see echo in the
-terminal which is used for flashing and monitoring. You can verify if the echo indeed comes from ESP32 by
+terminal which is used for flashing and monitoring. You can verify if the echo indeed comes from ESP32(S2) board by
 disconnecting either `TxD` or `RxD` pin: no characters will appear when typing.
 
 ## Troubleshooting
 
-You are not supposed to see the echo in the terminal which is used for flashing and monitoring, but in the other one
-which is connected to UART1.
+You are not supposed to see the echo in the terminal which is used for flashing and monitoring, but in the other UART configured through Kconfig can be used.

examples/peripherals/uart/uart_echo/main/Kconfig.projbuild

@@ -0,0 +1,45 @@
+menu "Echo Example Configuration"
+
+    config EXAMPLE_UART_PORT_NUM
+        int "UART port number"
+        range 0 2 if IDF_TARGET_ESP32
+        range 0 1 if IDF_TARGET_ESP32S2
+        default 2 if IDF_TARGET_ESP32
+        default 1 if IDF_TARGET_ESP32S2
+        help
+            UART communication port number for the example.
+            See UART documentation for available port numbers.
+
+    config EXAMPLE_UART_BAUD_RATE
+        int "UART communication speed"
+        range 1200 115200
+        default 115200
+        help
+            UART communication speed for Modbus example.
+
+    config EXAMPLE_UART_RXD
+        int "UART RXD pin number"
+        range 0 34 if IDF_TARGET_ESP32
+        range 0 46 if IDF_TARGET_ESP32S2
+        default 5
+        help
+            GPIO number for UART RX pin. See UART documentation for more information
+            about available pin numbers for UART.
+
+    config EXAMPLE_UART_TXD
+        int "UART TXD pin number"
+        range 0 34 if IDF_TARGET_ESP32
+        range 0 46 if IDF_TARGET_ESP32S2
+        default 4
+        help
+            GPIO number for UART TX pin. See UART documentation for more information
+            about available pin numbers for UART.
+
+    config EXAMPLE_TASK_STACK_SIZE
+        int "UART echo example task stack size"
+        range 1024 16384
+        default 2048
+        help
+            Defines stack size for UART echo example. Insufficient stack size can cause crash.
+
+endmenu

examples/peripherals/uart/uart_echo/main/uart_echo_example_main.c

@@ -11,23 +11,28 @@
 #include "freertos/task.h"
 #include "driver/uart.h"
 #include "driver/gpio.h"
+#include "sdkconfig.h"
 
 /**
- * This is an example which echos any data it receives on UART1 back to the sender,
+ * This is an example which echos any data it receives on configured UART back to the sender,
  * with hardware flow control turned off. It does not use UART driver event queue.
  *
- * - Port: UART1
+ * - Port: configured UART
  * - Receive (Rx) buffer: on
  * - Transmit (Tx) buffer: off
  * - Flow control: off
  * - Event queue: off
- * - Pin assignment: see defines below
+ * - Pin assignment: see defines below (See Kconfig)
  */
 
-#define ECHO_TEST_TXD  (GPIO_NUM_4)
-#define ECHO_TEST_RXD  (GPIO_NUM_5)
-#define ECHO_TEST_RTS  (UART_PIN_NO_CHANGE)
-#define ECHO_TEST_CTS  (UART_PIN_NO_CHANGE)
+#define ECHO_TEST_TXD (CONFIG_EXAMPLE_UART_TXD)
+#define ECHO_TEST_RXD (CONFIG_EXAMPLE_UART_RXD)
+#define ECHO_TEST_RTS (UART_PIN_NO_CHANGE)
+#define ECHO_TEST_CTS (UART_PIN_NO_CHANGE)
+
+#define ECHO_UART_PORT_NUM      (CONFIG_EXAMPLE_UART_PORT_NUM)
+#define ECHO_UART_BAUD_RATE     (CONFIG_EXAMPLE_UART_BAUD_RATE)
+#define ECHO_TASK_STACK_SIZE    (CONFIG_EXAMPLE_TASK_STACK_SIZE)
 
 #define BUF_SIZE (1024)
 
@@ -36,29 +41,35 @@ static void echo_task(void *arg)
     /* Configure parameters of an UART driver,
      * communication pins and install the driver */
     uart_config_t uart_config = {
-        .baud_rate = 115200,
+        .baud_rate = ECHO_UART_BAUD_RATE,
         .data_bits = UART_DATA_8_BITS,
         .parity    = UART_PARITY_DISABLE,
         .stop_bits = UART_STOP_BITS_1,
         .flow_ctrl = UART_HW_FLOWCTRL_DISABLE,
         .source_clk = UART_SCLK_APB,
     };
-    uart_driver_install(UART_NUM_1, BUF_SIZE * 2, 0, 0, NULL, 0);
-    uart_param_config(UART_NUM_1, &uart_config);
-    uart_set_pin(UART_NUM_1, ECHO_TEST_TXD, ECHO_TEST_RXD, ECHO_TEST_RTS, ECHO_TEST_CTS);
+    int intr_alloc_flags = 0;
+
+#if CONFIG_UART_ISR_IN_IRAM
+    intr_alloc_flags = ESP_INTR_FLAG_IRAM;
+#endif
+
+    ESP_ERROR_CHECK(uart_driver_install(ECHO_UART_PORT_NUM, BUF_SIZE * 2, 0, 0, NULL, intr_alloc_flags));
+    ESP_ERROR_CHECK(uart_param_config(ECHO_UART_PORT_NUM, &uart_config));
+    ESP_ERROR_CHECK(uart_set_pin(ECHO_UART_PORT_NUM, ECHO_TEST_TXD, ECHO_TEST_RXD, ECHO_TEST_RTS, ECHO_TEST_CTS));
 
     // Configure a temporary buffer for the incoming data
     uint8_t *data = (uint8_t *) malloc(BUF_SIZE);
 
     while (1) {
         // Read data from the UART
-        int len = uart_read_bytes(UART_NUM_1, data, BUF_SIZE, 20 / portTICK_RATE_MS);
+        int len = uart_read_bytes(ECHO_UART_PORT_NUM, data, BUF_SIZE, 20 / portTICK_RATE_MS);
         // Write data back to the UART
-        uart_write_bytes(UART_NUM_1, (const char *) data, len);
+        uart_write_bytes(ECHO_UART_PORT_NUM, (const char *) data, len);
     }
 }
 
 void app_main(void)
 {
-    xTaskCreate(echo_task, "uart_echo_task", 1024, NULL, 10, NULL);
+    xTaskCreate(echo_task, "uart_echo_task", ECHO_TASK_STACK_SIZE, NULL, 10, NULL);
 }