# sftool

A command-line utility for the SiFli SoC serial tool.

## Introduction

sftool is an open-source tool specifically designed for the SiFli series of SoCs (System on Chip) to interact with the chip via a serial interface. It supports various operations, including writing data to flash memory and resetting the chip.

## Features

- Supports SF32 series chips
- Supports multiple storage types: NOR flash, NAND flash, and SD card
- Configurable serial port parameters
- Reliable flash write functionality with verification and compression support
- Flexible reset options
- Customizable connection attempt counts

## Installation

### Download Pre-built

You can download the latest pre-built sftool from the GitHub release. Our naming convention is sftool-v{version}-{target}.zip/tar.xz. Please choose the compressed package suitable for your system architecture.

[GitHub Release](https://github.com/OpenSiFli/sftool/releases)

URL: https://github.com/OpenSiFli/sftool/releases

### Install Using Cargo

```bash
cargo install --git https://github.com/OpenSiFli/sftool
```

### Build from Source

```bash
# Clone the repository
git clone https://github.com/OpenSiFli/sftool.git
cd sftool

# Build using Cargo
cargo build --release

# The compiled binary is located at
# ./target/release/sftool
```

## Usage

### Basic Command Format

```bash
sftool [options] command [command options]
```

### Global Options

- `-c, --chip <CHIP>`: Target chip type (currently supports SF32LB52)
- `-m, --memory <MEMORY>`: Storage type [nor, nand, sd] (default: nor)
- `-p, --port <PORT>`: Serial port device path
- `-b, --baud <BAUD>`: Serial port baud rate used for flash/write (default: 1000000)
- `--before <OPERATION>`: Operation before connecting to the chip [no_reset, soft_reset] (default: no_reset)
- `--after <OPERATION>`: Operation after the tool completes [no_reset, soft_reset] (default: soft_reset)
- `--connect-attempts <ATTEMPTS>`: Number of connection attempts, negative or 0 for infinite (default: 7)
- `--compat` : Compatibility mode, enable this option if you frequently encounter timeout errors or post-download verification failures.

### Write Flash Command

```bash
# Linux/Mac
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash [options] <file@address>...
# Windows
sftool -c SF32LB52 -p COM9 write_flash [options] <file@address>...
```

#### Write Flash Options

- `--verify`: Verify the data just written to flash
- `-u, --no-compress`: Disable data compression during transfer
- `-e, --erase-all`: Erase all flash regions before programming (not just the write regions)
- `<file@address>`: Binary file and its target address, the @address part is optional if the file format contains address information

### Examples

Linux/Mac:

```bash
# Write a single file to flash
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash app.bin@0x12020000

# Write multiple files to different addresses
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash bootloader.bin@0x12010000 app.bin@0x12020000 ftab.bin@0x12000000

# Write and verify
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash --verify app.bin@0x12020000

# Erase all flash before writing
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash -e app.bin@0x12020000
```

Windows:

```bash
# Write multiple files to different addresses
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash bootloader.bin@0x1000 app.bin@0x12010000 ftab.bin@0x12000000
# Others are the same as above
```

## Library Usage

sftool also provides a reusable Rust library `sftool-lib` that can be integrated into other Rust projects:

```rust
use sftool_lib::{SifliTool, SifliToolBase, WriteFlashParams};

fn main() {
    let mut tool = SifliTool::new(
        SifliToolBase {
            port_name: "/dev/ttyUSB0".to_string(),
            chip: "sf32lb52".to_string(),
            memory_type: "nor".to_string(),
            quiet: false,
        },
        Some(WriteFlashParams {
            file_path: vec!["app.bin@0x10000".to_string()],
            verify: true,
            no_compress: false,
            erase_all: false,
        }),
    );
    
    if let Err(e) = tool.write_flash() {
        eprintln!("Error: {:?}", e);
    }
}
```

## Contribution

Pull requests and issues are welcome!

## Project Links

- [GitHub Repository](https://github.com/OpenSiFli/sftool)
- [Documentation](https://docs.rs/sftool)