Skip to content
/ ktool Public

A Python-based cross-platform Kendryte K210 UART ISP Utility, enhanced kflash.py

License

Notifications You must be signed in to change notification settings

loboris/ktool

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

About

A Python-based cross-platform Kendryte K210 UART ISP Utility, enhanced kflash.py

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

Packages

No packages published