Commit 09cca381 authored by Almir Okato's avatar Almir Okato Committed by Gustavo Henrique Nihei
Browse files

boot_serial: espressif: ESP32-C3 serial recovery mode 



Signed-off-by: default avatarAlmir Okato <almir.okato@espressif.com>
parent 707a69d4

boot/espressif/hal/src/esp32c3/bootloader_init.c

+17 −8
Original line number Diff line number Diff line
@@ -19,6 +19,7 @@ 


#include "bootloader_init.h"

#include "bootloader_common.h"

#include "bootloader_console.h"

#include "bootloader_clock.h"

#include "bootloader_flash_config.h"

#include "bootloader_mem.h"
@@ -31,6 +32,10 @@ 
#include "soc/efuse_reg.h"

#include "soc/rtc.h"



#include "hal/gpio_hal.h"

#include <hal/gpio_ll.h>

#include <hal/uart_ll.h>



#include "esp32c3/rom/cache.h"

#include "esp32c3/rom/spi_flash.h"
@@ -39,6 +44,12 @@ 


extern esp_image_header_t WORD_ALIGNED_ATTR bootloader_image_hdr;



#if CONFIG_ESP_CONSOLE_UART_CUSTOM

static uart_dev_t *alt_console_uart_dev = (CONFIG_ESP_CONSOLE_UART_NUM == 0) ?

                                          &UART0 :

                                          &UART1;

#endif



void IRAM_ATTR bootloader_configure_spi_pins(int drv)

{

    const uint32_t spiconfig = esp_rom_efuse_get_flash_gpio_info();
@@ -161,15 +172,13 @@ static void bootloader_super_wdt_auto_feed(void) 
    REG_WRITE(RTC_CNTL_SWD_WPROTECT_REG, 0);

}



static void bootloader_init_uart_console(void)

#if CONFIG_ESP_CONSOLE_UART_CUSTOM

void IRAM_ATTR esp_rom_uart_putc(char c)

{

    const int uart_num = 0;



    esp_rom_install_uart_printf();

    esp_rom_uart_tx_wait_idle(0);

    uint32_t clock_hz = UART_CLK_FREQ_ROM;

    esp_rom_uart_set_clock_baudrate(uart_num, clock_hz, CONFIG_ESP_CONSOLE_UART_BAUDRATE);

    while (uart_ll_get_txfifo_len(alt_console_uart_dev) == 0);

    uart_ll_write_txfifo(alt_console_uart_dev, (const uint8_t *) &c, 1);

}

#endif



esp_err_t bootloader_init(void)

{
@@ -190,7 +199,7 @@ esp_err_t bootloader_init(void) 
    // config clock

    bootloader_clock_configure();

    /* initialize uart console, from now on, we can use ets_printf */

    bootloader_init_uart_console();

    bootloader_console_init();

    // update flash ID

    bootloader_flash_update_id();

    // read bootloader header

boot/espressif/port/esp32c3/bootloader.conf

+35 −0
Original line number Diff line number Diff line
@@ -12,6 +12,41 @@ CONFIG_ESP_MCUBOOT_WDT_ENABLE=y 
CONFIG_ESP_SCRATCH_OFFSET=0x210000

CONFIG_ESP_SCRATCH_SIZE=0x40000



# Enables the MCUboot Serial Recovery, that allows the use of

# MCUMGR to upload a firmware through the serial port

# CONFIG_ESP_MCUBOOT_SERIAL=y

# Use Serial through USB JTAG Serial port for Serial Recovery

# CONFIG_ESP_MCUBOOT_SERIAL_USB_SERIAL_JTAG=y

# Use sector erasing (recommended) instead of entire image size

# erasing when uploading through Serial Recovery

# CONFIG_ESP_MCUBOOT_ERASE_PROGRESSIVELY=y



# GPIO used to boot on Serial Recovery

# CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT=5

# GPIO input type (0 for Pull-down, 1 for Pull-up)

# CONFIG_ESP_SERIAL_BOOT_GPIO_INPUT_TYPE=0

# GPIO signal value

# CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT_VAL=1

# Delay time for identify the GPIO signal

# CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S=5

# UART port used for serial communication (not needed when using USB)

# CONFIG_ESP_SERIAL_BOOT_UART_NUM=1

# GPIO for Serial RX signal

# CONFIG_ESP_SERIAL_BOOT_GPIO_RX=8

# GPIO for Serial TX signal

# CONFIG_ESP_SERIAL_BOOT_GPIO_TX=9



# Use UART0 for console printing (use either UART or USB alone)

CONFIG_ESP_CONSOLE_UART=y

CONFIG_ESP_CONSOLE_UART_NUM=0

# Configures alternative UART port for console printing

# (UART_NUM=0 must not be changed)

# CONFIG_ESP_CONSOLE_UART_CUSTOM=y

# CONFIG_ESP_CONSOLE_UART_TX_GPIO=9

# CONFIG_ESP_CONSOLE_UART_RX_GPIO=8

# Use USB JTAG Serial for console printing

# CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y



# CONFIG_ESP_SIGN_EC256=y

# CONFIG_ESP_SIGN_ED25519=n

# CONFIG_ESP_SIGN_RSA=n

boot/espressif/port/esp32c3/ld/bootloader.ld

+1 −1
Original line number Diff line number Diff line
@@ -33,13 +33,13 @@ SECTIONS 
    *libhal.a:bootloader_clock_loader.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_common_loader.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_init_common.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_flash.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_random.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_random*.*(.literal.bootloader_random_disable .text.bootloader_random_disable)

    *libhal.a:bootloader_random*.*(.literal.bootloader_random_enable .text.bootloader_random_enable)

    *libhal.a:bootloader_efuse_esp32c3.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_utility.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_sha.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_console.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_console_loader.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_panic.*(.literal .text .literal.* .text.*)

    *libhal.a:bootloader_soc.*(.literal .text .literal.* .text.*)

boot/espressif/port/esp32c3/serial_adapter.c

0 → 100644
+226 −0
Original line number Diff line number Diff line 
/*

 * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD

 *

 * SPDX-License-Identifier: Apache-2.0

 */



#include <bootutil/bootutil_log.h>



#include <esp_rom_uart.h>

#include <esp_rom_gpio.h>

#include <esp_rom_sys.h>

#include <esp_rom_caps.h>

#include <soc/uart_periph.h>

#include <soc/gpio_struct.h>

#include <soc/io_mux_reg.h>

#include <soc/rtc.h>

#include <hal/gpio_types.h>

#include <hal/gpio_ll.h>

#include <hal/uart_ll.h>

#include <hal/clk_gate_ll.h>

#include <hal/usb_serial_jtag_ll.h>

#include <hal/gpio_hal.h>



#ifdef CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT

#define SERIAL_BOOT_GPIO_DETECT     CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT

#else

#define SERIAL_BOOT_GPIO_DETECT     GPIO_NUM_5

#endif



#ifdef CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT_VAL

#define SERIAL_BOOT_GPIO_DETECT_VAL     CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT_VAL

#else

#define SERIAL_BOOT_GPIO_DETECT_VAL     1

#endif



#ifdef CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S

#define SERIAL_BOOT_DETECT_DELAY_S     CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S

#else

#define SERIAL_BOOT_DETECT_DELAY_S     5

#endif



#ifdef CONFIG_ESP_SERIAL_BOOT_GPIO_INPUT_TYPE

#define SERIAL_BOOT_GPIO_INPUT_TYPE    CONFIG_ESP_SERIAL_BOOT_GPIO_INPUT_TYPE

#else

// pull-down

#define SERIAL_BOOT_GPIO_INPUT_TYPE    0

#endif



#ifndef CONFIG_ESP_MCUBOOT_SERIAL_USB_SERIAL_JTAG



#ifdef CONFIG_ESP_SERIAL_BOOT_UART_NUM

#define SERIAL_BOOT_UART_NUM    CONFIG_ESP_SERIAL_BOOT_UART_NUM

#else

#define SERIAL_BOOT_UART_NUM    ESP_ROM_UART_1

#endif



#ifdef CONFIG_ESP_SERIAL_BOOT_GPIO_RX

#define SERIAL_BOOT_GPIO_RX     CONFIG_ESP_SERIAL_BOOT_GPIO_RX

#else

#define SERIAL_BOOT_GPIO_RX     GPIO_NUM_8

#endif



#ifdef CONFIG_ESP_SERIAL_BOOT_GPIO_TX

#define SERIAL_BOOT_GPIO_TX     CONFIG_ESP_SERIAL_BOOT_GPIO_TX

#else

#define SERIAL_BOOT_GPIO_TX     GPIO_NUM_9

#endif



static uart_dev_t *serial_boot_uart_dev = (SERIAL_BOOT_UART_NUM == 0) ?

                                          &UART0 :

                                          &UART1;



#endif



void console_write(const char *str, int cnt)

{

#ifdef CONFIG_ESP_MCUBOOT_SERIAL_USB_SERIAL_JTAG

    usb_serial_jtag_ll_txfifo_flush();

    while (!usb_serial_jtag_ll_txfifo_writable()) {

        MCUBOOT_WATCHDOG_FEED();

    }

    usb_serial_jtag_ll_write_txfifo((const uint8_t *)str, cnt);

    usb_serial_jtag_ll_txfifo_flush();

#else

    uint32_t tx_len;

    uint32_t write_len;



    do {

        tx_len = uart_ll_get_txfifo_len(serial_boot_uart_dev);

        if (tx_len > 0) {

            write_len = tx_len < cnt ? tx_len : cnt;

            uart_ll_write_txfifo(serial_boot_uart_dev, (const uint8_t *)str, write_len);

            cnt -= write_len;

        }

        MCUBOOT_WATCHDOG_FEED();

        esp_rom_delay_us(1000);

    } while (cnt > 0);

#endif

}



int console_read(char *str, int cnt, int *newline)

{

#ifdef CONFIG_ESP_MCUBOOT_SERIAL_USB_SERIAL_JTAG

    uint32_t read_len = 0;



    esp_rom_delay_us(1000);

    do {

        if (usb_serial_jtag_ll_rxfifo_data_available()) {

            usb_serial_jtag_ll_read_rxfifo((uint8_t *)&str[read_len], 1);

            read_len++;

        }

        MCUBOOT_WATCHDOG_FEED();

        esp_rom_delay_us(1000);

    }  while (!(read_len == cnt || str[read_len - 1] == '\n'));

    *newline = (str[read_len - 1] == '\n') ? 1 : 0;



    return read_len;

#else

    uint32_t len = 0;

    uint32_t read_len = 0;

    bool stop = false;



    do {

        len = uart_ll_get_rxfifo_len(serial_boot_uart_dev);



        if (len > 0) {

            for (uint32_t i = 0; i < len; i++) {

                /* Read the character from the RX FIFO */

                uart_ll_read_rxfifo(serial_boot_uart_dev, (uint8_t *)&str[read_len], 1);

                read_len++;

                if (read_len == cnt - 1|| str[read_len - 1] == '\n') {

                    stop = true;

                    break;

                }

            }

        }

        MCUBOOT_WATCHDOG_FEED();

        esp_rom_delay_us(1000);

    } while (!stop);



    *newline = (str[read_len - 1] == '\n') ? 1 : 0;

    return read_len;

#endif

}



int boot_console_init(void)

{

    BOOT_LOG_INF("Initializing serial boot pins");



#ifdef CONFIG_ESP_MCUBOOT_SERIAL_USB_SERIAL_JTAG

    usb_serial_jtag_ll_txfifo_flush();

    esp_rom_uart_tx_wait_idle(0);

#else

    /* Enable GPIO for UART RX */

    esp_rom_gpio_pad_select_gpio(SERIAL_BOOT_GPIO_RX);

    esp_rom_gpio_connect_in_signal(SERIAL_BOOT_GPIO_RX,

                                   UART_PERIPH_SIGNAL(SERIAL_BOOT_UART_NUM, SOC_UART_RX_PIN_IDX),

                                   0);

    gpio_ll_input_enable(&GPIO, SERIAL_BOOT_GPIO_RX);

    esp_rom_gpio_pad_pullup_only(SERIAL_BOOT_GPIO_RX);





    /* Enable GPIO for UART TX */

    esp_rom_gpio_pad_select_gpio(SERIAL_BOOT_GPIO_TX);

    esp_rom_gpio_connect_out_signal(SERIAL_BOOT_GPIO_TX,

                                    UART_PERIPH_SIGNAL(SERIAL_BOOT_UART_NUM, SOC_UART_TX_PIN_IDX),

                                    0, 0);

    gpio_ll_output_enable(&GPIO, SERIAL_BOOT_GPIO_TX);



    uart_ll_set_sclk(serial_boot_uart_dev, UART_SCLK_APB);

    uart_ll_set_mode_normal(serial_boot_uart_dev);

    uart_ll_set_baudrate(serial_boot_uart_dev, 115200);

    uart_ll_set_stop_bits(serial_boot_uart_dev, 1u);

    uart_ll_set_parity(serial_boot_uart_dev, UART_PARITY_DISABLE);

    uart_ll_set_rx_tout(serial_boot_uart_dev, 16);

    uart_ll_set_data_bit_num(serial_boot_uart_dev, UART_DATA_8_BITS);

    uart_ll_set_tx_idle_num(serial_boot_uart_dev, 0);

    uart_ll_set_hw_flow_ctrl(serial_boot_uart_dev, UART_HW_FLOWCTRL_DISABLE, 100);

    periph_ll_enable_clk_clear_rst(PERIPH_UART0_MODULE + SERIAL_BOOT_UART_NUM);



    uart_ll_txfifo_rst(serial_boot_uart_dev);

    uart_ll_rxfifo_rst(serial_boot_uart_dev);

    esp_rom_delay_us(50000);

#endif



    return 0;

}



bool boot_serial_detect_pin(void)

{

    bool detected = false;

    int pin_value = 0;



    esp_rom_gpio_pad_select_gpio(SERIAL_BOOT_GPIO_DETECT);

    gpio_ll_input_enable(&GPIO, SERIAL_BOOT_GPIO_DETECT);

    switch (SERIAL_BOOT_GPIO_INPUT_TYPE) {

        // Pull-down

        case 0:

            gpio_ll_pulldown_en(&GPIO, SERIAL_BOOT_GPIO_DETECT);

            break;

        // Pull-up

        case 1:

            gpio_ll_pullup_en(&GPIO, SERIAL_BOOT_GPIO_DETECT);

            break;

    }

    esp_rom_delay_us(50000);



    pin_value = gpio_ll_get_level(&GPIO, SERIAL_BOOT_GPIO_DETECT);

    detected = (pin_value == SERIAL_BOOT_GPIO_DETECT_VAL);

    esp_rom_delay_us(50000);



    if (detected) {

        if (SERIAL_BOOT_DETECT_DELAY_S > 0) {

            /* The delay time is an approximation */

            for (int i = 0; i < (SERIAL_BOOT_DETECT_DELAY_S * 100); i++) {

                esp_rom_delay_us(10000);

                pin_value = gpio_ll_get_level(&GPIO, SERIAL_BOOT_GPIO_DETECT);

                detected = (pin_value == SERIAL_BOOT_GPIO_DETECT_VAL);

                if (!detected) {

                    break;

                }

            }

        }

    }

    return detected;

}

docs/readme-espressif.md

+23 −1
Original line number Diff line number Diff line
@@ -552,7 +552,7 @@ Serial recovery mode allows management through MCUMGR (more information and how 
---

***Note***



Supported on ESP32.

Supported on ESP32 and ESP32-C3.



---
@@ -581,6 +581,28 @@ When enabled, the bootloader checks the if the GPIO `<CONFIG_ESP_SERIAL_BOOT_GPI 


Serial mode then uses the UART port configured for communication (`<CONFIG_ESP_SERIAL_BOOT_UART_NUM>`, pins `<CONFIG_ESP_SERIAL_BOOT_GPIO_RX>`, `<CONFIG_ESP_SERIAL_BOOT_GPIO_RX>`).



### [Serial Recovery through USB JTAG Serial port](#serial-recovery-through-usb-jtag-serial-port)



Some chips, like ESP32-C3, have an integrated USB JTAG Serial Controller that implements a serial port (CDC) that can also be used for handling MCUboot Serial Recovery.

More information about the USB pins and hardware configuration on ESP32-C3: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jtag-console.html.



Configuration example:

```

# Use Serial through USB JTAG Serial port for Serial Recovery

CONFIG_ESP_MCUBOOT_SERIAL_USB_SERIAL_JTAG=y

# Use sector erasing (recommended) instead of entire image size

# erasing when uploading through Serial Recovery

CONFIG_ESP_MCUBOOT_ERASE_PROGRESSIVELY=y

# GPIO used to boot on Serial Recovery

CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT=5

# GPIO input type (0 for Pull-down, 1 for Pull-up)

CONFIG_ESP_SERIAL_BOOT_GPIO_INPUT_TYPE=0

# GPIO signal value

CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT_VAL=1

# Delay time for identify the GPIO signal

CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S=5

```



### [MCUMGR image upload example](#mcumgr-image-upload-example)



After entering the Serial recovery mode on the device, MCUMGR can be used as following:

CRA Git | Maintained and supported by SUSTech CRA and CCSE