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 West zsg command section.

Command Explanation
-h, --help List available commands
write To generate bin and hex file
read Read NVS information from a bin file and save it to a YAML file
show Show NVS information from a bin file
dump Dump bin file from Device

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

West zsg Commands

Use the following command to view usage details:

Syntax

west zsg --help

Example

$ west zsg --help
usage: west zsg [-h] {write,read,show,dump} ...

Atmosic zsg tool required files and info

positional arguments:
  {write,read,show,dump}
                        sub-command to run
    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
    dump                Dump bin file from device

options:
  -h, --help            show this help message and exit

Generate bin and hex file

Syntax

west zsg write [-h] -p PARTITION_FILE -i INPUT_FILE -o OUTPUT_FILE -t PARTITION_TYPE [-obj OBJCOPY_FILE] [--hex]

Required parameters:

  • PARTITION_FILE Partition_info.map file path

  • PARTITION_TYPE Type of Zephyr subsystem storage (e.g., factory or settings).

  • INPUT_FILE Input file path(yaml file)

  • OUTPUT_FILE Output file file(bin file)

  • hex Convert the bin file to hex

  • OBJCOPY_FILE Objcopy exe file path(This parameter is required if conversion to HEX is needed).

Example

$ west zsg write -i factory.yml -o factory.bin -p partition_info.map -obj C:/atmoa/toolchains/25.07.0/zephyr-sdk/arm-zephyr-eabi/bin/arm-zephyr-eabi-objcopy.exe -t factory --hex

Read bin file and save it to a YAML file

Syntax

west zsg read [-h] -p PARTITION_FILE -i INPUT_FILE -o OUTPUT_FILE -t PARTITION_TYPE

Required parameters:

  • PARTITION_FILE Partition_info.map file path

  • PARTITION_TYPE Type of Zephyr subsystem storage (e.g., factory or settings).

  • INPUT_FILE Input file path(bin file)

  • OUTPUT_FILE Output file file(yaml file)

Example

$ west zsg read -i factory.bin -o factory.yml -p partition_info.map -t factory

Show NVS information from bin file

Syntax

west zsg show [-h] -p PARTITION_FILE -i INPUT_FILE -t PARTITION_TYPE -s {show_verbose,show_pretty}

Required parameters:

  • PARTITION_FILE Partition_info.map file path

  • PARTITION_TYPE Type of Zephyr subsystem storage (e.g., factory or settings).

  • INPUT_FILE Input file path(bin file)

  • [show_pretty | show_verbose] Display output using the specified style

Example

$ west zsg show -i factory.bin -p partition_info.map -t factory -s 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

$ west zsg show -i factory.bin -p partition_info.map -t factory -s show_pretty
@001 FACTORY/XTAL_CAL 0x5AA50FF0
@002 FACTORY/BD_ADDR 0x123456789ABC

Dump bin file from device

Syntax

west zsg dump [-h] -p PARTITION_FILE [--jlink] --device DEVICE_ID --board BOARD [--openocd_config OPENOCD_CONFIG] -o OUTPUT_FILE -t PARTITION_TYPE

Required parameters:

  • PARTITION_FILE Partition_info.map file path

  • PARTITION_TYPE Type of Zephyr subsystem storage (e.g., factory or settings).

  • OUTPUT_FILE Output file file(bin file)

  • BOARD Atmosic device (see board).

  • DEVICE_ID Serial number of the programmer (see serial).

  • OPENOCD_CONFIG Specifies the config file for openocd

Note

--jlink Specify if using a J-Link interface. If omitted, the FTDI interface is assumed.

Example

  1. FTDI

    $ west zsg dump --device ATRDI2727 --board ATMEVK-3330e-QN-7 -p partition_info.map -t factory -o dump_factory.bin

  2. J-Link

    $ west zsg dump --device 900039052 --board ATMEVK-3330e-QN-7 --jlink -p partition_info.map -t factory -o dump_factory.bin