====================
Tool: mp_objdump2dma
====================

--------
Overview
--------

Objdump to DMA tool provides a command-line interface (CLI)
to interpret objdump outputs and generate the corresponding DMA file. DMA
file format is a simple format that specifies contents for each address
of memory. E.g. each line of the file contains ``D <address> <contents>``. 
This format is used during early stages of bring-up and characterization to 
set up the contents of the processors cache directly, without requiring a
fully operational system.   

-----------
Basic usage
-----------

::

   > mp_objdump2dma -i OBJDUMP_FILE -O DMA_OUTPUT_FILE

where:

=============================================================== =================================================================
Flag/Argument                                                   Description
=============================================================== =================================================================
``-i OBJDUMP_FILE``, ``--input-objdump-file OBJDUMP_FILE``      Objdump file generated with Objdump (see details in the following section)
``-O DMA_OUTPUT_FILE``, ``--dma-output-file DMA_OUTPUT_FILE``   Output file name
=============================================================== =================================================================

------------------------------
How to obtain an objdump file?
------------------------------

**objdump** (part of the GNU Binutils) is a program for displaying various 
information about object files. An object file is a file containing object 
code, meaning relocatable format machine code that is usually not directly 
executable. There are various formats for object files, and the same object 
code can be packaged in different object files. In addition to the object code 
itself, object files may contain metadata used for linking or debugging, 
including: information to resolve symbolic cross-references between different 
modules, relocation information, stack unwinding information, comments, program
symbols, debugging or profiling information.
Consequently, **objdump** can be used as a disassembler to view an executable 
in assembly form. More details 
`on the wikipedia webpage <https://en.wikipedia.org/wiki/Objdump>`_.

The command to get an dump of a binary using **objdump** is the 
following::

   > objdump -D -z your_binary_file > mydump.dump
   
the ``-D`` flag forces the tool to dump also the data sections (not
only the executable ones) and the ``-z`` flag instructs the tool to dump 
everything (long regions of zero values are typically excluded). 

.. note:: 

   Only dumps from GNU Binutils **objdump** and dumps generated by Microprobe
   itself are currently supported.
   
----------
Full usage
----------

.. program-output:: ../../targets/generic/tools/mp_objdump2dma.py --help

---------------
Example outputs
---------------

.. rubric:: Example 1:

Command::

   > mp_objdump2dma.py -O output.dma -i input.objdump  
   
Input file ``input.objdump``:

.. literalinclude:: ./examples/example_mp_objdump2mpt.dump
    :linenos:
 
Output file ``output.dma``:

.. literalinclude:: ./examples_outputs/example_mp_objdump2dma.dma
    :linenos:
 
