#   ============================================================================
#   @file   README.TXT
#
#   @path   $(DSPLINK)/etc/host/scripts/msdos/loaderutils/static/
#
#   @desc   Contains instructions for usage of loader for DSP executable which
#           is statically linked into the ARM executable.
#
#   @ver    1.65.00.03
#   ============================================================================
#   Copyright (C) 2002-2009, Texas Instruments Incorporated -
#   http://www.ti.com/
#
#   Redistribution and use in source and binary forms, with or without
#   modification, are permitted provided that the following conditions
#   are met:
#   
#   *  Redistributions of source code must retain the above copyright
#      notice, this list of conditions and the following disclaimer.
#   
#   *  Redistributions in binary form must reproduce the above copyright
#      notice, this list of conditions and the following disclaimer in the
#      documentation and/or other materials provided with the distribution.
#   
#   *  Neither the name of Texas Instruments Incorporated nor the names of
#      its contributors may be used to endorse or promote products derived
#      from this software without specific prior written permission.
#   
#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
#   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
#   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
#   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
#   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
#   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
#   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
#   OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
#   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
#   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
#   EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#   ============================================================================


Description:
~~~~~~~~~~~~
The static loader provided with DSP/BIOS LINK allows loading of DSP executable,
which is statically linked into the ARM executable.

The static loader can be used only with the PrOS OS running on the GPP. The TI
CGTOOLS for ARM (TMS470) must be used for building the GPP-side executable.

It is possible to statically link the DSP executable into the ARM executable,
only on platforms where the ARM and DSP memory space is unified, as in the
Davinci platform. When this loader is used, the DSP executable gets
automatically loaded into memory along with the ARM executable.

--------------------------------------------------------------------------------

Sequence of steps for using the static loader:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(Refer to the details for these steps given in later sections.)
1.  Build the GPP-side of DSP/BIOS LINK.
2.  Choose the static loader within the dynamic configuration for DSP/BIOS LINK.
3.  Build the DSP-side of DSP/BIOS LINK.
4.  Build the DSP-side sample application.
5.  Confirm that the paths to tools in staticloader.pl script are correct.
6.  Run the staticloader.pl script to generate required files.
7.  Make the required changes to the GPP-side sample application to use the
    static loader.
8.  Build the GPP-side sample application with the new dynamic configuration.
9.  Make the required changes in build for PrOS GPP-side executable to include
    the files generated by the createimg.pl script.
10. Build the GPP-side PrOS executable.

--------------------------------------------------------------------------------

Choosing the static loader within the dynamic configuration for DSP/BIOS LINK:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. To use the static loader, the appropriate option for the DSP executable
   loader type must be selected within the dynamic configuration.

2. When the static loader is to be used within DSP/BIOS LINK, the DSP object
   configuration within the application's copy of its platform-specific dynamic
   configuration file (copy of CFG_<PLATFORM>.c) must be modified as follows:
   Within the LINKCFG_dspObjects array definition for DSP objects:

   "STATIC",              /* LOADERNAME     : Name of the DSP executable loader */

   This modification plugs the static loader into the DSPLINK loader such that
   the PROC_Load () call eventually passes down into the static loader
   functions.

After this modification, the application's copy of the dynamic configuration
file must be compiled and linked along with the application.

--------------------------------------------------------------------------------

Changes required to applications using the static loader:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some changes are required to applications to be able to use the static loader.
The static loader expects information about the DSP executable file to be
loaded, through the imagePath parameter to the PROC_Load () API:
EXPORT_API
DSP_STATUS
PROC_Load (IN   ProcessorId  procId,
           IN   Char8 *      imagePath,
           IN   Uint32       argc,
           IN   Char8 **     argv) ;

In the normal COFF loader, the imagePath parameter is the path (including file
name) of the DSP executable in the GPP file system.
In case of the static loader, the imagePath parameter is a pointer to a specific
structure STATICLOADER_ImageInfo (defined within loaderdefs.h) expected by the
static loader.

The staticloader.pl script generates a GPP-side 'C' source file, which defines
an instance of this structure. The application must include this file within
its build.

A declaration of this structure is also provided within the generated GPP-side
'H' file by the staticloader.pl script. The application must include this header
file.

The address of the structure is then provided by the application to the
PROC_Load () API as the imagePath parameter.

Arguments to be passed to the main () function in the DSP executable can still
be provided to the PROC_Load () API as with the normal COFF loader.

However, when the static loader is used, only a single DSP executable can be
included in the build of the ARM executable.

--------------------------------------------------------------------------------

Using the staticloader.pl utility with the static loader:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The staticloader.pl utility is provided to simplify usage of the static loader
with user applications.
The staticloader utility generates source and command files corresponding to the
DSP executable to be loaded by the static loader. These generated files can be
statically linked into the ARM-side executable to get a pre-loaded DSP image.

Usage instructions:
  Usage: staticloader.pl <GPP o/p path> <DSP i/p file>
     <GPP o/p path>: Path where GPP-side files should be generated.
     <DSP i/p file>: Name (with path) of input DSP COFF executable.

  Example: Example: staticloader.pl L:\dsplink\gpp\src\samples\message\PrOS L:\dsplink\dsp\export\BIN\DspBios\Davinci\RELEASE\message.out

The files generated are:
1. 'C' file containing an instance of the STATICLOADER_ImageInfo structure
   required by the static loader.
   This generated file can be built with the ARM-side example to generate
   information used by the static loader.
2. 'H' file containing declaration of the instance of the STATICLOADER_ImageInfo
   structure in the 'C' file. This file can be included by the ARM-side
   application using the static loader.
3. 'C' file containing arrays of DSP sections. This file is generated in the
   asp-psp source directory for Davinci, and included in the build.
4. 'CMD' file containing linker placement of the DSP section arrays.
   This file is generated in the asp-psp build directory for Davinci and
   included in the linker command file for the GPP executable.


Changes in build of applications when using the staticloader.pl utility:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The files generated by the staticloader utility must be included in the
build of the ARM executable.
1. The generated GPP-side 'C' file must be included with the build of the
   GPP-side application.
2. The generated 'C' file containing arrays of DSP executable sections must be
   included in the build of the final GPP executable.
3. The generated 'CMD' file must be included in the linker command file used
   for building the GPP-side executable using TI TMS470 CGTOOLS.

--------------------------------------------------------------------------------
