
Usage
=====

The primary entry point for use of ``fpvgcc`` is as a console script. The
``fpvgcc`` console entry point supports a variety of analysis functions, each
of which essentially recasts the information contained in the provided mapfile
in a different way.

Script usage and arguments are listed here. This help listing can also be
obtained on the command line with ``fpvgcc --help``.

.. argparse::
    :module: fpvgcc.cli
    :func: _get_parser
    :prog: fpvgcc
    :nodefault:

The various available analysis functions are described below. Additional
analysis may be possible using changes to the code and/or direct manipulation
of the parsed memory map in the python interpreter / shell, and is not covered
in this documentation.

Memory Utilization Summaries
----------------------------

These functions print out a concise summary of memory utilization.

.. rubric:: --sar

Prints out a summary of memory utilization per library archive file, sorted by
the total static memory footprint of each file. Object files which were included
directly show up here as object files.

.. code-block:: console

    $ fpvgcc app.map --sar
    +-----------------------------------+--------+--------+----------+------+------+-------+-------+
    | FILE                              | VECT47 | VECT57 | RESETVEC |  ROM |  RAM | HIROM | TOTAL |
    +-----------------------------------+--------+--------+----------+------+------+-------+-------+
    | TOTALS                            |      2 |      2 |        2 | 6588 | 1222 |     0 |       |
    | libmodbus-msp430f5529.a           |      0 |      0 |        0 | 2594 |  360 |     0 |  2954 |
    (...)                             (...)                        (...)                       (...)
    | crtend.o                          |      0 |      0 |        0 |   36 |    2 |     0 |   38  |
    | crtn.o                            |      0 |      0 |        0 |   12 |    0 |     0 |   12  |
    | libprintf-msp430f5529.a           |      0 |      0 |        0 |    0 |    0 |     0 |   0   |
    | libmul_f5.a                       |      0 |      0 |        0 |    0 |    0 |     0 |   0   |
    +-----------------------------------+--------+--------+----------+------+------+-------+-------+

.. rubric:: --sobj ARFILE

Prints out a summary of memory utilization per object file, sorted by the total
static memory footprint of each file.

The ``ARFILE`` specified should be one of the following :

    - ``all`` : All object files included
    - An archive file : Object files provided by that archive file are only listed

.. code-block:: console

    $ fpvgcc app.map --sobj libc.a
    +-----------------+--------+--------+----------+-----+-----+-------+-------+
    | OBJFILE         | VECT47 | VECT57 | RESETVEC | ROM | RAM | HIROM | TOTAL |
    +-----------------+--------+--------+----------+-----+-----+-------+-------+
    | TOTALS          |      0 |      0 |        0 |  96 |   0 |     0 |       |
    | lib_a-memmove.o |      0 |      0 |        0 |  58 |   0 |     0 |   58  |
    | lib_a-memcpy.o  |      0 |      0 |        0 |  20 |   0 |     0 |   20  |
    | lib_a-memset.o  |      0 |      0 |        0 |  18 |   0 |     0 |   18  |
    +-----------------+--------+--------+----------+-----+-----+-------+-------+

.. rubric:: --ssym FILE

Prints out a summary of memory utilization per symbol, sorted by the total
static memory footprint of each symbol.

The ``FILE`` specified should be one of the following :

    - ``all`` : All symbols included
    - An object file : Symbols provided by that object file are only listed
    - An archive file : Symbols provided by that archive file are only listed

.. code-block:: console

    $ fpvgcc app.map --ssym libc.a
    +-----------------+--------+--------+----------+-----+-----+-------+-------+
    | SYMBOL          | VECT47 | VECT57 | RESETVEC | ROM | RAM | HIROM | TOTAL |
    +-----------------+--------+--------+----------+-----+-----+-------+-------+
    | TOTALS          |      0 |      0 |        0 |  96 |   0 |     0 |       |
    | memmove         |      0 |      0 |        0 |  58 |   0 |     0 |   58  |
    | memcpy          |      0 |      0 |        0 |  20 |   0 |     0 |   20  |
    | memset          |      0 |      0 |        0 |  18 |   0 |     0 |   18  |
    | lib_a-memset_o  |      0 |      0 |        0 |   0 |   0 |     0 |   0   |
    | lib_a-memmove_o |      0 |      0 |        0 |   0 |   0 |     0 |   0   |
    | lib_a-memcpy_o  |      0 |      0 |        0 |   0 |   0 |     0 |   0   |
    +-----------------+--------+--------+----------+-----+-----+-------+-------+

.. rubric:: --ssec

Prints out a summary of memory utilization per object file, per section.

The --ssec output can get pretty garbled very easily. The table that it results
in is simply far too large (wide), and each line overflows (wraps) into a
number of lines with even a slightly non-trivial program.

It exists because at some point in the distant future, when I have the time,
I would want to put in a web or desktop UI which would be able to handle the
details, with baobab or filelight as a model of what I would want it to
look and feel like.

As it stands, the per-section split of memory utilization is rarely useful.
I would recommend using the other more compact and useful outputs instead,
starting with --sar followed by --ssym all.

Pull requests which imrprove the output of print_sectioned_fp() of cli.py are
always welcome.


Linker Map Nodes
----------------

These functions print out a (relatively) concise version of all linker map
nodes satisfying certain criteria. The output contains all nodes satisfying the
given criteria, including those in DISCARDED sections.

.. rubric:: --lmap ROOT

Prints out all linker map nodes which are apparant descendents of the given
root node. The ``ROOT`` node **must** be provided.

If ROOT is 'root', i.e., the root node of the entire linker map, the output
contains all the top level nodes (first children of 'root') of the linker map,
and only the top level nodes.

For all other provided nodes, the output contains all descendents.

.. code-block:: console

    $ fpvgcc app.map --lmap root
    .__interrupt_vector_1.......................................                                                 UNDEF
    (...)
    .__interrupt_vector_47......................................0x0000ffdc              2         2         2    VECT47         uart_handlers.c.obj
    (...)
    .__reset_vector.............................................0x0000fffe              2                   2    RESETVEC
    .rodata.....................................................0x00004400            234                 234    ROM
    (...)
    .bss........................................................0x00002414           1202                1202    RAM
    (...)
    .lowtext....................................................0x00004550            102                 102    ROM
    .text.......................................................0x00005cca           6172                6172    ROM            slli.o
    (...)

.. code-block:: console

    $ fpvgcc app.map --lmap .lowtext
    .lowtext....................................................0x00004550            102                 102    ROM
    .lowtext.crt_0000start......................................0x00004550                        4         4    ROM            crt0.o
    .lowtext.crt_0100init_bss...................................0x00004554                       14        14    ROM            crt_bss.o
    .lowtext.crt_0300movedata...................................0x00004562                       20        20    ROM            crt_movedata.o
    .lowtext.crt_0700call_init_then_main........................0x00004576                       10        10    ROM            crt_main.o
    .lowtext.crt_0900main_init..................................0x00004580                       54        54    ROM            crt0.o

.. rubric:: --lobj OBJFILE

Prints out all linker map nodes that originated from the specified object file.

.. code-block:: console

    $ fpvgcc app.map --lobj crt_bss.o
    .lowtext.crt_0100init_bss...................................0x00004554                       14        14    ROM            crt_bss.o
    .MSP430.attributes.crt_bss_o................................0x00000353                       23        23    DISCARDED      crt_bss.o

.. rubric:: --lar ARFILE

Prints out all linker map nodes that originated from the specified library
archive file.

.. code-block:: console

    $ fpvgcc app.map --lar libc.a
    .text.memcpy................................................0x00005d3e                       20        20    ROM            lib_a-memcpy.o
    .text.memset................................................0x00005d52                       18        18    ROM            lib_a-memset.o
    .text.memmove...............................................0x00005d64                       58        58    ROM            lib_a-memmove.o
    .MSP430.attributes.lib_a-memcpy_o...........................0x0000030e                       23        23    DISCARDED      lib_a-memcpy.o
    .MSP430.attributes.lib_a-memset_o...........................0x00000325                       23        23    DISCARDED      lib_a-memset.o
    .MSP430.attributes.lib_a-memmove_o..........................0x00000398                       23        23    DISCARDED      lib_a-memmove.o
    .comment.lib_a-memcpy_o.....................................0x00000041                       66        66    DISCARDED      lib_a-memcpy.o
    .comment.lib_a-memset_o.....................................0x00000041                       66        66    DISCARDED      lib_a-memset.o
    .comment.lib_a-memmove_o....................................0x00000041                       66        66    DISCARDED      lib_a-memmove.o


Reverse Address Lookup
----------------------

Given a memory location / address, this function can be used to quickly
determine what exists there. It is expected that this will be useful when
looking through generated assembly listings.

Example:

.. code-block:: console

    $ fpvgcc app.map --addr 0x242e
    .bss........................................................0x00002414           1202                1202    RAM
    .bss.privateXT1ClockFrequency...............................0x0000242e                        4         4    RAM            ucs.c.obj
    $ fpvgcc app.map --addr 0x475d
    .text.clock_set_default.....................................0x000046ce                      144       144    ROM            core_impl.c.obj


Other Information
-----------------

.. rubric:: --lfa

Prints a list of all loaded files. These are all the files that were provided
to the linker. It is not necessary that all of these files have found their way
into the output.

Example :

.. code-block:: console

    $ fpvgcc app.map --lfa
    ../peripherals/libhal-uc-core-msp430f5529.a
    (...)
    /opt/ti/msp430/gcc/bin/../lib/gcc/msp430-elf/5.3.0/../../../../msp430-elf/lib/crt0.o
    (...)
    /opt/ti/msp430/gcc/bin/../lib/gcc/msp430-elf/5.3.0/crtbegin.o
    (...)
    /opt/ti/msp430/gcc/bin/../lib/gcc/msp430-elf/5.3.0/crtend.o
    (...)
    CMakeFiles/firmware-msp430f5529.elf.dir/main.c.obj
    (...)


.. rubric:: --uf

Prints out a list of input files which have non-zero footprint in the output.
If any of the used object files came from a library archive, then only the
library archive is listed. If the object files were used directly, then the
object file is listed. All elements in the output are necessarily represented
by some file in this list, and all these files probably exist(ed) somewhere
in the build tree at the link-time.

.. code-block:: console

    $ fpvgcc app.map --uf
    crt0.o
    libucdm-msp430f5529.a
    (...)
    main.c.obj

.. rubric:: --uarf

Prints out a list of input library archives (.a/.ar) which have non-zero
footprint in the output. Any elements from object files which were used
directly are not represented in this output.

.. code-block:: console

    $ fpvgcc app.map --uarf
    libc.a
    libcrt.a
    libgcc.a
    libhal-uc-core-msp430f5529.a
    (...)

.. rubric:: --uobjf

Prints out a list of input object files (.out) which have non-zero
footprint in the output. All elements in the output are necessarily
represented by some file in this list, though remember that some of
these object files actually exist inside library archives.

.. code-block:: console

    $ fpvgcc app.map --uobjf
    _ashldi3.o
    _clz.o
    _clzdi2.o
    _lshrdi3.o
    _muldi3.o
    _udivdi3.o
    bytebuf.c.obj
    core_impl.c.obj
    crt0.o
    (...)

.. rubric:: --uregions

Prints out a list of used memory regions.

.. code-block:: console

    $ fpvgcc app.map --uregions
    HIROM
    RAM
    RESETVEC
    ROM
    VECT47
    VECT57

.. rubric:: --usections

Prints out a list of used memory sections.

.. code-block:: console

    $ fpvgcc app.map --usections
    .__interrupt_vector_47
    .__interrupt_vector_57
    .__reset_vector
    .bss
    .data
    .lowtext
    .rodata
    .rodata2
    .text

.. rubric:: --la

Prints out a list of detected / assumed section aliases.

.. code-block:: console

    $ fpvgcc app.map --la
    __TI_build_attributes -> .MSP430.attributes
    .gnu.attributes -> .MSP430.attributes
    __interrupt_vector_rtc -> .__interrupt_vector_42
    __interrupt_vector_port2 -> .__interrupt_vector_43
    (...)
