Atmosic Zephyr Settings Generator (ZSG) Tool

It is a simple command line utility to generate flash images (in binary format) for the zephyr settings subsystem with NVS backend, currently supports Windows and Linux platforms.

The table below lists the available actions of ZSG. Detailed descriptions of each action can be found in Actions section.

Actions Explanation
-h, --help List available commands
write To generate binary string data to the settings storage area
read Read NVS information from a bin file and save it to a YAML file
show Show NVS information from a bin file

Before You Begin

Before running the ZSG, ensure the following items are prepared:

1. The YAML file to be converted

First, the user needs to create the corresponding YAML file to declare the tag names and tag values included. Based on the different storage partitions, the tag name needs to start with the corresponding subtree. The subtree format is as follows:

  • settings data => SETTINGS/

  • factory data => FACTORY/

For example:

data:
  data_1:
    tag_name: FACTORY/BD_ADDR
    tag_value: 0x123456789ABC
  data_2:
    tag_name: FACTORY/XTAL_CAL
    tag_value: 0x5AA50FF0
  data_3:
    tag_name: FACTORY/VERSION
    tag_value: 1.23

Note

Note: The settings mentioned here refer to the storage_partition and the bin files for the factory and settings partitions are generated separately.

2. Ensure ERASE_BLOCK_SIZE / STORAGE_DATA_SIZE / FACTORY_DATA_SIZE are defined

When generating partition_info.map, the tool determines whether to retrieve Flash or RRAM information from the DTS based on the platform. Those parameters will be extracted using the following keywords respectively.

  • erase-block-size => ERASE_BLOCK_SIZE

  • factory_partition size => FACTORY_DATA_SIZE

  • storage_partition size => STORAGE_DATA_SIZE

For example(DTS/RRAM):

rram_controller: rram-controller@10000 {
compatible = "atmosic,rram-controller";
reg = < 0x10000 0x7f800 >;
rram0: rram@10000 {
   compatible = "soc-nv-flash";
       erase-block-size = < 0x400 >;  // Get erase block size from here
       write-block-size = < 0x1 >;
       reg = < 0x10000 0x7f800 >;
       partitions {
      ....
          factory_partition: partition@cece0050 {
             label = "factory";
             reg = < 0x7e800 0x800 >;  // Get factory partition size from here
          };
          storage_partition: partition@cece0051 {
             label = "storage";
             reg = < 0x7f000 0x800 >;  // Get settings partition size from here
      };
       };
};

For example(partition_info.map):

STORAGE_DATA_START=0x8f000
STORAGE_DATA_OFFSET=0x7f000
STORAGE_DATA_SIZE=0x800
FACTORY_DATA_START=0x8e800
FACTORY_DATA_OFFSET=0x7e800
FACTORY_DATA_SIZE=0x800
....
ERASE_BLOCK_SIZE=0x400

Pass the above parameters into the ZSG tool. The parameter mappings are as follows:

  • partition_sector_size Typically, it is equal to ERASE_BLOCK_SIZE. However, since the number of partition sectors must be at least 2, this size can be at most half of the partition_size.

  • partition_size Depending on the partition storage, provide the corresponding size information. The STORAGE_DATA_SIZE or FACTORY_DATA_SIZE is used here.

3. An attribute YAML file is required when converting a bin file back to a YAML file

When converting a YAML file to a binary file, the Tag Value types will be recorded in [bin_file_name]_attr.yml.

  • The attribute file used when converting settings.bin is named settings_attr.yml.

  • The attribute file used when converting factory.bin is named factory_attr.yml.

Later, if the binary file needs to be converted back to a YAML file, this file will be referenced for the conversion (if the file does not exist, the values will be treated as hexadecimal by default).

For example:

attr:
  data_1:
    tag_name: FACTORY/BD_ADDR
    tag_attr: Hex
  data_2:
    tag_name: FACTORY/XTAL_CAL
    tag_attr: Hex
  data_3:
    tag_name: FACTORY/VERSION
    tag_value: String

Actions

  1. -h, –help

    Show information about all commands.

    Syntax

    zsg [-h | --help]

    Example

    $ zsg --help
Usage: zsg [options]

General Options:
  -h, --help         Show this help message

Input/Output:
  read [bin_file] [FACTORY | SETTINGS] [partition_sector_size] [partition_size] [yaml_output_file]
    Read NVS information from a bin file and save it to a YAML file

  write [yaml_file] [partition_sector_size] [partition_size] [bin_output_file]
    To generate binary string data to the settings storage area

  show [bin_file] [FACTORY | SETTINGS] [partition_sector_size] [partition_size] [show_pretty | show_verbose]
    Display current binary file information

  2. read

    Read NVS information from a bin file and save it to a YAML file (subtree must be provided during execution in order to correctly read the contents of NVS).

    Syntax

    zsg read [bin_file] [SETTINGS | FACTORY] [partition_sector_size] [partition_size] [yaml_file]

    Example

    $ zsg read factory.bin FACTORY 1024 2048 factory.yml  //Read factory data
$ zsg read settings.bin SETTINGS 1024 2048 setting.yml //Read settings data

  3. write

    To generate binary string data to the settings storage area.

    Syntax

    zsg write [yaml_file] [partition_sector_size] [partition_size] [bin_file]

    Example

    $ zsg write factory.yml 1024 2048 factory.bin

  4. show

    Show NVS information from a bin file.

    Syntax

    zsg show [bin_file] [FACTORY | SETTINGS] [partition_sector_size] [partition_size] [show_pretty | show_verbose]

    Example

    $ zsg show factory.bin FACTORY 1024 2048 show_pretty
@001 FACTORY/XTAL_CAL 0x5AA50FF0
@002 FACTORY/BD_ADDR 0x123456789ABC

$ zsg show factory.bin FACTORY 1024 2048 show_verbose
@001 46 41 43 54 4F 52 59 2F 58 54 41 4C 5F 43 41 4C  f0 0f a5 5a
@002 46 41 43 54 4F 52 59 2F 42 44 5F 41 44 44 52  bc 9a 78 56 34 12