Add read-flash support (#558)

* feat: Standarize names and add missing commands

* feat: Add missing commands and documentation

* feat: Implement read_flash

* feat: Add block_size and max_in_flight args

* docs: Remove todos

* feat: Only support read-flash when using stub

* feat: Add read_flash support to cargo-espflash

* docs: Update changelog

Author: SergioGasquez

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add support for 26 MHz bootloader for ESP32 and ESP32-C2 (#553)
 - Add CI check to verify that CHANGELOG is updated (#560)
 - Add `--before` and `--after` reset arguments (#561)
+- Add `read-flash` command (#558)
 
 ### Fixed
 

cargo-espflash/src/main.rs

@@ -10,9 +10,9 @@ use espflash::{
     cli::{
         self, board_info, checksum_md5, completions, config::Config, connect, erase_flash,
         erase_partitions, erase_region, flash_elf_image, monitor::monitor, partition_table,
-        print_board_info, save_elf_as_image, serial_monitor, ChecksumMd5Args, CompletionsArgs,
-        ConnectArgs, EraseFlashArgs, EraseRegionArgs, EspflashProgress, FlashConfigArgs,
-        MonitorArgs, PartitionTableArgs,
+        print_board_info, read_flash, save_elf_as_image, serial_monitor, ChecksumMd5Args,
+        CompletionsArgs, ConnectArgs, EraseFlashArgs, EraseRegionArgs, EspflashProgress,
+        FlashConfigArgs, MonitorArgs, PartitionTableArgs, ReadFlashArgs,
     },
     error::Error as EspflashError,
     flasher::{parse_partition_table, FlashData, FlashSettings},
@@ -100,6 +100,8 @@ enum Commands {
     /// '--to-binary' options, plus the ability to print a partition table
     /// in tabular format.
     PartitionTable(PartitionTableArgs),
+    /// Read SPI flash content
+    ReadFlash(ReadFlashArgs),
     /// Generate a binary application image and save it to a local disk
     ///
     /// If the '--merge' option is used, then the bootloader, partition table,
@@ -219,6 +221,7 @@ fn main() -> Result<()> {
         Commands::Flash(args) => flash(args, &config),
         Commands::Monitor(args) => serial_monitor(args, &config),
         Commands::PartitionTable(args) => partition_table(args),
+        Commands::ReadFlash(args) => read_flash(args, &config),
         Commands::SaveImage(args) => save_image(args),
         Commands::ChecksumMd5(args) => checksum_md5(&args, &config),
     }
@@ -233,7 +236,7 @@ struct BuildContext {
 
 pub fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
-        return Err(EspflashError::StubRequiredToEraseFlash).into_diagnostic();
+        return Err(EspflashError::StubRequired).into_diagnostic();
     }
 
     let metadata_partition_table = PackageMetadata::load(&args.package)

espflash/src/bin/espflash.rs

@@ -9,9 +9,9 @@ use espflash::{
     cli::{
         self, board_info, checksum_md5, completions, config::Config, connect, erase_flash,
         erase_partitions, erase_region, flash_elf_image, monitor::monitor, parse_uint32,
-        partition_table, print_board_info, save_elf_as_image, serial_monitor, ChecksumMd5Args,
-        CompletionsArgs, ConnectArgs, EraseFlashArgs, EraseRegionArgs, EspflashProgress,
-        FlashConfigArgs, MonitorArgs, PartitionTableArgs,
+        partition_table, print_board_info, read_flash, save_elf_as_image, serial_monitor,
+        ChecksumMd5Args, CompletionsArgs, ConnectArgs, EraseFlashArgs, EraseRegionArgs,
+        EspflashProgress, FlashConfigArgs, MonitorArgs, PartitionTableArgs, ReadFlashArgs,
     },
     error::Error,
     flasher::{parse_partition_table, FlashData, FlashSettings},
@@ -75,6 +75,8 @@ enum Commands {
     /// '--to-binary' options, plus the ability to print a partition table
     /// in tabular format.
     PartitionTable(PartitionTableArgs),
+    /// Read SPI flash content
+    ReadFlash(ReadFlashArgs),
     /// Generate a binary application image and save it to a local disk
     ///
     /// If the '--merge' option is used, then the bootloader, partition table,
@@ -178,14 +180,15 @@ fn main() -> Result<()> {
         Commands::Monitor(args) => serial_monitor(args, &config),
         Commands::PartitionTable(args) => partition_table(args),
         Commands::SaveImage(args) => save_image(args),
+        Commands::ReadFlash(args) => read_flash(args, &config),
         Commands::WriteBin(args) => write_bin(args, &config),
         Commands::ChecksumMd5(args) => checksum_md5(&args, &config),
     }
 }
 
 pub fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
-        return Err(Error::StubRequiredToEraseFlash).into_diagnostic();
+        return Err(Error::StubRequired.into());
     }
 
     let mut flash = connect(&args.connect_args, config, false, false)?;

espflash/src/cli/mod.rs

@@ -194,6 +194,32 @@ pub struct PartitionTableArgs {
     to_csv: bool,
 }
 
+/// Reads the content of flash memory and saves it to a file
+#[derive(Debug, Args)]
+#[non_exhaustive]
+pub struct ReadFlashArgs {
+    /// Offset to start reading from
+    #[arg(value_name = "OFFSET", value_parser = parse_uint32)]
+    pub addr: u32,
+    /// Size of each individual packet of data
+    ///
+    /// Defaults to 0x1000 (FLASH_SECTOR_SIZE)
+    #[arg(long, default_value = "0x1000", value_parser = parse_uint32)]
+    pub block_size: u32,
+    /// Connection configuration
+    #[clap(flatten)]
+    connect_args: ConnectArgs,
+    /// Size of the region to erase
+    #[arg(value_name = "SIZE", value_parser = parse_uint32)]
+    pub size: u32,
+    /// Name of binary dump
+    #[arg(value_name = "FILE")]
+    pub file: PathBuf,
+    /// Maximum number of un-acked packets
+    #[arg(long, default_value = "64", value_parser = parse_uint32)]
+    pub max_in_flight: u32,
+}
+
 /// Save the image to disk instead of flashing to device
 #[derive(Debug, Args)]
 #[non_exhaustive]
@@ -558,7 +584,7 @@ impl ProgressCallbacks for EspflashProgress {
 
 pub fn erase_flash(args: EraseFlashArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
-        return Err(Error::StubRequiredToEraseFlash).into_diagnostic();
+        return Err(Error::StubRequired.into());
     }
 
     let mut flash = connect(&args.connect_args, config, true, true)?;
@@ -575,7 +601,7 @@ pub fn erase_flash(args: EraseFlashArgs, config: &Config) -> Result<()> {
 
 pub fn erase_region(args: EraseRegionArgs, config: &Config) -> Result<()> {
     if args.connect_args.no_stub {
-        return Err(Error::StubRequiredToEraseFlash).into_diagnostic();
+        return Err(Error::StubRequired).into_diagnostic();
     }
 
     let mut flash = connect(&args.connect_args, config, true, true)?;
@@ -677,6 +703,25 @@ fn erase_partition(flasher: &mut Flasher, part: &Partition) -> Result<()> {
     flasher.erase_region(offset, size).into_diagnostic()
 }
 
+/// Read flash content and write it to a file
+pub fn read_flash(args: ReadFlashArgs, config: &Config) -> Result<()> {
+    if args.connect_args.no_stub {
+        return Err(Error::StubRequired.into());
+    }
+
+    let mut flasher = connect(&args.connect_args, config, false, false)?;
+    print_board_info(&mut flasher)?;
+    flasher.read_flash(
+        args.addr,
+        args.size,
+        args.block_size,
+        args.max_in_flight,
+        args.file,
+    )?;
+
+    Ok(())
+}
+
 /// Convert and display CSV and binary partition tables
 pub fn partition_table(args: PartitionTableArgs) -> Result<()> {
     if args.to_binary {