Crate hisiflash 

hisiflash

A library for flashing HiSilicon chips.

This crate provides the core functionality for communicating with HiSilicon chips via serial port, including:

• FWPKG firmware package parsing
• WS63 protocol implementation
• YMODEM file transfer
• CRC16-XMODEM checksum calculation

Supported Chips

• WS63 (primary support)
• More chips coming in future releases

Supported Platforms

• Native (default): Linux, macOS, Windows via the serialport crate
• WASM (experimental): Web browsers via the Web Serial API

Cancellation Model

Long-running operations (flashing, erasing, etc.) can be cancelled via the CancelContext mechanism. This allows the embedding application (e.g., CLI) to signal interruption (e.g., Ctrl-C) and have the operation stop gracefully.

Quick Start

use hisiflash::{CancelContext, cancel_context_from_global};

// Option 1: Use global interrupt flag (set by CLI when Ctrl-C is pressed)
let cancel = cancel_context_from_global();

// Option 2: Create a custom cancel context
use std::sync::atomic::{AtomicBool, Ordering};
let flag = AtomicBool::new(false);
let cancel = CancelContext::new(move || flag.load(Ordering::SeqCst));

// Option 3: No cancellation (always returns "not cancelled")
let cancel = CancelContext::none();

Integration with Flasher

use hisiflash::{CancelContext, Ws63Flasher, cancel_context_from_global};

// Create flasher with global cancellation support
let cancel = cancel_context_from_global();
let flasher = Ws63Flasher::with_cancel(port, 921600, cancel);

// Or use non-cancellable flasher
let flasher = Ws63Flasher::new(port, 921600);

Features

• native (default): Native serial port support
• wasm: WASM/Web Serial API support (experimental)
• serde: Serialization support for data types

Example

use hisiflash::{ChipFamily, Fwpkg};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse firmware package
    let fwpkg = Fwpkg::from_file("firmware.fwpkg")?;

    // Create flasher and connect (native only)
    #[cfg(feature = "native")]
    {
        let chip = ChipFamily::Ws63;
        let mut flasher = chip.create_flasher("/dev/ttyUSB0", 921600, false, 0)?;
        flasher.connect()?;

        // Flash the firmware
        flasher.flash_fwpkg(&fwpkg, None, &mut |name, current, total| {
            println!("Flashing {}: {}/{}", name, current, total);
        })?;

        // Reset the device
        flasher.reset()?;
    }

    Ok(())
}

Re-exports

pub use port::NativePort;

pub use port::NativePortEnumerator;

pub use target::ChipConfig;

pub use target::ChipFamily;

pub use target::ChipOps;

pub use target::Flasher;

pub use device::DetectedPort;

pub use device::DeviceKind;

pub use device::TransportKind;

pub use device::UsbDevice;

pub use error::Error;

pub use error::Result;

pub use host::auto_detect_port;

pub use host::discover_hisilicon_ports;

pub use host::discover_ports;

pub use image::fwpkg::Fwpkg;

pub use image::fwpkg::FwpkgBinInfo;

pub use image::fwpkg::FwpkgHeader;

pub use image::fwpkg::FwpkgVersion;

pub use image::fwpkg::PartitionType;

pub use monitor::MonitorSession;

pub use monitor::clean_monitor_text;

pub use monitor::drain_utf8_lossy;

pub use monitor::format_monitor_output;

pub use monitor::split_utf8;

pub use port::Port;

pub use port::PortEnumerator;

pub use port::PortInfo;

pub use port::SerialConfig;

pub use protocol::seboot::CommandType;

pub use protocol::seboot::ImageType;

pub use protocol::seboot::SebootAck;

pub use protocol::seboot::SebootFrame;

pub use protocol::seboot::contains_handshake_ack;

Modules

device

Device discovery and classification utilities.

error

Error types for hisiflash.

host

Host-side utilities for serial port discovery.

image

Firmware image formats.

monitor

Native serial monitor primitives.

port

Port abstraction for cross-platform serial communication.

protocol

Protocol implementations.

target

Target-specific implementations.

Structs

CancelContext

Explicit cancellation context for long-running library operations.

Functions

cancel_context_from_global

Create a CancelContext that bridges to the global interrupt flag.

clear_interrupt_flag

Clear the global interrupt flag.

is_interrupted_requested

Returns whether interruption was requested.

set_interrupt_flag

Set the global interrupt flag (for CLI to call when Ctrl-C is received).