Ktool

Ktool is the enhanced version of Kendryte kflash.py utility.

It is compatible with kflash.py but introduces many new features and enhancement.

Full sources of the enhanced 2nd stage ISP are available in this repository's src/isp directory.
More information about 2nd stage ISP and build instructions are available in the build directory.

How it works

On start, K210 board is reset into bootloader ISP mode (running from K210 ROM) by holding the K210 IO16 low and asserting the reset pin.
After reset, if IO16 is low, K210 executes the 1st stage ISP from ROM.
1st stage ISP is only capable of loading K210 program to the requested SRAM address and execute it.
After the communication with the 1st stage ISP is established, ktool.py uploads the 2nd stage ISP to the K210 SRAM (at address 0x805E0000) and executes it.
All further communication is performed via 2nd stage ISP

Features:

Compatible with standard kflash.py, the same command line options are supported (but more are added)
Uses highly optimized 2nd stage ISP binary which loads in less than a second and supports many new features
Write firmware or data to any SPI Flash address
Write firmware/data using also 4K chunks and 4K alignment
(kflash.py always writes 64K chunks and the firmware address must be 64KB aligned)
Read Flash content to file is supported
Erase the SPI Flash chip
Reports SPI Flash chip manufacturer's JEDEC ID, 64-bit unique serial number and size
Optionally swap endianess on data write (useful when writing some kind of data, for example file system images)
Load the firmware to K210 SRAM end execute it.
Loading is done by the 2nd stage ISP and can be performed at any baudrate supported by the board.
It is now possible to load and start large firmwares at high speed...
(kflash.py supports this function, but loading to SRAM is done at 115200 baud, making it impractical for larger firmwares)

Standard command line arguments:

Argument	Description
`-h` `--help`	Show help message and exit
`-v` `--version`	Print version and exit
`-p PORT` `--port PORT`	Communication port used to connect to the K210 board If not given, automatic port detection is atempted
`-b BAUDRATE` `--baudrate BAUDRATE`	UART baudrate used for for communication with 2nd stage ISP. Communication with 1st stage ISP is always performed at `115200` Bd. default: `115200`
`-l ISP_BIN` `--bootloader ISP_BIN`	2nd stage ISP binary file name. External ISP binary is usually used only for testing. If not given, internal ISP binary is used (recommended)
`-k KEY` `--key KEY`	AES key in hex, if you need to encrypt the firmware. There is no documentation about how it works, it probably requires some programming of K210 OTP memory, firmware flashed with this option will not start If not given, no AES encription is used
`-t` `--terminal`	Open terminal emulator (default: `miniterm`) after the operation is finished default: `False`
`-n` `--noansi`	Do not use ANSI colors, recommended when ANSI colors are not supported (for example in Windows Command prompt) default: `False`
`-B BOARD` `--Board BOARD`	Select the board to which you are trying to connect Different boards my have different reset to bootloader requirements. If not given automatic board detection is atempted, which usually works good Supported: `ḋan`, `bit`, `trainer`, `kd233`, `goE`, `goD` default: `None`
`--verbose`	Increase output verbosity; default: `False`; not used
`-S` `--Slow`	Slow download mode; default: `False`; not used
`firmware`	The only positional argument, usually given after all other arguments Name of the file containing firmware or other data to be flashed to K210 SPI Flash Name of the firmware file to be loaded to K210 SRAM and executed Not needed for erase operation, optional for read operation The file may contain binary firmware/data, firmware ELF file or kfpkg package (see below)

New and changed command line arguments:

Argument	Description
`-a ADDRESS` `--address ADDRESS`	Flash address at which the firmware/data will be written for Flash write operations Flash address from which the data will be read for Flash read operations integer, can be given as decimal or hex number default: `0`
`-E` `--erase`	Erase the whole flash chip Be carefull!
`-L` `--rdlen`	The length of data to be read from Flash integer, can be given as decimal or hex number default: `0`
`-R` `--read`	Read data from Flash address specified by `--address` The data will be saved to the `firmware` name specified in command line default: `"flash_dump.bin"`
`--swapendian`	Swap endianess when writing the data. It may be necessary when writing some kind of data, for example file system image default: `False`
`-s` `--sram`	Download firmware to K210 SRAM and boot Loading is done by the 2nd stage ISP and can be performed at any baudrate supported by the board default: `False` `kflash.py` supports this function, but loading to SRAM is done at `115200` baud, making it impractical for larger firmwares
`--termbdr BAUDRATE`	UART baudrate used for for terminal emulator default: `115200`
`--nosha`	Flash without firmware prefix and SHA suffix Used when flashing data which is not executable firmware default: `False`
`-T` `--onlyterm`	Do not perform any operation, only start the terminal emulator default: `False`
`--reset`	Reset the board before running terminal emulator, used only with `--onlyterm` option default: `False`

kfpkg package

kfpgk package is a ZIP archive containing several firmware or data binary files and a json file describing its content.
It is convenient to use it when multiple files must be flashed at different Flash addresses and with different options.

ktool.py can proces this file, unpack the content and perform the necessary operations.

The package must contain the JSON file named flash-list.json which describes which files are to be flashed and how.

The following objects must be present to describe each file under files object:

Key	Value description
`address`	integer; Flash address at which the file content will be written
`bin`	string; Name of the file containing firmware/data to be flashed
`sha256Prefix`	boolean if `true` flash with firmware prefix and SHA suffix (flash the executable firmware) if `ḟalse` flash without firmware prefix and SHA suffix (data)
`swap`	boolean, may be omitted, if not present defaults to `false` If `true`, swap endianess when writing the data. It may be necessary when writing some kind of data, for example file system image

Examples of `flash-list.json`

{
    "version": "0.1.0",
    "files": [
        {
            "address": 0,
            "bin": "MicroPython.bin",
            "sha256Prefix": true,
            "swap": false
        },
        {
            "address": 5242880,
            "bin": "MicroPython_lfs.img",
            "sha256Prefix": false,
            "swap": true
        }
    ]
}

{
    "version": "0.1.1",
    "files": [
        {
            "address": 0,
            "bin": "bootloader_lo.bin",
            "sha256Prefix": true
        },
        {
            "address": 4096,
            "bin": "bootloader_hi.bin",
            "sha256Prefix": true
        },
        {
            "address": 16384,
            "bin": "config.bin",
            "sha256Prefix": false
        },
        {
            "address": 20480,
            "bin": "config.bin",
            "sha256Prefix": false
        }
    ]
}

loboris/ktool