.. _west_dump-tool:

Atmosic Dump Tool
#################

It is a simple command line utility to dump flash images (in binary format) from Atmosic device, currently supports Windows and Linux platforms.

.. _west_dump_command:

West dump Commands
==================

Use the following command to view usage details:

**Syntax**

.. code-block:: bash

   west dump --help

**Example**

.. code-block:: bash

   $ west dump --help
   usage: west dump [-h] [--jlink] [--dl] [--rram] --device DEVICE --board BOARD [--openocd_config OPENOCD_CONFIG] -o
                    OUTPUT_FILE --start_addr START_ADDR --size SIZE [--offset_addr OFFSET_ADDR]

   Dump binary data from device

   options:
     -h, --help            show this help message and exit
     --jlink               if using JLINK
     --dl                  if using DL Board
     --rram                if using RRAM
     --device DEVICE       selects FTDI interface, e.g: ATRDIxxxx, or JLINK, or ATMDLxxxx
     --board BOARD         board to build for with optional board revision
     --openocd_config OPENOCD_CONFIG
                           Specifies the config file for openocd
     -o OUTPUT_FILE, --output_file OUTPUT_FILE
                           output file path
     --start_addr START_ADDR
                           start address to dump data from
     --size SIZE           size of data to dump
     --offset_addr OFFSET_ADDR
                           offset address of output file

Dump bin file from device
-------------------------

**Syntax**

.. code-block:: bash

   west dump [-h] [--jlink] [--dl] [--rram] --device DEVICE_ID --board BOARD [--openocd_config OPENOCD_CONFIG] -o OUTPUT_FILE --start_addr START_ADDR --size SIZE [--offset_addr OFFSET_ADDR]

Required parameters:

- ``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.
- ``OFFSET_ADDR`` Specify the offset address for padding the output file. When set, ``OFFSET_ADDR`` bytes of 0xFF padding are prepended to the dumped data, ensuring the binary file layout aligns with the memory layout. Supports both hexadecimal (e.g., 0x200000) and decimal (e.g., 2097152) formats.
- ``START_ADDR`` Start address to dump data from (in hexadecimal, e.g., 0x200000).
- ``SIZE`` Size of data to dump (in hexadecimal, e.g., 0x1000).

.. note::
  ``--jlink`` Specify if using a **J-Link** interface. If omitted, the **FTDI** interface is assumed.
  ``--dl`` Specify if using a **Download Board (DL)** interface.
  ``--rram`` Specify if want to dump **RRAM**.


**Example (Dump Flash Memory)**

1. FTDI Interface Board (Flash)

   .. code-block:: bash

      $ west dump --device ATRDI2727 --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x200000 --size 0x1000

   This dumps 4KB (0x1000 bytes) of flash memory starting from address 0x200000.

2. FTDI Download Board (Flash)

   .. code-block:: bash

      $ west dump --device ATMDL220600000123 --dl --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x200000 --size 0x1000

   This dumps 4KB of flash memory from a Download Board (DL) interface.

3. J-Link (Flash)

   .. code-block:: bash

      $ west dump --device 900039052 --jlink --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x200000 --size 0x1000

   This dumps 4KB of flash memory using J-Link interface.

4. Flash Dump with Offset Address

   .. code-block:: bash

      $ west dump --device ATRDI2727 --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x200000 --size 0x1000 --offset_addr 0x200000

   When ``--offset_addr`` is specified, 0xFF padding bytes are prepended to the dumped data.
   This ensures the binary file layout aligns with the memory layout (e.g., layout.info).

   In this example:

   - Data dumped from device: 0x1000 bytes starting at address 0x200000
   - Padding prepended: 0x200000 bytes of 0xFF
   - Total output file size: 0x200000 + 0x1000 = 0x201000 bytes
   - The data from device address 0x200000 will be at file offset 0x200000

**Example (Dump RRAM Memory)**

1. FTDI Interface Board (RRAM)

   .. code-block:: bash

      $ west dump --device ATRDI2727 --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x8f000 --size 0x800 --rram

   This dumps 2KB (0x800 bytes) of RRAM starting from address 0x8f000.

2. FTDI Download Board (RRAM)

   .. code-block:: bash

      $ west dump --device ATMDL220600000123 --dl --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x8f000 --size 0x800 --rram

   This dumps 2KB of RRAM from a Download Board (DL) interface.

3. J-Link (RRAM)

   .. code-block:: bash

      $ west dump --device 900039052 --jlink --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x8f000 --size 0x800 --rram

   This dumps 2KB of RRAM using J-Link interface.

4. RRAM Dump with Offset Address

   .. code-block:: bash

      $ west dump --device ATRDI2727 --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x8f000 --size 0x800 --rram --offset_addr 0x8f000

   Similar to flash dumps, when ``--offset_addr`` is specified for RRAM:

   - Data dumped from device: 0x800 bytes starting at address 0x8f000
   - Padding prepended: 0x8f000 bytes of 0xFF
   - Total output file size: 0x8f000 + 0x800 = 0x8f800 bytes
   - The RRAM data from device address 0x8f000 will be at file offset 0x8f000 in the output file

Understanding offset_addr Parameter
-----------------------------------

The ``--offset_addr`` parameter is useful when you want the dumped binary file to maintain the same memory layout as the device by prepending 0xFF padding bytes.

**Without offset_addr:**

.. code-block:: bash

   $ west dump --device ATRDI2727 --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x200000 --size 0x1000

- Dumps 0x1000 bytes starting from device address 0x200000
- Output file size: 0x1000 bytes (4KB)
- Data from device address 0x200000 is at file offset 0x0
- File structure: ``[0x1000 bytes of dumped data]``

**With offset_addr:**

.. code-block:: bash

   $ west dump --device ATRDI2727 --board ATMEVK-3330e-QN-7 -o dump.bin --start_addr 0x200000 --size 0x1000 --offset_addr 0x200000

- Dumps 0x1000 bytes starting from device address 0x200000
- Prepends 0x200000 bytes of 0xFF padding
- Output file size: 0x200000 + 0x1000 = 0x201000 bytes (~2MB)
- Data from device address 0x200000 is at file offset 0x200000
- File structure: ``[0x200000 bytes of 0xFF padding] + [0x1000 bytes of dumped data]``
- File layout matches device memory layout

**Offset Address Format:**

The ``--offset_addr`` parameter supports both hexadecimal and decimal formats:

- Hexadecimal: ``--offset_addr 0x200000`` (2,097,152 bytes)
- Decimal: ``--offset_addr 2097152`` (same as above)

**Use Case:**

This is particularly useful when:

- Comparing dump files with memory layout files (e.g., layout.info)
- Analyzing multiple memory regions while preserving their relative positions
- Using tools that expect the binary file to match the device memory map
- Debugging memory-mapped peripherals or specific memory regions
- Creating binary images that can be directly compared with device memory maps