Skip to content

Latest commit

 

History

History
182 lines (139 loc) · 9.74 KB

Kboot.md

File metadata and controls

182 lines (139 loc) · 9.74 KB
Raw

Kboot

Kboot is a small applications (< 8KB) which enables loading and executing applications from any K210 SPI Flash location.

Features

  • Load and execute K210 application stored at any location in SPI Flash.
  • Application to be loaded is chosen from the list of available applications in Kboot configuration sector.
  • Multiple criteria application validity check is performed when selecting the application.
  • If no valid application is found default application is loaded and executed.
  • The interactive mode can be enabled in which, based on the specific Pin state, the user can choose which application to load and execute from the list of found applications.

K210 Boot process when using kboot

  • After reset, the 1st part (stage #0) of Kboot application is loaded by K210 ROM to SRAM address 0x80000000 and executed.
  • SPI Flash driver is initialized in XiP mode.
  • The 2nd part (stage #1) of Kboot application is loaded to high SRAM address 0x805E0000 and the execution is continued fram that address.
  • If allowed by configuration, Boot Pin state is checked and saved
    If Boot Pin is activated (pulled to GND) interactive mode is enabled.
  • Configuration sector is scanned for valid applications.
    Following actions are performed:
    • Configuration entry ID is checked
    • Application Flash address is cheched for valid range
    • Application size is checked for valid range
    • If Size flag is set, application size is checked agains the acctual size written in application's Flash block.
    • Application flags are saved
    • Application Flash block * is checked for valid format
    • If CRC32 flag is set, application's crc32 is calculated and checked
    • If SHA256 flag is set, application's SHA256 hash is calculated and checked
  • If no valid application is found, the backup configuration sector is scanned.
  • If all checks passes, the application is marked as valid.
  • If not in interactive mode, configuration sector scan is terminated as soon as the first valid, flagged as active application is found and that application is loaded and executed.
  • If in interactive mode, all configuration sector entries are scanned and the user is prompted to select which one to load and execute.
  • If no valid application is found, the default application is loaded and executed
  • If the default application fails the application test, the system is halted

* each application stored in SPI Flash has the following format:

Byte offset Size Name Content
0 1 AES_FLAG AES cipher flag, for use with Kboot must be 0
1 4 APP_SIZE Application code size
5 APP_SIZE APP_CODE Application code
APP_SIZE + 5 32 SHA_HASH Application SHA256 hash

All applications flashed with ktool.py or kflash.py have such format.


K210 SPI Flash layout

The following SPI Flash layout must be used when using *Kboot

From To Length Comment
0x00000000 0x00000FFF 4K 1st part of Kboot application, stage #0 code
0x00001000 0x00003FFF 12K 2nd part of Kboot application, stage #1 code
0x00004000 0x00004FFF 4K main boot configuration sector
0x00005000 0x00005FFF 4K backup boot configuration sector
0x00006000 0x0000FFFF 40K reserved, user data etc.
0x00010000 DEF_APP_END --- default application code
>DEF_APP_END FLASH_END --- user area, application(s) code, file system(s), user data etc.

Boot configuration sector

Boot configuration used by Kboot is stored in one SPI Flash sector (4KB) at fixed Flash address (0x00004000).
One backup configuration sector is also used for security reasons, stored in one SPI Flash sector (4KB) at fixed Flash address (0x00005000).

The configuration sector consists of 8 application entries occupying 32 bytes each.
After the last application entry the config flags entry is placed, one 32bit value.

Configuration sector layout:

Offset To Length Comment
0x000 01F 32 application entry #0
0x020 03F 32 application entry #1
0x040 05F 32 application entry #2
0x060 07F 32 application entry #3
0x080 09F 32 application entry #4
0x0A0 0BF 32 application entry #5
0x0C0 0DF 32 application entry #6
0x0E0 0FF 32 application entry #7
0x100 103 4 config flags
0x104 11F 4 reserved
0x120 11F 4 not used, user data

The format of each application entry in configuration sector is as follows:

Offset Length Comment
0 4 Configuration entry ID (bits 4-31) + entry flags (bits 0-4)
4 4 Application address in SPI Flash
8 4 Application size in SPI Flash. This is the size of the application's .bin file
12 4 Application's CRC32 value (32bits)
16 16 Null terminated application name or description

Notes:
Configuration entry ID must have a value of 0x5AA5D0C0 for entry to be recognized as valid.
Application addres must be in range 0x10000 ~ 0x800000 ( 64KB ~ 8MB ).
Application size must be in range 0x4000 ~ 0x300000 ( 16KB ~ 3MB ).
Application CRC32 value is used only if CRC32 flag is set.

If config flags at offset 0x100 in configuration sector is set to configuration entry ID (0x5AA5D0C0), interractive mode will be disabled, *boot Pin will not be checked and nothing will be printed during the boot process. Configuration entry flags:

Bit Comment
0 Active flag, if set the application will be loaded and executed.
If multiple entries have active flag set, the first one will be loaded ad executed
1 CRC32 flag, if set the application's CRC32 value will be calculated and compared with the value in the configuration entry
2 AES256 flag, if set the application's AES256 hash value will be calculated and compared with the value stored in flash after the application code (SHA_HASH)
3 Size flag, if set the application size specified in configuration entry must match the application size present in application's Flash block

Warning: all 32-bit values in the configuration sector entries must be written in big-endian format.


Default application

If in the boot process no valid application was found in the configuration sector, the default application is loaded and executed.
The default application should try to check if loading it was intended or it was result of an error condition, in which case it should try to correct the issue.


Building the applications to be used with Kboot

Nothing special must be done to build the applications which are going to be used with Kboot.
All applications built with Kendryte Standalone SDK or FreeRTOS SDK should run without issues.

The application can check if the Kboot system is used by reading the 2nd SPI Flash sector (at address 0x1000).
At offset 0x09 the Kboot id string is positioned: Kboot_v1.4.1 (version mumbers may be different).

[00001000] 00 B0 1F 00 00 6F 00 40 01 4B 62 6F 6F 74 5F 76 31 2E 34 2E 31 00 00 00 00 19 71 86 FC A2 F8 A6 
[00001020] F4 CA F0 CE EC D2 E8 D6 E4 DA E0 5E FC 62 F8 66 F4 6A F0 6E EC F3 27 40 F1 81 27 17 27 00 00 23

See the note about sector data!



Usage

Flashing the application(s) to SPI Flash and manipulating the boot configuration sector should be performed from the user application.
Accessing SPI flash from K210 application is quite easy and reliable.

Example

Application firmware update

  • The condition to update the firmware is detected by the application
  • Load the boot configuration sector, check its integrity and check the flash address and size of the currently running application
  • Flash the new firmware to the not used SPI Flash area. The new firmware can be downloaded from remote server using WiFi or GSM, loaded from SD Card, etc ...
    Use the application block format described above.
    The application can be flashed without SHA256 hash, in that case do not set the SHA256 flag.
  • Calculate new firmware's CRC32 and/or SHA256 hash if needed.
  • Flash the current main boot configuration sector to the backup boot configuration sector and check it.
    It will be used by Kboot in case the main boot configuration sector which we are going to write is corrupted.
  • Update (add or change entry) in the boot configuration sector with the new firmware information, set the new firmware as active and the old firmware as inactive and flash the configuration sector.
  • Reset (reboot) the system to start the new firmware.

Important Notes

When reading sectors written with ktool.p< or kflash.py from SPI Flash in normal mode (not using XiP mode), the sector data may look corrupted.
The reason is that all sector data are written with swapped 32-bit values (32-bit big endian format is used).
To correct this, you should swap endianess of all 32-bit values in the sector, something like this:.

uint8_t buf4[4];
for (int k=0; k<4096; k+=4) {
    buf4[0] = sector[k+0];
    buf4[1] = sector[k+1];
    buf4[2] = sector[k+2];
    buf4[3] = sector[k+3];
    sector[k+0] = buf4[3];
    sector[k+1] = buf4[2];
    sector[k+2] = buf4[1];
    sector[k+3] = buf4[0];
}