xous-core/docs/flash.md

FLASH memory layout

Xous is designed to operate from a SPI FLASH filesystem. The key properties assumed of the underlying implementation are as follows:

• XIP-capable
• Memory-mapped
• 4kiB erase sectors (same as page size)
• Transparent bad block mechanism
• ~100k erase/program cycles per sector

The FLASH memory used in the Precursor implementation is a Macronix MX66UM1G45G, which is a 128MiB part, upgradable to higher capacities.

In Precursor, FLASH memory is located at a base of 0x2000_0000, which is the constant HW_SPIFLASH_MEM in the utra, and the length is coded as HW_SPIFLASH_MEM_LEN.

Below is a map of the FLASH memory. For completeness, note that the hardware boots from location 0x0000_0000, from 32kiB a non-Xous boot ROM that is compiled into the FPGA binary image itself. This ROM currently consists of just a few instructions to jump to the Xous loader, but eventually this will need to house the code that does public key signature verification of the Xous kernel itself before jumping to it.

Also note that main SRAM is, by default, battery-backed, so during shutdown, the RAM image stays resident. This means no space is allocated in FLASH for hibernation or standby.

Finally, everything in the memory layout up until the PDDB is considered to be largely static data, only written during firmware and software updates. Therefore, no provision exists for sector-sparing or weare levelling; we instead rely on the 100k-cycle write endurance of the underlying hardware. The PDDB itself will have to implement some form of wear leveling, however.

+-----------+----------------------------------------+
+ 2000_0000 |   Primary FPGA bitstream               |
+ 2021_7287 |   2,192,008 bytes                      |
+-----------+----------------------------------------+
+ 2021_7288 |   Padding                              |
+ 2027_7FFF |                                        |
+-----------+----------------------------------------+
+ 2027_8000 |   csr.csv corresponding to bitstream   |
+ 2027_FFFF |   (32kiB max, see below)               |
+-----------+----------------------------------------+
+ 2028_0000 |   Reserved for backup bitstream        |
+ 204F_FFFF |                                        |
+-----------+----------------------------------------+
+ 2050_0000 |   loader.bin - Xous loader             |
+ 2050_FFFF |                                        |
+-----------+----------------------------------------+
+ 2051_0000 |   Font planes                          |
+ 2097_FFFF |                                        |
+-----------+----------------------------------------+
+ 2098_0000 |   Xous kernel plus                     |
+ 20AF_FFFF |   Initial/trusted server set           |
+-----------+----------------------------------------+
+ 20B0_0000 |   Reserved                             |
+ 20CF_FFFF |                                        |
+-----------+----------------------------------------+
+ 20D0_0000 |   PDDB 'filesystem'                    |
+ 27F7_FFFF |                                        |
+-----------+----------------------------------------+
+ 27F8_0000 |   512k reserved space for EC image     |
+ 27FF_FFFF |   Split into 300k wf200 + 200k EC fw   |
+-----------+----------------------------------------+

The csr.csv block is further structured as follows:

+-----------+----------------------------------------+
+ 2027_8000 |   Length of csr.csv data               |
+ 2027_8003 |   4 bytes, little-endian               |
+-----------+----------------------------------------+
+ 2027_8004 |   csr.csv data (variable length)       |
+ 2027_8xxx |   Typically ~12kiB, byte ordered       |
+-----------+----------------------------------------+
+ 2027_8xxx |   padding to 0xFF                      |
+ 2027_FFBF |   padding included in sha512           |
+-----------+----------------------------------------+
+ 2027_FFC0 |   sha512 of 2027_8000:2027_FFBF        |
+ 2027_FFFF |   64 bytes, network order              |
+-----------+----------------------------------------+

Testing Structures

Prior to the creation of the PDDB, some hard-coded audio data is loaded for development purposes.

This documents their location in FLASH. The samples are shorter than the allocated regions, but the WAV headers encode their actual lenth.

+-----------+----------------------------------------+
+ 2600_0000 |   8khz short sample (WAV/<512kiB)      |
+ 2607_FFFF |   16-bit stereo PCM ~16s long          |
+-----------+----------------------------------------+
+ 2608_0000 |   44.1khz short sample (WAV/<2,816kiB) |
+ 2633_FFFF |   16-bit stereo PCM ~16s long          |
+-----------+----------------------------------------+
+ 2634_0000 |   8khz short sample (WAV/<28,928kiB)   |
+ 2707_FFFF |   16-bit stereo PCM ~330s long         |
+-----------+----------------------------------------+
+ 27F8_0000 |   Start of EC region (do not use)      |
+-----------+----------------------------------------+