NVM3 Commands#

The Third Generation Non-Volatile Memory (NVM3) module in the Gecko SDK provides a way to store data in non-volatile memory (flash) on EFM32, EFR32, and SiWx91x devices. Refer to UG103.7: Non-Volatile Memory Fundamentals or AN1135: Using Third Generation Non-Volatile Memory (NVM3) Data Storage in Dynamic Multiprotocol Applications for more details on NVM3.

Simplicity Commander supports initializing, modifying, and reading NVM3 from a device.

Initializing and modifying NVM3 data can be applicable on the production line to set an initial state.

Reading out the NVM3 data area from a device and parsing the NVM3 data to extract stored values can be useful in a debugging scenario where you may need to find out the stored state of an application that has been running for some time.

Device Differences#

NVM3 is implemented differently across device families, which leads to different user interfaces in Simplicity Commander.

Series 1 and Series 2 (EFR32/EFM32) Devices#

On these devices, NVM3 is stored unencrypted in flash. Commander can read and write the NVM3 data directly from flash, and all NVM3 processing is done "offline" on the host computer. The commands dump, parse, initfile, and set are suitable for NVM3 manipulation on these devices.

Workflow to Initialize NVM3 on a Blank Device#

  1. Use commander nvm3 initfile to initialize an empty NVM3 area.

  2. Use commander nvm3 set to set NVM3 objects in the file.

  3. Use commander flash to write the NVM3 area with data to the device.

Workflow to Read and Modify NVM3 data on a Device#

  1. Use commander nvm3 dump to find and read NVM3 data from the device.

  2. Use commander nvm3 parse to check the state of NVM3 objects in the file.

  3. Use commander nvm3 set to set or modify NVM3 objects in the file.

  4. Use commander flash to write the modified NVM3 area with data to the device.

Series 3 (SixG3xx) Devices#

On these devices, NVM3 is stored encrypted in flash. The key used for encryption is accessible only by the SE. Therefore, all NVM3 parsing and manipulation must happen on-chip. Simplicity Commander handles this by loading RAM code that performs NVM3 parsing and manipulation. The commands readdevice and writedevice are suitable for NVM3 manipulation on these devices.

Workflow to Initialize NVM3 on a Blank Device#

  1. Use commander nvm3 writedevice to initialize an NVM3 area with data as given by command line options or a text file.

Workflow to Read and Modify NVM3 data on a Device#

  1. Use commander nvm3 readdevice to find and parse NVM3 data on the device.

  2. Use commander nvm3 writedevice to set or modify NVM3 objects on the device.

Dump NVM3 Data From a Device#

This command searches for an NVM3 area in the device's flash and dumps the content to a file in .bin, .s37 or .hex format.

The optional --range parameter can be used to specify the memory range where Simplicity Commander should search for NVM3 data. If no range is given, the entire flash is searched.

This command was named nvm3 read prior to version 1.17.1 of Simplicity Commander. The old command name remains supported as an alias.

Command Line Syntax

$ commander nvm3 dump -o <outfile> [--range <startaddress>:<endaddress>]

Command Line Input Example

$ commander nvm3 dump -o my_nvm3_data.s37

This example scans device flash and searches for a valid NVM3 area. When it is found, the NVM3 area is written to the file named my_nvm3_data.s37.

Command Line Output Example

Reading 24576 bytes from 0x000fa000...
Writing to my_nvm3_data.s37...
DONE

Parse NVM3 Data#

This command takes an image file containing NVM3 data and parses the contents. The parsed NVM3 objects are printed to standard out.

The optional --range parameter can be used to specify the memory range where Simplicity Commander should search for NVM3 data. If no range is given, the entire file is searched.

The optional --key parameter can be used to specify specific NVM3 keys to look up. It can be used multiple times to look up more than one key at a time. Objects with more than eight bytes of data will be truncated when listing all objects. Use the --key parameter to select objects whose data should be displayed.

Command Line Syntax

$ commander nvm3 parse <file> [--range <startaddress>:<endaddress>] [--key <object key>]

Command Line Input Example

$ commander nvm3 parse my_nvm3_data.s37

Scans through the given file and searches for valid NVM3 data. When it is found, the data is parsed and printed to standard out.

Command Line Output Example

Parsing file my_nvm3_data.s37...
Found NVM3 range: 0x000FA000 - 0x00100000
All NVM3 objects:
    KEY -       TYPE -     SIZE - DATA
0x00001 -       Data -      4 B - 2A 00 00 00
0x00002 -       Data -     16 B - 73 36 57 CA 6B CE CF E2 (+ 8 more bytes)
0x00003 -    Counter -      4 B - 2
NVM3 erase count: 1
DONE

Initialize NVM3 Area in a File#

The nvm3 initfile command creates a blank NVM3 area in an image file. For example, this feature is useful to create a file that the nvm3 set command can work on to create a default set of NVM3 data that can be written during production.

The size and location of the NVM3 area must be given and must match the size and location used in the embedded application using the NVM3 area.

Command Line Syntax

$ commander nvm3 initfile --address <location> --size <size in bytes> --device <target device part number> --outfile <image file>

Command Line Input Example

$ commander nvm3 initfile --address 0xfa000 --size 0x6000 --device EFR32MG12P233F1024 --outfile my_nvm3_data.s37

This creates a 24 kB NVM3 area spanning the flash address range 0xfa000 - 0x100000.

Command Line Output Example

Placing NVM3 area at address 0x000fa000
Writing to my_nvm3_data.s37...
DONE

Write NVM3 Data Using a Text File#

The nvm3 set command takes an image file containing an NVM3 data region and sets the value of one or more NVM3 objects. The objects may already exist, in which case the value is updated. If the object does not already exist, it is created. The definition of the data to write can be passed either as a text file (--nvm3file) or as command line parameters (--object and --counter).

The text file passed by the --nvm3file option must have the following format:

  • Each line defines a single object or counter.

  • Empty lines are ignored.

  • Lines starting with # are ignored.

Each line in the file must have the following syntax:

<key>:<type>:<data>

<key> is the NVM3 object key which is the unique identifer used by the embedded application. It has a maximum size of 20 bits (maximum value 0xFFFFF).

<type> is the NVM3 object type. It can be one of two values: OBJ or CNT. OBJ indicates a plain byte array. CNT indicates an NVM3 counter type (32-bit unsigned integer).

<data> is the value the object should be set to. For counter types, the value is interpreted as an unsigned integer which can be prefixed with 0x to indicate a hexadecimal value. Byte arrays are always parsed as hexadecimal and should not be prefixed with 0x.

Example File

0x00001 : OBJ : 01020304AABBCCDD
0x01000 : CNT : 0x80
0x01001 : CNT : 42

This file sets the object with ID 0x1 to be a byte array of eight bytes in length with the contents above.

The object with ID 0x1000 is a counter with value 0x80 (128). The object with ID 0x1001 is a counter with value 42.

Command Line Syntax

$ commander nvm3 set <input image file> --nvm3file <filename> --outfile <image file>

Command Line Input Example

$ commander nvm3 set my_nvm3_data.s37 --nvm3file nvm3_objects.txt --outfile my_modified_nvm3_data.s37

nvm3_objects.txt is parsed for NVM3 objects following the format described above. The given input image file is scanned for a valid NVM3 region. The objects defined in the text file are written into the NVM3 region and the modified output is written to the output image file.

Command Line Output Example

Parsing file my_nvm3_data.s37...
Found NVM3 range: 0x000FA000 - 0x00100000
Setting NVM3 object: 0x00001 = 01020304AABBCCDD
Setting NVM3 counter: 0x01000 = 128 (0x00000080)
Setting NVM3 counter: 0x01001 = 42 (0x0000002a)
Writing to my_modified_nvm3_data.s37...
DONE

Write NVM3 Data Using CLI Options#

In some cases, it may be more convenient to set the NVM3 object data directly from the command line without using a text file. In this instance, use the command line options --object and --counter.

The two options both use the same syntax: <key>:<data>. The definitions of <key> and <data> are the same as in the previous section. The only difference between the two formats is that the <type> field has been removed because it is given by the command line option name instead.

Simplicity Commander automatically finds the correct NVM3_MAX_OBJECT_SIZE based on the given size of NVM3 area.

Command Line Syntax

$ commander nvm3 set <input image file> --object <key>:<data> --counter <key>:<data> --outfile <image file>

Command Line Input Example

$ commander nvm3 set my_nvm3_data.s37 --object 0x1:01020304AABBCCDD --counter 0x1000:0x80 --counter 0x01001:42 --outfile my_modified_nvm3_data.s37

All --object and --counter parameters are parsed according to the format above. The given input image file is scanned for a valid NVM3 region. The objects defined in the text file are written into the NVM3 region and the modified output is written to the output image file.

Command Line Output Example

Parsing file my_nvm3_data.s37...
Setting NVM3 object: 0x00001 = 01020304AABBCCDD
Setting NVM3 counter: 0x01000 = 128 (0x00000080)
Setting NVM3 counter: 0x01001 = 42 (0x0000002a)
Writing to my_modified_nvm3_data.s37...
DONE

Read NVM3 Data From a Series 3 Device#

This command searches for an NVM3 area in the device's flash and parses the contents. The parsed NVM3 objects are printed to standard out.

The options for readdevice are largely the same as for parse.

The optional --range parameter specifies the memory range where Simplicity Commander should search for NVM3 data. If no range is given, the entire flash is searched.

The optional --key parameter specifies NVM3 keys to look up. You can use it multiple times to look up more than one key at a time. Objects with more than eight bytes of data are truncated when listing all objects. Use the --key parameter to select objects whose data should be displayed.

Command Line Syntax

$ commander nvm3 readdevice [--range <startaddress>:<endaddress>] [--key <object key>]

Command Line Input Example

$ commander nvm3 readdevice

This example scans through device flash and searches for a valid NVM3 area. When it is found, RAM code is uploaded to the device, and the data is parsed and printed to standard out.

Command Line Output Example

Found NVM3 range: 0x01377000 - 0x0138f000. Security mode: aead
Uploading RAM code...
Waiting for RAM code to become ready
Opening NVM3...
Getting NVM3 objects...
Closing NVM3...
Resetting device
All NVM3 objects:
    KEY -       TYPE -     SIZE - DATA
0x00001 -       Data -      4 B - 2A 00 00 00
0x00002 -       Data -     16 B - 73 36 57 CA 6B CE CF E2 (+ 8 more bytes)
0x00003 -    Counter -      4 B - 2

NVM3 erase count: 1

DONE

Write NVM3 Data to a Series 3 Device#

On Series 3 devices, nvm3 writedevice replaces nvm3 initfile, nvm3 set, and flashing the result to the device.

The options for writedevice are largely the same as for set. You can use either --nvm3file and/or --object and --counter to specify data to be written. The syntax and details for these options are the same as for the set command as described above.

nvm3 writedevice will search the device for an existing NVM3 area and use that. If no NVM3 area is found, and --range is given to provide a start and end address for NVM3, the NVM3 area is initialized in the given range.

Note: nvm3 writedevice interacts with the NVM3 instance in the device's flash. Take care to either let the app run for long enough to fully initialize its NVM3 area, or let Simplicity Commander initialize the NVM3 area from scratch (i.e., run nvm3 writedevice before flashing the app).

Command Line Syntax

$ commander nvm3 writedevice [--object <key>:<data>] [--counter <key>:<data>] [--nvm3file <filename>]

Command Line Input Example

$ commander nvm3 writedevice --object 0x1:01020304AABBCCDD --counter 0x1000:0x80 --counter 0x01001:42

All --object and --counter parameters are parsed. The device flash is scanned for a valid NVM3 region. RAM code is uploaded to the device. The objects and counters are written into the NVM3 region on the device. Finally, the device is reset.

Command Line Output Example

Setting NVM3 object: 0x00001 = 01020304AABBCCDD
Setting NVM3 counter: 0x01000 = 128 (0x00000080)
Setting NVM3 counter: 0x01001 = 42 (0x0000002a)
Found NVM3 range: 0x01377000 - 0x0138f000. Security mode: aead
Uploading RAM code...
Waiting for RAM code to become ready
Opening NVM3...
Writing data to NVM3...
Closing NVM3...
Resetting device
DONE