Add write commands for zlib compressed writing, cleanup and move test function to readme

Author: renzenicolai

README.md

@@ -4,6 +4,41 @@ Component for flashing ESP32 chips using an ESP32 chip.
 
 This component is still in active development and has currently only been tested for programming the ESP32-C6. Many basic esptool functions are not yet supported.
 
+## Usage example
+
+A proper usage example has yet to be written but the block of code below should give an idea.
+
+```
+// Initialize
+uint32_t chip_id;
+esp_log_level_set(TAG, ESP_LOG_DEBUG);
+ESP_ERROR_CHECK(et2_detect(&chip_id));
+ESP_LOGI(TAG, "ESP32 detected; chip id 0x%08" PRIx32, chip_id);
+
+// Start stub
+ESP_ERROR_CHECK(et2_run_stub());
+
+// Write test data to flash
+uint8_t* dummy_data = malloc(4096);
+for (int i = 0; i < 4096; i++) dummy_data[i] = i;
+ESP_ERROR_CHECK(et2_cmd_flash_begin(4096 * 4, 0));
+ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 0));
+ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 1));
+ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 2));
+ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 3));
+ESP_ERROR_CHECK(et2_cmd_flash_finish(false));
+
+// Read test data from flash
+memset(dummy_data, 0, 4096);
+ESP_ERROR_CHECK(et2_cmd_read_flash(0, 4096, dummy_data));
+printf("Data read:\r\n");
+for (size_t i = 0; i < 4096; i++) {
+    printf("%02x", dummy_data[i]);
+}
+printf("\r\n");
+free(dummy_data);
+```
+
 ## License
 
 The contents of this repository are made available under the terms of the MIT license, see [LICENSE](LICENSE) for the full license text.

include/esptoolsquared.h

@@ -7,55 +7,72 @@
 #include <stdint.h>
 #include "esp_system.h"
 
-// ESP flashing protocol commands.
+// ESP flashing protocol commands
 typedef enum {
-    ET2_CMD_FLASH_BEGIN   = 0x02,
-    ET2_CMD_FLASH_DATA    = 0x03,
-    ET2_CMD_FLASH_END     = 0x04,
-    ET2_CMD_MEM_BEGIN     = 0x05,
-    ET2_CMD_MEM_END       = 0x06,
-    ET2_CMD_MEM_DATA      = 0x07,
-    ET2_CMD_SYNC          = 0x08,
-    ET2_CMD_WRITE_REG     = 0x09,
-    ET2_CMD_READ_REG      = 0x0A,
-    // Supported by ESP32-S2 and later.
-    ET2_CMD_SEC_INFO      = 0x14,
-    // Supported by stub only
-    ET2_CMD_ERASE_FLASH   = 0xD0,
-    ET2_CMD_ERASE_REGION  = 0xD1,
-    ET2_CMD_READ_FLASH    = 0xD2,
-    ET2_CMD_RUN_USER_CODE = 0xD3,
+    ET2_CMD_FLASH_BEGIN        = 0x02,
+    ET2_CMD_FLASH_DATA         = 0x03,
+    ET2_CMD_FLASH_END          = 0x04,
+    ET2_CMD_MEM_BEGIN          = 0x05,
+    ET2_CMD_MEM_END            = 0x06,
+    ET2_CMD_MEM_DATA           = 0x07,
+    ET2_CMD_SYNC               = 0x08,
+    ET2_CMD_WRITE_REG          = 0x09,
+    ET2_CMD_READ_REG           = 0x0A,
+    ET2_CMD_SPI_SET_PARAMS     = 0x0B,
+    ET2_CMD_SPI_ATTACH         = 0x0D,
+    ET2_CMD_READ_FLASH_SLOW    = 0x0E,
+    ET2_CMD_CHANGE_BAUDRATE    = 0x0F,
+    ET2_CMD_DEFL_BEGIN         = 0x10,
+    ET2_CMD_DEFL_DATA          = 0x11,
+    ET2_CMD_DEFL_END           = 0x12,
+    ET2_CMD_SPI_FLASH_MD5      = 0x13,
+    ET2_CMD_SEC_INFO           = 0x14,
+    ET2_CMD_ERASE_FLASH        = 0xD0,
+    ET2_CMD_ERASE_REGION       = 0xD1,
+    ET2_CMD_READ_FLASH         = 0xD2,
+    ET2_CMD_RUN_USER_CODE      = 0xD3,
+    ET2_CMD_FLASH_ENCRYPT_DATA = 0xD4,
 } et2_cmd_t;
 
-// Set interface used to a UART.
+// Set interface used to a UART
 esp_err_t et2_setif_uart(uart_port_t uart);
-// Try to connect to and synchronize with the ESP32.
+
+// Try to connect to and synchronize with the ESP32
 esp_err_t et2_sync();
-// Detect an ESP32 and, if present, read its chip ID.
-// If a pointer is NULL, the property is not read.
+
+// Detect an ESP32 and, if present, read its chip ID
+// If a pointer is NULL, the property is not read
 esp_err_t et2_detect(uint32_t* chip_id);
-// Upload and start a flasher stub.
+
+// Upload and start the flasher stub
 esp_err_t et2_run_stub();
 
-// Write to a range of memory.
+// Write to a range of memory
 esp_err_t et2_mem_write(uint32_t addr, void const* wdata, uint32_t len);
-// Write to a range of FLASH.
-esp_err_t et2_flash_write(uint32_t flash_off, void const* wdata, uint32_t len);
 
-// Send MEM_BEGIN command to initiate memory writes.
+// Write application to RAM (sending end command restarts the target into the loaded application)
 esp_err_t et2_cmd_mem_begin(uint32_t size, uint32_t blocks, uint32_t blocksize, uint32_t offset);
-// Send MEM_DATA command to send memory write payload.
 esp_err_t et2_cmd_mem_data(void const* data, uint32_t data_len, uint32_t seq);
-// Send MEM_END command to restart into application.
 esp_err_t et2_cmd_mem_end(uint32_t entrypoint);
-// Send FLASH_BEGIN command to initiate memory writes.
+
+// Write uncompressed data to flash
 esp_err_t et2_cmd_flash_begin(uint32_t size, uint32_t offset);
-// Send FLASH_BLOCK command to send memory write payload.
 esp_err_t et2_cmd_flash_data(const uint8_t* data, uint32_t data_len, uint32_t seq);
-// Send FLASH_FINISH command to restart into application.
 esp_err_t et2_cmd_flash_finish(bool reboot);
 
+// Write compressed data to flash
+esp_err_t et2_cmd_deflate_begin(uint32_t uncompressed_size, uint32_t compressed_size, uint32_t offset);
+esp_err_t et2_cmd_deflate_data(const uint8_t* data, uint32_t data_len, uint32_t seq);
+esp_err_t et2_cmd_deflate_finish(bool reboot);
+
+// Read a register
 esp_err_t et2_cmd_read_reg(uint32_t address, uint32_t* out_value);
+
+// Read uncompressed data from flash
 esp_err_t et2_cmd_read_flash(uint32_t offset, uint32_t length, uint8_t* out_data);
 
-void et2_test(void);
+// Erase entire flash
+esp_err_t et2_cmd_erase_flash(void);
+
+// Erase a region of flash
+esp_err_t et2_cmd_erase_region(uint32_t offset, uint32_t length);

src/esptoolsquared.c

@@ -57,37 +57,6 @@ static uint32_t et2_checksum(const uint8_t* data, uint32_t data_length, uint32_t
     return state;
 }
 
-void et2_test(void) {
-    uint32_t chip_id;
-    esp_log_level_set(TAG, ESP_LOG_DEBUG);
-    ESP_ERROR_CHECK(et2_detect(&chip_id));
-    ESP_LOGI(TAG, "ESP32 detected; chip id 0x%08" PRIx32, chip_id);
-
-    ESP_ERROR_CHECK(et2_run_stub());
-
-    // Send FLASH_BEGIN command to initiate memory writes
-    uint8_t* dummy_data = malloc(4096);
-
-    for (int i = 0; i < 4096; i++) dummy_data[i] = i;
-
-    ESP_ERROR_CHECK(et2_cmd_flash_begin(4096 * 4, 0));
-    ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 0));
-    ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 1));
-    ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 2));
-    ESP_ERROR_CHECK(et2_cmd_flash_data(dummy_data, 4096, 3));
-    ESP_ERROR_CHECK(et2_cmd_flash_finish(false));
-
-    uint32_t length = 4 * 1024;
-    uint8_t* buffer = malloc(length);
-    ESP_ERROR_CHECK(et2_cmd_read_flash(0, length, buffer));
-
-    printf("DATA READ FROM FLASH:\r\n");
-    for (size_t i = 0; i < length; i++) {
-        printf("%02x", buffer[i]);
-    }
-    printf("\r\n");
-}
-
 esp_err_t et2_read_magic_reg(uint32_t* out_magic) {
     return et2_cmd_read_reg(0x40001000, out_magic);
 }
@@ -529,3 +498,36 @@ esp_err_t et2_cmd_flash_finish(bool reboot) {
     uint32_t params[] = {reboot ? 0 : 1};
     return et2_send_cmd_check(ET2_CMD_FLASH_END, 0, params, sizeof(params), NULL, NULL, NULL, NULL, NULL, 0);
 }
+
+// Write compressed data to flash
+
+esp_err_t et2_cmd_deflate_begin(uint32_t uncompressed_size, uint32_t compressed_size, uint32_t offset) {
+    uint32_t num_blocks = (compressed_size + FLASH_WRITE_SIZE - 1) / FLASH_WRITE_SIZE;
+    uint32_t erase_size = uncompressed_size;
+    uint32_t params[]   = {erase_size, num_blocks, FLASH_WRITE_SIZE, offset};
+    return et2_send_cmd_check(ET2_CMD_DEFL_BEGIN, 0, params, sizeof(params), NULL, NULL, NULL, NULL, NULL, 0);
+}
+
+esp_err_t et2_cmd_deflate_data(const uint8_t* data, uint32_t data_len, uint32_t seq) {
+    uint32_t params[] = {data_len, seq, 0, 0};
+    ESP_RETURN_ON_ERROR(
+        et2_send_cmd_check(ET2_CMD_DEFL_DATA, 0, params, sizeof(params), NULL, NULL, NULL, NULL, data, data_len), TAG,
+        "Failed to write to flash");
+    return ESP_OK;
+}
+
+esp_err_t et2_cmd_deflate_finish(bool reboot) {
+    uint32_t params[] = {reboot ? 0 : 1};
+    return et2_send_cmd_check(ET2_CMD_DEFL_END, 0, params, sizeof(params), NULL, NULL, NULL, NULL, NULL, 0);
+}
+
+// Erase entire flash
+esp_err_t et2_cmd_erase_flash(void) {
+    return et2_send_cmd_check(ET2_CMD_ERASE_FLASH, 0, NULL, 0, NULL, NULL, NULL, NULL, NULL, 0);
+}
+
+// Erase a region of flash
+esp_err_t et2_cmd_erase_region(uint32_t offset, uint32_t length) {
+    uint32_t params[] = {offset, length};
+    return et2_send_cmd_check(ET2_CMD_ERASE_REGION, 0, params, sizeof(params), NULL, NULL, NULL, NULL, NULL, 0);
+}