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
        }
    ]
}