1. Overview
This note describes how to use the SPI Flash with the Thingy-9151-Lite platform.
2. Hardware Implementation
As documented in Emcraft Thingy-9151-Lite Platform Data Sheet , the Thingy-9151-Lite provides a 32MB SPI Flash connected to the nRF9151 MCU.
Relevant hardware implementation details are as follows:
32MB SPI Flash using the GD25WB256E device
Connected to the SPI3 controller of the nRF9151 MCU
P0.20 pin on the nRF9151 MCU controller used as a CS (Chip Select)
SPI is configured to run at 8 MHz.
3. Software Interfaces
3.1. SPI Flash Device Driver
There is a generic jedec,spi-nor driver in Zephyr that is used to handle SPI Flash devices compatible with the JESD216 JEDEC standard. This driver operates as a middleware between an underlying driver for the SoC-specific SPI controller and the low-level Flash API.
The driver is available when the SPI_NOR configuration parameter is enabled in the build-configuration. The level of auto-configuration is selected with the SPI_NOR_SFDP parameter:
SPI_NOR_SFDP | |
|---|---|
| Synthesise a minimal configuration assuming 256 By page size and standard 4 KiBy and 64 KiBy erase instructions. Requires the |
| The JESD216 Basic Flash Parameters table must be provided in the |
| Read all flash device characteristics from the device at runtime. This option is the most flexible as it should provide functionality for all supported JESD216-compatible devices. |
For the full list of driver parameters available in the device tree, refer to https://docs.zephyrproject.org/latest/build/dts/api/bindings/mtd/jedec%2Cspi-nor.html#std-dtcompatible-jedec-spi-nor
3.1. Support for QSPI Flash
Note that the jedec,spi-nor driver runs on top of the SPI driver, so the DSPI and QSPI features are not supported by this solution. For some Nordic chips (nRF5340 in particular), there is a nordic,qspi-nor driver that supports operating in QSPI mode, with its own set of flash parameters. nordic,qspi-nor is not affected by SPI_NOR_SFDP, all required parameters need to be supplied in the device tree node.
3.2. Software APIs
There are several API levels that allow access to SPI Flash.
3.2.1. Low Level Flash Access
This level can be used to access SPI Flash as a raw Flash device.
The following calls are the core for the Flash API defined in zephyr/include/zephyr/drivers/flash.h:
__syscall const struct flash_parameters *flash_get_parameters(const struct device *dev);
__syscall size_t flash_get_write_block_size(const struct device *dev);
/* access functions */
__syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
__syscall int flash_write(const struct device *dev, off_t offset,
const void *data,
size_t len);
__syscall int flash_read(const struct device *dev, off_t offset, void *data,
size_t len);
/* specific to SPI flash, if supported by driver and enabled by CONFIG_FLASH_JESD216_API */
__syscall int flash_read_jedec_id(const struct device *dev, uint8_t *id);
__syscall int flash_sfdp_read(const struct device *dev, off_t offset,
void *data, size_t len);
There are more to the Flash API’s, please refer to Zephyr documentation https://docs.zephyrproject.org/latest/hardware/peripherals/flash.html for details.
There are also the zephyr/samples/drivers/jesd216 and zephyr/samples/drivers/spi_flash demos that demonstrate use of low-level API.
3.2.2. Flash Partitioning
Zephyr additionally has API’s that can be used to partition SPI Flash. The goal is to provide a facility to split a single Flash device into several named areas to be used independently and preventing out-of-bounds access.
There is a predefined Flash map that is created from the “fixed-partition” compatible entries in the DTS file. Internally, each Flash area is described with a descriptor, providing: offset, length, underlying flash driver. Those descriptors are identified by globally unique ID numbers. To obtain the ID from the device tree label for “fixed-partition” use the FIXED_PARTITION_ID() macro.
It is also possible to create Flash partitions at the runtime.
The following functions are the core of Flash area API defined in zephyr/include/zephyr/storage/flash_map.h
int flash_area_open(uint8_t id, const struct flash_area **fa);
void flash_area_close(const struct flash_area *fa);
int flash_area_erase(const struct flash_area *fa, off_t off, size_t len);
int flash_area_write(const struct flash_area *fa, off_t off, const void *src,
size_t len);
int flash_area_read(const struct flash_area *fa, off_t off, void *dst,
size_t len);
Refer to Zephyr documentations https://docs.zephyrproject.org/latest/services/storage/flash_map/flash_map.html for details. Note that when using multi-image builds, the Nordic SDK overrides the partitions defined in the device tree with Partition Manager .
The zephyr/samples/subsys/fs/littlefs sample illustrates use of a fixed partition to create a file system over it. mcuboot is another useful example.
3.2.3. High-Level Non-Volatile API
There are several high-level storage API’s provided by Zephyr that can be used over Flash (or a Flash area):
https://docs.zephyrproject.org/latest/services/storage/nvs/nvs.html can be used to store elements, represented as id-data pairs.
https://docs.zephyrproject.org/latest/services/storage/fcb/fcb.html provides an abstraction through which you can treat Flash like a FIFO.
https://docs.zephyrproject.org/latest/services/storage/stream/stream_flash.html module takes contiguous fragments of a stream of data (e.g. from radio packets), aggregates them into a user-provided buffer, then when the buffer fills (or stream ends), writes it to a raw Flash partition.
https://docs.zephyrproject.org/latest/services/file_system/index.html allow to have several independent file systems.
See samples/fs/littlefs, samples/subsys/usb/mass for an example of how to use filesystem over SPI Flash.
In the nrf-app application use the CONFIG_PM_PARTITION_REGION_LITTLEFS_EXTERNAL, CONFIG_PM_PARTITION_REGION_SETTINGS_STORAGE_EXTERNAL, and CONFIG_PM_PARTITION_REGION_NVS_STORAGE_EXTERNAL to relocate corresponding partition to SPI Flash.
3.3. Zephyr Shell Commands
The nrf-app application comes preconfigured to use SPI Flash, with support for the relevant Zephyr shell commands enabled. The following shell commands are available:
erase [<device>] <page address> [<size>] read [<device>] <address> [<Dword count>] test [<device>] <address> <size> <repeat count> write [<device>] <address> <dword> [<dword>...] load [<device>] <address> <size> page_info [<device>] <address> read_test [<device>] <address> <size> <repeat count> write_test [<device>] <address> <size> <repeat count> erase_test [<device>] <address> <size> <repeat count> erase_write_test [<device>] <address> <size> <repeat count>
In the above, [<device>] is an optional Flash device name (as given in the device tree). If not present, value of zephyr,flash in the choosen node will be used.
When specifying the <address> and <size> values, use an 0x prefix for hexadecimal values. <size> for test operations is limited by the CONFIG_FLASH_SHELL_BUFFER_SIZE parameter and defaults to 0x4000.
The following procedures can be used to verify raw Flash access. Note, that the low-level API is used in the example, which can destroy any available partition data:
Run a generic erase/write/read/compare test:
uart:~$ flash test gd25wb256e3ir@1 0 0x4000 1 Erase OK. Write OK. Verified OK. Erase-Write-Verify test done.
Run read and write measurements:
uart:~$ flash erase gd25wb256e3ir@1 0 0x4000 Erase success. uart:~$ flash write_test gd25wb256e3ir@1 0 0x4000 1 Loop #1 done in 53 ticks. Total: 53ms, Per loop: ~53ms, Speed: ~301.9KiBps uart:~$ flash read_test gd25wb256e3ir@1 0 0x4000 1 Loop #1 done in 16ms. Total: 16ms, Per loop: ~16ms, Speed: ~1000.0KiBps
3.4. Configuring for a Different SPI Flash Device
This chapter explains how to configure a different Flash device. Specifically, the GD25WB256E Flash device installed on the Thingy-9151-Lite platform is used as an example.
3.4.1. Get JEDEC info
First step when setting a new SPI Flash is to obtain information about it. To do so, we need to create a minimally required description of the Flash. Let’s start with the following overlay:
&arduino_spi {
newspi: newdevice@1 {
compatible = "jedec,spi-nor";
status = "ok";
reg = <1>;
spi-max-frequency = <8000000>;
jedec-id = [c8 65 19];
size = <0x400000>;
};
};
/ {
aliases {
spi-flash0 = &newspi;
};
};
We’re adding new device newdevice@1 at address 1(match CS used for the chip) and create label to refer to it newspi. compatibleand status fields select driver and mark device as present. reg field specifies CS for our SPI device. spi-max-frequency, jedec-id and size (in bits!) can easily be obtained from SPI flash datasheet. spi-max-frequency may be lower than maximum value specified in datasheet and size does not have to be correct at this point, just be correctly aligned, so driver does not refuse configuration.
Now go to zephyr/samples/drivers/jesd216, put the fragment above into boards/nrf9161dk_nrf9161.overlay and build sample using west:
$ cd zephyr/samples/drivers/jesd216
$ cat >boards/nrf9161dk_nrf9161.overlay <<EOF
&arduino_spi {
newspi: newdevice@1 {
compatible = "jedec,spi-nor";
status = "ok";
reg = <1>;
spi-max-frequency = <8000000>;
jedec-id = [c8 65 19];
size = <0x400000>;
};
};
/ {
aliases {
spi-flash0 = &newspi;
};
};
EOF
$ west build -b nrf9161dk_nrf9161 -d build_an -p
If the build finish successfully, there will be build_an/zephyr/zephyr.hex that can be installed and run on target. Here’s example output after running:
*** Booting nRF Connect SDK v2.5.1-7-g76a2a1188200 *** newdevice@1: SFDP v 1.6 AP ff with 3 PH PH0: ff00 rev 1.6: 16 DW @ 30 Summary of BFP content: DTR Clocking not supported Addressing: 3- or 4-Byte 4-KiBy erase: uniform Support QSPI XIP Support 1-1-1 Support 1-1-2: instr 3Bh, 0 mode clocks, 8 waits Support 1-1-4: instr 6Bh, 0 mode clocks, 8 waits Support 1-2-2: instr BBh, 2 mode clocks, 2 waits Support 1-4-4: instr EBh, 2 mode clocks, 4 waits Flash density: 33554432 bytes ET1: instr 20h for 4096 By; typ 80 ms, max 800 ms ET2: instr 52h for 32768 By; typ 256 ms, max 2560 ms ET3: instr D8h for 65536 By; typ 304 ms, max 3040 ms Chip erase: typ 60928 ms, max 487424 ms Byte program: type 80 + 5 * B us, max 640 + 40 * B us Page program: typ 512 us, max 4096 us Page size: 256 By Suspend: 75h ; Resume: 7Ah DPD: Enter B9h, exit ABh ; delay 40000 ns ; poll 0x01 HOLD or RESET Disable: unsupported QER: 7 0-4-4 Mode methods: entry 0x4 ; exit 0x01 4-4-4 Mode sequences: enable 0x00 ; disable 0x0 4-byte addressing support: enter 0x01, exit 0x001 Soft Reset and Rescue Sequence support: 0x10 Status Register 1 support: 0x08 size = <268435456>; sfdp-bfp = [ e5 20 f3 ff ff ff ff 0f 44 eb 08 6b 08 3b 42 bb ee ff ff ff ff ff 00 ff ff ff 00 ff 0c 20 0f 52 10 d8 00 ff 44 7a c9 fe 83 67 26 62 ec 82 18 44 7a 75 7a 75 04 c4 d5 5c 00 06 74 00 08 50 00 01 ]; PH1: ffc8 rev 1.0: 3 DW @ 90 sfdp-ffc8 = [ 00 36 50 16 9d f9 77 64 fc cb ff ff ]; PH2: ff84 rev 1.0: 2 DW @ c0 sfdp-ff84 = [ ff 0e f0 ff 21 5c dc ff ]; jedec-id = [c8 65 19];
Now, we can replace size line in our flash descriptor in the overlay with value obtained from SFDP by this sample. We can also copy sfdp-bfp value from output: it may be needed if SPI_NOR_SFDP_DEVICETREE is used in the configuration. As line starting with DPD: indicates, hardware supports DPD using B9h and ABh commands and time to wake up is 40000 ns. Unfortunately time to enter DPD can only be obtained from datasheet (usually tDP). Add has-dpd, t-enter-dpd and t-exit-dpd. Now we can finalize flash description in the overlay:
/* Deactivate predefined flash node for SPI flash installed on DK */
&gd25wb256 {
status = "disable";
};
&arduino_spi {
/* Insert node for new device */
newspi: newdevice@1 {
compatible = "jedec,spi-nor";
status = "ok";
reg = <1>;
spi-max-frequency = <8000000>;
jedec-id = [c8 65 19];
size = <268435456>;
has-dpd;
t-enter-dpd = <3000>;
t-exit-dpd = <40000>;
sfdp-bfp = [
e5 20 f3 ff ff ff ff 0f 44 eb 08 6b 08 3b 42 bb
ee ff ff ff ff ff 00 ff ff ff 00 ff 0c 20 0f 52
10 d8 00 ff 44 7a c9 fe 83 67 26 62 ec 82 18 44
7a 75 7a 75 04 c4 d5 5c 00 06 74 00 08 50 00 01
];
};
};
/* Use new device in choosen and aliases */
/ {
chosen {
nordic,pm-ext-flash = &newspi;
};
aliases {
spi-flash0 = &newspi;
ext-flash = &newspi;
};
};
3.4.2. Configuring for different SPI flash device with QSPI support on nRF5340 (nordic,qspi-nor)
The nRF5340 MCU includes a QSPI controller that allows to use faster flash devices in dual and quad SPI mode.
Following the similar procedure to SPI flash discussed above, jedec216 provides the following output:
*** Booting nRF Connect SDK v3.5.99-ncs1-1-8-g04e7e56b7fed ***
mx25r6435f@0: SFDP v 1.6 AP ff with 3 PH
PH0: ff00 rev 1.6: 16 DW @ 30
Summary of BFP content:
DTR Clocking not supported
Addressing: 3-Byte only
4-KiBy erase: uniform
Support QSPI XIP
Support 1-1-1
Support 1-1-2: instr 3Bh, 0 mode clocks, 8 waits
Support 1-1-4: instr 6Bh, 0 mode clocks, 8 waits
Support 1-2-2: instr BBh, 0 mode clocks, 4 waits
Support 1-4-4: instr EBh, 2 mode clocks, 4 waits
Flash density: 8388608 bytes
ET1: instr 20h for 4096 By; typ 48 ms, max 384 ms
ET2: instr 52h for 32768 By; typ 240 ms, max 1920 ms
ET3: instr D8h for 65536 By; typ 480 ms, max 3840 ms
Chip erase: typ 52000 ms, max 312000 ms
Byte program: type 32 + 1 * B us, max 192 + 6 * B us
Page program: typ 896 us, max 5376 us
Page size: 256 By
Suspend: B0h ; Resume: 30h
DPD: Enter B9h, exit ABh ; delay 40000 ns ; poll 0x3d
HOLD or RESET Disable: unsupported
QER: 2
0-4-4 Mode methods: entry 0x9 ; exit 0x2f
4-4-4 Mode sequences: enable 0x00 ; disable 0x0
Soft Reset and Rescue Sequence support: 0x10
Status Register 1 support: 0x70
size = <67108864>;
sfdp-bfp = [
e5 20 f1 ff ff ff ff 03 44 eb 08 6b 08 3b 04 bb
ee ff ff ff ff ff 00 ff ff ff 00 ff 0c 20 0f 52
10 d8 00 ff 23 72 f5 00 82 ed 04 cc 44 83 48 44
30 b0 30 b0 f7 c4 d5 5c 00 be 29 ff f0 d0 ff ff
];
PH1: ffc2 rev 1.0: 4 DW @ 110
sfdp-ffc2 = [
00 36 50 16 9d f9 c0 64 fe cf ff ff ff ff ff ff
];
PH2: ff84 rev 1.0: 2 DW @ c0
sfdp-ff84 = [
00 00 f0 ff ff ff ff ff
];
jedec-id = [c2 28 17];
spi-max-frequency, jedec-id, sfdp-bfp, size, has-dpd, t-enter-dpd and t-exit-dpd are determined similarly to SPI case. However nordic,qspi-nor requires additional parameters to enable quad mode:
quad-enable-requirementsdefines method to enable quad mode and can be determined from line starting withQER:in the output
|
|
|---|---|
0 |
|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
readocandwriteocdefine command and mode used during quad access:
Mode | Write instruction | Read Instruction |
|
|
|---|---|---|---|---|
1-1-1 | 0x02 | 0x0B |
|
|
1-1-2 | 0xA2 | 0x3B |
|
|
1-2-2 | 0xBB |
| ||
1-1-4 | 0x32 | 0x6B |
|
|
1-4-4 | 0x38 | 0xEB |
|
|
For both parameters yellow lines indicate values not supported by nordic,qspi-nor.
For the device used in this test, both 1-1-4 and 1-4-4 modes are available, but 1-4-4 is slightly faster, so it will be selected. Final device tree entry:
mx25r64: mx25r6435f@0 {
compatible = "nordic,qspi-nor";
reg = < 0x0 >;
writeoc = "pp4io";
readoc = "read4io";
quad-enable-requirements = "S1B6";
sck-frequency = < 8000000 >;
jedec-id = [ C2 28 17 ];
sfdp-bfp = [ E5 20 F1 FF FF FF FF 03 44 EB 08 6B 08 3B 04 BB
EE FF FF FF FF FF 00 FF FF FF 00 FF 0C 20 0F 52
10 D8 00 FF 23 72 F5 00 82 ED 04 CC 44 83 68 44
30 B0 30 B0 F7 C4 D5 5C 00 BE 29 FF F0 D0 FF FF ];
size = < 0x4000000 >;
has-dpd;
t-enter-dpd = < 10000 >;
t-exit-dpd = < 35000 >;
};