.. _sysconfig-genMap:

GenMap
======

GenMap is a feature of SysConfig which allows for the generation of linker command
file definitions (e.g. memory maps) and symbols suitable for inclusion in custom
linker command files.

While GenMap is intentionally an optional feature, TI's examples leverage it to
improve their ability to migrate between devices, and remove hard-coded values
that may otherwise require managing in multiple places.

Using GenMap linker definitions
-------------------------------

SysConfig will now generate config- and device-related linker definitions
in a new file named ``ti_utils_build_linker.cmd.genmap``.  This file will
be created in the standard SysConfig output directory (e.g.
``{PROJECT_LOC}/{TARGET_CONFIGURATION}/syscfg`` when using CCS).

A user is able to include the ``ti_utils_build_linker.cmd.genmap`` in their
application's linker command file in order to reference the definitions within.

By default, the SDK examples include a linker file (with extension ``*.cmd`` for
CCS, ``*.icf`` for IAR and ``*.ldf`` for GCC) which includes the ``ti_utils_build_linker.***.genmap`` file
(where \*\*\* is the appropriate extension for the toolchain being used)  and uses the definitions
contained in the genmap.

The code snippet below shows how the genmap file may be included and how the
definitions may be used in a linker file.

.. code-block:: none
    :caption: **ti_utils_build_linker.cmd.genmap** include and usage example
    
    ...
    /* Including genmap file */
    #include "ti_utils_build_linker.cmd.genmap"
    ...
    /* Using genmap definitions in linker file */
    #define FLASH_BASE              ti_utils_build_GenMap_FLASH0_BASE
    #define FLASH_SIZE              ti_utils_build_GenMap_FLASH0_SIZE
    #define RAM_BASE                ti_utils_build_GenMap_RAM0_BASE
    #define RAM_SIZE                ti_utils_build_GenMap_RAM0_SIZE
    ...

