.. program:: xobjdump

.. _xobjdump_manual:

XOBJDUMP
========

Synopsis
--------

| :command:`xobjdump [OPTIONS] xe-file`

Description
-----------

The xobjdump tool is used to examine and manipulate the contents of :ref:`XMOS Executable
(XE)<xe_format>` files.

Options
-------

.. option:: --help

   Display a summary of the available options.

.. option:: --version

   Display the build version information.

.. option:: --sector-info

   Lists the contents or 'sectors' of the .xe file.

.. option:: --strip

   Creates a new XE file with suffix .xb in which the ELF sectors containing ELF files have been replaced with BINARY sectors containing flat binary images and a 'load address' at which to place them.

   Also removes the SYSCONFIG sector.

   XE files generated by this option retain the same format and can therefore be further manipulated by xobjdump.

.. option:: --split, -s

   Extracts ELF, BINARY, SYSCONFIG, XN, PROGINFO and XSCOPE sectors from the XE package and writes them as files in the current directory. 
   Specifically:

   .. list-table::
      :widths: 20 80
      :header-rows: 1

      * - Sector type
        - Default generated filename
      * - ELF
        - :file:`image_n{<node>}c{<tile>}.elf`
      * - BINARY
        - :file:`image_n{<node>}c{<tile>}.bin`
      * - SYSCONFIG
        - :file:`config.xml`
      * - XN
        - :file:`platform_def.xn`
      * - PROGINFO
        - :file:`program_info.txt`
      * - XSCOPE
        - :file:`xscope.xscope`

   Where a sector exists with duplicate <node> and <core> value to a sector previously extracted (which will often be the case), the extracted filename will have an incrementing id added. For instance, the first ELF sector on node 0, tile 0 will be extracted as :file:`image_n0c0.elf`. The second ELF sector on node 0, tile 0 will be extracted as :file:`image_n0c0_2.elf`.

.. option:: --split-dir

   If :option:`--split` is set, then extracts sectors into the directory <dir>. The directory must already exist.

.. option:: -o <file>

   When used with :option:`--split`, causes ELF sectors to be extracted to :file:`{<file>}_n{<node>}c{<tile>}.elf`.

   When used with :option:`--strip`, new XE file is given name :file:`{<file>}`.

.. option:: --disassemble, -d

   Disassembles contents of all executable sectors in XE file

.. option:: --source, -S

   Same as :option:`--disassemble`, but interleaves source code into disassembly output. Requires source to have been built with :option:`xcc -g`.

.. option:: --disassemble-all, -D

   Same as :option:`--disassemble`, but also provides binary contents of non-executable data sections.

Readelf-alike options
^^^^^^^^^^^^^^^^^^^^^

The following options all have more powerful alternatives that rely on the generally available `readelf <https://linux.die.net/man/1/readelf>`_ tool.

.. option:: --syms, -t

   Provides the symbol table for every ELF sector in the XE file.

   More powerful example: Use :option:`xobjdump --split` to obtain all the ELF files, then issue :command:`readelf --syms *.elf`.

.. option:: --size

   Provides a summary of the code and data (both initialised and uninitialised) requirements for every ELF sector in the XE file. 

   More powerful example: Use :option:`xobjdump --split` to obtain all the ELF files, then issue :command:`readelf --sections *.elf`.