Support metadata like the TinyFPGA Bootloader

[mithro]

It would be good to support / have the same style of board metadata that the TinyFPGA board does.

See below;

FPGA Board Metadata

Each FPGA board implementing the TinyFPGA USB Bootloader may have different locations for the bootloader image, user image, user data, and other information. These differences are driven by the FPGA's multi-boot capabilities/requirements and the size of the FPGA configuration image.

In order for a common bootloader and programmer application to program user images and user data to the correct locations, the programmer must know where these locations are in the SPI flash. It is also useful to identify the board with a name and unique serial number. This information along with other required and optional metadata is stored in the non-volatile security register pages of the SPI flash and optionally in the main SPI flash memory.

The programmer application will search security register pages 0-3 for valid metadata. The metadata is stored in JSON format. JSON was choosen because it is compact enough, is well understood, and easier to read and understand than a binary format.

Below is an example of how the metadata may be structured and formatted for the TinyFPGA BX board:

SPI Flash Security Register Page 1 (write-protected)

One of the SPI flash security register pages contains fixed data about the board that does not change. This is the name of the board, the hardware revision of the board, and serial number unique to the board name. This security register page should be write protected as it should never be changed. If the rest of the SPI flash is erased, this minimal amount of information will help the user to find recovery instructions.

{"boardmeta":{
  "name": "TinyFPGA BX",
  "fpga": "ice40lp8k-cm81",
  "hver": "1.0.0",
  "serial": 10034
}}

SPI Flash Security Register Page 2 (not write-protected)

A seperate SPI flash security register page should contain or point to information that can change. This includes the bootloader version number, update URL for new bootloader releases for this board, and an address map for the SPI flash that describes where the bootloader, user image, and user data belong. Using this information the programmer application is able to discover where to put new user images and data without any input from the user or built-in knowledge about the board. It makes the board plug-and-play.

Optionally, an additional desc.tgz file may be included in the SPI flash itself, or on the update page. This desc.gz file contains the information necessary to develop with the board. At a minimum it describes the FPGA name, package, and a mapping from FPGA pins to board IOs and peripherals.

{"bootmeta": "@0xFF000+445"}

SPI Flash Memory Address 0xFF000

{
  "bootloader": "TinyFPGA USB Bootloader",
  "bver": "2.0.0",
  "update": "https://tinyfpga.com/update/tinyfpga-bx",
  "addrmap": {
    "bootloader": "0x00000-0x2FFFF",
    "userimage":  "0x30000-0x4FFFF",
    "userdata":   "0x50000-0xFBFFF",
    "desc.tgz":   "0xFC000-0xFFFFF"
  }
}

A detailed explanation of the metadata structure will be added here.

[mithro]

@xobs Does the Fomu SPI flash have these flash security register pages?