Esp32BootloaderHal.hxx

Go to the documentation of this file.

 
#ifndef _FREERTOS_DRIVERS_ESP32_ESP32BOOTLOADERHAL_HXX_
#define _FREERTOS_DRIVERS_ESP32_ESP32BOOTLOADERHAL_HXX_
 
#include "sdkconfig.h"
 
#ifndef BOOTLOADER_LOG_LEVEL
#define BOOTLOADER_LOG_LEVEL VERBOSE
#endif // BOOTLOADER_LOG_LEVEL
 
#ifndef BOOTLOADER_TWAI_LOG_LEVEL
#define BOOTLOADER_TWAI_LOG_LEVEL VERBOSE
#endif // BOOTLOADER_TWAI_LOG_LEVEL
 
// Enable streaming support for the bootloader
#define BOOTLOADER_STREAM
#ifndef WRITE_BUFFER_SIZE
// Set the buffer size to half of the sector size to minimize the flash writes.
#define WRITE_BUFFER_SIZE (CONFIG_WL_SECTOR_SIZE / 2)
#endif // WRITE_BUFFER_SIZE
 
#include <driver/twai.h>
 
#include <esp_app_format.h>
#include <esp_chip_info.h>
#include <esp_ota_ops.h>
#if defined(CONFIG_IDF_TARGET_ESP32)
#include <esp32/rom/rtc.h>
#elif defined(CONFIG_IDF_TARGET_ESP32S2)
#include <esp32s2/rom/rtc.h>
#elif defined(CONFIG_IDF_TARGET_ESP32S3)
#include <esp32s3/rom/rtc.h>
#elif defined(CONFIG_IDF_TARGET_ESP32C3)
#include <esp32c3/rom/rtc.h>
#else
#error Unknown/Unsupported ESP32 variant.
#endif
#include <stdint.h>
 
#include "openlcb/Bootloader.hxx"
#include "openlcb/Defs.hxx"
#include "utils/constants.hxx"
#include "utils/Hub.hxx"
 
struct Esp32BootloaderState
{
    esp_chip_id_t chip_id;
 
    struct app_header app_header;
 
    uint64_t node_id;
 
    esp_partition_t *current;
 
    esp_partition_t *target;
 
    esp_ota_handle_t ota_handle;
 
    bool twai_initialized;
 
    gpio_num_t tx_pin;
 
    gpio_num_t rx_pin;
};
 
static Esp32BootloaderState esp_bl_state;
 
static constexpr BaseType_t MAX_TWAI_WAIT_RX = pdMS_TO_TICKS(250);
 
static constexpr BaseType_t MAX_TWAI_WAIT_TX = pdMS_TO_TICKS(0);
 
static uint32_t RTC_NOINIT_ATTR bootloader_request;
 
static constexpr uint32_t RTC_BOOL_TRUE = 0x92e01a42;
 
static constexpr uint32_t RTC_BOOL_FALSE = 0;
 
extern "C"
{
 
void bootloader_hw_init(void)
{
    // TWAI driver timing configuration, 125kbps.
    twai_timing_config_t t_config = TWAI_TIMING_CONFIG_125KBITS();
 
    // TWAI driver filter configuration, accept all frames.
    twai_filter_config_t f_config = TWAI_FILTER_CONFIG_ACCEPT_ALL();
 
    // TWAI driver general configuration.
    twai_general_config_t g_config =
        TWAI_GENERAL_CONFIG_DEFAULT(esp_bl_state.tx_pin, esp_bl_state.rx_pin,
                                    TWAI_MODE_NORMAL);
    g_config.tx_queue_len = config_can_tx_buffer_size();
    g_config.rx_queue_len = config_can_rx_buffer_size();
 
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] Configuring TWAI driver");
    ESP_ERROR_CHECK(twai_driver_install(&g_config, &t_config, &f_config));
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] Starting TWAI driver");
    ESP_ERROR_CHECK(twai_start());
    esp_bl_state.twai_initialized = true;
}
 
void application_entry(void)
{
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] application_entry");
 
    // reset the RTC persistent variable to not enter bootloader on next
    // restart.
    bootloader_request = RTC_BOOL_FALSE;
 
    // restart the esp32 since we do not have a way to rerun app_main.
    esp_restart();
}
 
void bootloader_reboot(void)
{
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] Reboot requested");
}
 
bool read_can_frame(struct can_frame *frame)
{
    twai_message_t rx_msg;
    memset(&rx_msg, 0, sizeof(twai_message_t));
    if (twai_receive(&rx_msg, MAX_TWAI_WAIT) == ESP_OK)
    {
        LOG(BOOTLOADER_TWAI_LOG_LEVEL, "[Bootloader] CAN_RX");
        frame->can_id = rx_msg.identifier;
        frame->can_dlc = rx_msg.data_length_code;
        frame->can_err = 0;
        frame->can_eff = rx_msg.extd;
        frame->can_rtr = rx_msg.rtr;
        memcpy(frame->data, rx_msg.data, frame->can_dlc);
        return true;
    }
    return false;
}
 
bool try_send_can_frame(const struct can_frame &frame)
{
    twai_message_t tx_msg;
    memset(&tx_msg, 0, sizeof(twai_message_t));
    tx_msg.identifier = frame.can_id;
    tx_msg.data_length_code = frame.can_dlc;
    tx_msg.extd = frame.can_eff;
    tx_msg.rtr = frame.can_rtr;
    memcpy(tx_msg.data, frame.data, frame.can_dlc);
    if (twai_transmit(&tx_msg, MAX_TWAI_WAIT_TX) == ESP_OK)
    {
        LOG(BOOTLOADER_TWAI_LOG_LEVEL, "[Bootloader] CAN_TX");
        return true;
    }
    return false;
}
 
void get_flash_boundaries(const void **flash_min, const void **flash_max,
    const struct app_header **app_header)
{
    LOG(BOOTLOADER_LOG_LEVEL,
        "[Bootloader] get_flash_boundaries(%d, %" PRIu32 ")",
        0, esp_bl_state.app_header.app_size);
    *((uint32_t *)flash_min) = 0;
    *((uint32_t *)flash_max) = esp_bl_state.app_header.app_size;
    *app_header = &esp_bl_state.app_header;
}
 
void get_flash_page_info(
    const void *address, const void **page_start, uint32_t *page_length_bytes)
{
    uint32_t value = (uint32_t)address;
    value &= ~(CONFIG_WL_SECTOR_SIZE - 1);
    *page_start = (const void *)value;
    *page_length_bytes = CONFIG_WL_SECTOR_SIZE;
    LOG(BOOTLOADER_LOG_LEVEL,
        "[Bootloader] get_flash_page_info(%" PRIu32 ", %" PRIu32")",
        value, *page_length_bytes);
}
 
void erase_flash_page(const void *address)
{
    // NO OP as this is handled automatically as part of esp_ota_write.
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] Erase: %" PRIu32,
        (uint32_t)address);
}
 
void write_flash(const void *address, const void *data, uint32_t size_bytes)
{
    uint32_t addr = (uint32_t)address;
    LOG(VERBOSE, "[Bootloader] Write: %" PRIu32 ", %" PRIu32, addr,
        size_bytes);
 
    // The first part of the received binary should have the image header,
    // segment header and app description. These are used as a first pass
    // validation of the received data to ensure it is a valid firmware.
    if (addr == 0)
    {
        // Mapping of known ESP32 chip id values.
        const char * const CHIP_ID_NAMES[] =
        {
            // Note: this must be kept in sync with esp_chip_id_t.
            "ESP32",            // 0x00 ESP_CHIP_ID_ESP32
            "INVALID",          // 0x01 invalid (placeholder)
            "ESP32-S2",         // 0x02 ESP_CHIP_ID_ESP32S2
            "INVALID",          // 0x03 invalid (placeholder)
            "INVALID",          // 0x04 invalid (placeholder)
            "ESP32-C3",         // 0x05 ESP_CHIP_ID_ESP32C3
            "INVALID",          // 0x06 invalid (placeholder)
            "INVALID",          // 0x07 invalid (placeholder)
            "INVALID",          // 0x08 invalid (placeholder)
            "ESP32-S3",         // 0x09 ESP_CHIP_ID_ESP32S3
            "ESP32-H2",         // 0x0A ESP_CHIP_ID_ESP32H2
            "INVALID",          // 0x0B invalid (placeholder)
            "ESP32-C2",         // 0x0C ESP_CHIP_ID_ESP32C2
        };
 
        bool should_abort = false;
        esp_image_header_t *image_header = (esp_image_header_t *)data;
        // If the image magic is correct we can proceed with validating the
        // basic details of the image.
        if (image_header->magic == ESP_IMAGE_HEADER_MAGIC)
        {
            LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] Chip ID: %s / %x (%x)",
                CHIP_ID_NAMES[image_header->chip_id],
                image_header->chip_id, esp_bl_state.chip_id);
            // validate the image magic byte and chip type to
            // ensure it matches the currently running chip.
            if (image_header->chip_id != ESP_CHIP_ID_INVALID &&
                image_header->chip_id == esp_bl_state.chip_id)
            {
                // start the OTA process at this point, if we have had a
                // previous failure this will reset the OTA process so we can
                // start fresh.
                esp_err_t err = ESP_ERROR_CHECK_WITHOUT_ABORT(
                    esp_ota_begin(esp_bl_state.target, OTA_SIZE_UNKNOWN,
                                  &esp_bl_state.ota_handle));
                should_abort = (err != ESP_OK);
            }
            else
            {
                LOG_ERROR("[Bootloader] Firmware does not appear to be valid "
                          "or is for a different chip (%s - %x vs %s - %x).",
                          CHIP_ID_NAMES[image_header->chip_id],
                          image_header->chip_id,
                          CHIP_ID_NAMES[esp_bl_state.chip_id],
                          esp_bl_state.chip_id);
                should_abort = true;
            }
        }
        else
        {
            LOG_ERROR("[Bootloader] Image magic is incorrect: %d vs %d!",
                      image_header->magic, ESP_IMAGE_HEADER_MAGIC);
            should_abort = true;
        }
 
        // It would be ideal to abort the firmware upload at this point but the
        // bootloader HAL does not offer a way to abort the transfer so instead
        // reboot the node.
        if (should_abort || esp_bl_state.ota_handle == 0)
        {
            // reset the RTC persistent variable to not enter bootloader on
            // next restart.
            bootloader_request = RTC_BOOL_FALSE;
 
            // cleanup the OTA handle since we are aborting.
            if (esp_bl_state.ota_handle != 0)
            {
                // abort the OTA operation, we do not validate the return code
                // other than logging the error (if any) as this method only
                // cleans up the ota_handle reference within the OTA system and
                // does not impact future usage.
                ESP_ERROR_CHECK_WITHOUT_ABORT(
                    esp_ota_abort(esp_bl_state.ota_handle));
            }
 
            // invalidate ota_handle in case the esp32 does not reboot before
            // the next time address zero comes up again.
            esp_bl_state.ota_handle = 0;
            esp_restart();
        }
    }
    bootloader_led(LED_WRITING, true);
    bootloader_led(LED_ACTIVE, false);
    ESP_ERROR_CHECK(
        esp_ota_write(esp_bl_state.ota_handle, data, size_bytes));
    bootloader_led(LED_WRITING, false);
    bootloader_led(LED_ACTIVE, true);
}
 
uint16_t flash_complete(void)
{
    LOG(INFO, "[Bootloader] Finalizing firmware update");
    esp_err_t res = esp_ota_end(esp_bl_state.ota_handle);
    if (res != ESP_OK)
    {
        LOG_ERROR("[Bootloader] Firmware update failed: %s (%04x), aborting!",
            esp_err_to_name(res), res);
        return openlcb::Defs::ERROR_FIRMWARE_CSUM;        
    }
    LOG(INFO,
        "[Bootloader] Firmware appears valid, updating the next boot "
        "partition to %s.", esp_bl_state.target->label);
    res = esp_ota_set_boot_partition(esp_bl_state.target);
    if (res != ESP_OK)
    {
        LOG_ERROR("[Bootloader] Failed to update the boot partition %s (%04x)!",
            esp_err_to_name(res), res);
        return openlcb::Defs::ERROR_FIRMWARE_CSUM;
    }
    return openlcb::Defs::ERROR_CODE_OK;
}
 
void checksum_data(const void* data, uint32_t size, uint32_t* checksum)
{
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] checksum_data(%" PRIu32 ")", size);
    // Force the checksum to be zero since it is not currently used on the
    // ESP32. The startup of the node may validate the built-in SHA256 and
    // fallback to previous application binary if the SHA256 validation fails.
    memset(checksum, 0, sizeof(uint32_t) * CHECKSUM_COUNT);
}
 
uint16_t nmranet_alias(void)
{
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] nmranet_alias");
    // let the bootloader generate it based on nmranet_nodeid().
    return 0;
}
 
uint64_t nmranet_nodeid(void)
{
    LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] nmranet_nodeid");
    return esp_bl_state.node_id;
}
 
} // extern "C"
 
void esp32_bootloader_init(uint8_t reset_reason)
{
    // If this is the first power up of the node we need to reset the flag
    // since it will not be initialized automatically.
    if (reset_reason == POWERON_RESET)
    {
        bootloader_request = RTC_BOOL_FALSE;
    }
}
 
void esp32_bootloader_run(uint64_t id, gpio_num_t rx, gpio_num_t tx,
                          bool reboot_on_exit = true)
{
    memset(&esp_bl_state, 0, sizeof(Esp32BootloaderState));
 
    esp_bl_state.node_id = id;
    esp_bl_state.tx_pin = tx;
    esp_bl_state.rx_pin = rx;
    esp_bl_state.chip_id = ESP_CHIP_ID_INVALID;
 
    // Extract the currently running chip details so we can use it to confirm
    // the received firmware is for this chip.
    esp_chip_info_t chip_info;
    esp_chip_info(&chip_info);
    switch (chip_info.model)
    {
        case CHIP_ESP32:
            esp_bl_state.chip_id = ESP_CHIP_ID_ESP32;
            break;
        case CHIP_ESP32S2:
            esp_bl_state.chip_id = ESP_CHIP_ID_ESP32S2;
            break;
        case CHIP_ESP32S3:
            esp_bl_state.chip_id = ESP_CHIP_ID_ESP32S3;
            break;
        case CHIP_ESP32C3:
            esp_bl_state.chip_id = ESP_CHIP_ID_ESP32C3;
            break;
        default:
            LOG(FATAL, "[Bootloader] Unknown/Unsupported Chip ID: %x",
                chip_info.model);
    }
 
    // Initialize the app header details based on the currently running
    // partition.
    esp_bl_state.current = (esp_partition_t *)esp_ota_get_running_partition();
    esp_bl_state.app_header.app_size = esp_bl_state.current->size;
 
    // Find the next OTA partition and confirm it is not the currently running
    // partition.
    esp_bl_state.target =
        (esp_partition_t *)esp_ota_get_next_update_partition(NULL);
    if (esp_bl_state.target != nullptr &&
        esp_bl_state.target != esp_bl_state.current)
    {
        LOG(INFO, "[Bootloader] Preparing to receive firmware");
        LOG(INFO, "[Bootloader] Current partition: %s",
            esp_bl_state.current->label);
        LOG(INFO, "[Bootloader] Target partition: %s",
            esp_bl_state.target->label);
 
        // since we have the target partition identified, start the bootloader.
        LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] calling bootloader_entry");
        bootloader_entry();
    }
    else
    {
        LOG_ERROR("[Bootloader] Unable to locate next OTA partition!");
    }
 
    if (esp_bl_state.twai_initialized)
    {
        LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] Stopping TWAI driver");
        ESP_ERROR_CHECK(twai_stop());
        LOG(BOOTLOADER_LOG_LEVEL, "[Bootloader] Disabling TWAI driver");
        ESP_ERROR_CHECK(twai_driver_uninstall());
    }
 
    // reset the RTC persistent variable to not enter bootloader on next
    // restart.
    bootloader_request = RTC_BOOL_FALSE;
 
    if (reboot_on_exit)
    {
        // If we reach here we should restart the node.
        LOG(INFO, "[Bootloader] Restarting!");
        esp_restart();
    }
}
 
#endif // _FREERTOS_DRIVERS_ESP32_ESP32BOOTLOADERHAL_HXX_