.. _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:`Actions <Actions>` 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">Actions</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 binary string data to the settings storage area</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>
      </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

.. _Actions:

Actions
=======

1. **-h, --help**

   Show information about all commands.

   **Syntax**

   .. code-block:: bash

     zsg [-h | --help]

   **Example**

   .. code-block:: bash

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

   .. code-block:: bash

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

   **Example**

   .. code-block:: bash

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

   .. code-block:: bash

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

   **Example**

   .. code-block:: bash

      $ zsg write factory.yml 1024 2048 factory.bin

4. **show**

   Show NVS information from a bin file.

   **Syntax**

   .. code-block:: bash

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

   **Example**

   .. code-block:: bash

      $ 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