.. _west_zsg-tool:

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 :ref:`West zsg command <west_zsg_command>` section.

.. raw:: html

   <div>
      <table style="border-collapse: collapse;width:auto;;border-style:double;font-family: Arial, sans-serif">
         <tr>
            <th style="background-color: #EDEDED;color: rgb(37, 37, 37);padding: 10px;border: 1px solid white !important">Command</th>
            <th style="background-color: #EDEDED;color: rgb(37, 37, 37);padding: 10px;border: 1px solid white !important">Explanation</th>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">-h, --help</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">List available commands</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">write</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">To generate bin and hex file</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">read</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">Read NVS information from a bin file and save it to a YAML file</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">show</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">Show NVS information from a bin file</td>
         </tr>
         <tr>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">dump</td>
            <td style="background-color: white; color: rgb(37, 37, 37); padding: 10px;border: 1px solid black !important">Dump bin file from Device</td>
         </tr>
      </table>
   </div>

|

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:

.. code-block:: bash

  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):

.. code-block:: bash

   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):

.. code-block:: bash

   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:

.. code-block:: bash

   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_command:

West zsg Commands
=================

Use the following command to view usage details:

**Syntax**

.. code-block:: bash

   west zsg --help

**Example**

.. code-block:: bash

   $ 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**

.. code-block:: bash

   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**

.. code-block:: bash

   $ 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**

.. code-block:: bash

   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**

.. code-block:: bash

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

Show NVS information from bin file
----------------------------------

**Syntax**

.. code-block:: bash

   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**

.. code-block:: bash

   $ 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**

.. code-block:: bash

   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 :ref:`board <atmosic_evk>`).
- ``DEVICE_ID`` Serial number of the programmer (see :ref:`serial <atmosic_evk>`).
- ``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

   .. code-block:: bash

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

2. J-Link

   .. code-block:: bash

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