
LYRTECH EVMUPDATER V1.3.1.0
---------------------------



1-Introduction
  ------------

This program allows to burn a file in evm internal flash memory (32 MBytes). It can be used in 3 differents
modes:

Mode I)   Application mode (easy direct burning of a dsp .out executable file)
Mode II)  Binary mode (burning of any binary file or AIS file)
Mode III) Binary in compilation mode (burning of any binary file compiled with evmupdater library)

Mode I and II ask user with a prompt for the filename/options, mode III burns the compiled file without asking
any prompt from the user.

In mode I, it will burn a ".out" dsp program file directly to flash without any other manipulation (adding a
small Lyrtech bootloader to bootload the application before running it). This is the easiest mode to use, and
will allow to burn a small user application without the need to create a custom bootloader.

In mode I, this flash burner will take care of default dsp initialization needed to run the program
(what is usually done by the GEL file). It is mainly used to burn the default evm post (Power On Self Test
application), but it may also be used for user applications. It is provided as is, and is in no way a replacement
for a commercial flash programming application.

Here are the dsp peripherals initialized by evmupdater (by the builtin bootloader when burned in application mode I):

a) dsp pll1 clock speed
b) power on all dsp power domains (for all peripherals)
c) ddr2 initialization
d) emif configuration for flash memory on CS2 and default value on CS3
e) dsp pin mux needed for emif
f) dsp cache configuration

N.B. Any other evm configurations requiered by application (evm clk settings, evm mux settings,) must be provided
by user application.

All this is done without any user intervention. Evmupdater will burn a small bootloader with the provided
user ".out" program file to allow this. The bootloader is using a small part of the flash memory and
is using no dsp resources at all (no dsp ram, neither ddr2, no dsp peripherals) after user application is running.

This way user application ".out" can be tested in CCS with a jtag debugger in "release" or "debug" mode with
dsp initializations done by GEL file, and then simply burned to flash memory with this tool without any
other modifications. Any program that could be loaded with a jtag emulator to the evm could be directly burned
to flash memory this way. But you should take care that your program is setting evm specifics configurations that
could have been done manually through GEL files initialization functions (by using evm BSL library functions or
user provided functions).

When the evm is booted from flash memory, the small bootloader is initializing the dsp, then is loading
the user program from flash to ram memory (internal dsp memory and/or DDR2 memory), then the bootloader
is running the user program by calling the program "entry point".

N.B. Only flash sectors that are needed to burn the user program will be modified. Others will not. But the
addresses that do not need to be changed will not.


In mode II or III, it could also be used to burn a binary file (or AIS file) at a specific flash offset. In binary modes
(mode II & III), no bootloader is burned in flash but only the user specified binary file. User can burn as many as binary
files needed to specific flash offsets, because the flash burner will only override the modified addresses in flash and
will keep intact other flash memory content. 

If binary files were burned, dip sw could be set to a specific AIS dsp boot mode (dsp rom boot mode) to boot
the device.


2- Burning a program to flash memory (in .out application mode I)
   --------------------------------------------------------------

The following lines will explain how to burn a user program "evmpost.out" located in "c:\test" directory:

a) Let's call your application "evmpost.out"
b) Starts the flash burner tool by loading the program "evmupdater.out" in CCS (File - Load Program)
c) Run the flash burner program (press <F5> key)
d) A "Standard Input Dialog Box" will ask for the program filename. Types the complete filename including the
   complete path: "c:\test\evmpost.out" (if your burned a program before since you opened CCS, you may also
   use the drop box. It is also possible to "paste" the file name in the box).
e) click "OK" button of the "Standard Input Dialog Box"
f) The program will now be burned to flash memory. You can check in CCS under the "stdout" tab the status of
   the burning process. It should stop with "Done." message if it was made correctly.
g) To run a program burn in mode I from flash, the dsp boot mode must be set to "Master Mode - EMIF CS2 Direct Boot"
   To achieve this, set SW2 bank switches 1,2,4=OFF and 3=ON. Then power off the evm. At next power on,
   the burned application should start (verify also that bank SW2 switch 7=ON, bank SW3 switch 1,2,4=ON 3=OFF).
h) In case there are problems with a buggy burned application, to allow the evm to be used with a jtag debugger,
   power off the evm, set SW2 bank switches 1,2,3,4=OFF (Master Mode - Emulation Boot), then power on evm.


Typical program output (without a configuration file, see sect 4 below):
=======================================================================================



EVM - Flash Updater V1.3.1.0 @2007 Lyrtech
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enter [options], and the filename of the binary file or application to program:
[-E/][-B0xhhhhhhhh/]filename
c:\test\EVMPost.out

Opening c:\test\EVMPost.out...
Opening configuration file c:\test\evmupdater.ini...
No configuration file found, using defaults parameters...
Config parameters:
pll1_mult =0000001B, ddr_sdcfg =00000832, ddr_sdrfc=0000081A, ddr_sdtim1=42DB5BD9                  
ddr_sdtim2=00A4C722, ddr_dmcctl=50006405, emifb_ce2cfg=00310181, emifb_ce3cfg=0FFFFFFD                  
cachel1d_cfg=00000000, cachel1p_cfg=00000000, cachel2_cfg=00000000

Burning application in flash memory...

Entry point : 0x00A08400

Section    .text :    34816 bytes @ 0x00A00000
Reading Section...
Writing Section...
Section   .cinit :      444 bytes @ 0x00A0CC30
Reading Section...
Writing Section...
Section   .const :      426 bytes @ 0x00A0CDF0
Reading Section...
Writing Section...
Section  .switch :      220 bytes @ 0x00A0D0C0
Reading Section...
Writing Section...

Done.




3- Burning a binary file to flash memory (in binary mode II)
   ---------------------------------------------------------

The following lines will explain how to burn a user binary file "test.bin" located in "c:\test" directory at
flash byte offset 0x0 (beginning of flash):

a) Let's call your binary file "test.bin" that need to be burned at flash byte offset 0 (-B option will be
   used to specify binary flash offset in bytes from beginning of flash memory).
b) Starts the flash burner tool by loading the program "evmupdater.out" in CCS (File - Load Program)
c) Run the flash burner program (press <F5> key)
d) A "Standard Input Dialog Box" will ask for the program filename. Types the complete filename including the
   complete path, adding the desired burning offset like this: "-B0x00000000/c:\test\test.bin"
   (if your burned a program before since you opened CCS, you may also use the drop box. It is also possible
   to "paste" the file name in the box).
e) click "OK" button of the "Standard Input Dialog Box"
f) The file will now be burned to flash memory. You can check in CCS under the "stdout" tab the status of
   the burning process. It should stop with "Done." message if it was made correctly.
g) In case there are problems with a buggy burned application, to allow the evm to be used with a jtag debugger,
   power off the evm, set SW2 bank switches 1,2,3,4=OFF (Master Mode - Emulation Boot), then power on evm.


Typical program output (in binary mode II):
=======================================================================================




EVM - Flash Updater V1.3.1.0 @2007 Lyrtech
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enter [options], and the filename of the binary file or application to program:
[-E/][-B0xhhhhhhhh/]filename
-B0x00000000/c:\test\test.bin

Opening c:\test\test.bin...
File size:0x00000BFA, flash offset:0x00000000.

Burning binary file in flash memory...

Reading Section...
Writing Section...

Done.
=======================================================================================



4- Custom bootloader configuration (advanced user only)
   ----------------------------------------------------

IMPORTANT:
Custom bootloader configuration could only be used when the file is a dsp application (.out) file burned in mode I.
If a binary file is burned in binary mode (mode II or III), no bootloader will be burned to flash memory.
This step is usually not needed for normal application (.out) programming, because default parameters will
be used for the evmupdater bootloader:

CPU 891 MHz (27 * 33MHz)
DDR 265.9 MHz (fix speed if external clk is not changed)
EMIF 16 bits max wait states for cs3 and flash wait states for cs2...
caches L1D,L1P,L2 disable

To allow modification of bootloader operation (before the flash programmed user application is running),
an evmupdater configuration file may be used. A file "evmupdater.ini" may be
created in the same directory as the user program to be burned (in our example "c:\test\evmpost.out",
the file would be "c:\test\evmupdater.ini". If this file exist, evmupdater will use it to configure
the bootloader operation instead of default parameters. Care has to be taken of what is defined
in this configuration file, it could make easily the DSP crash if programmed with wrong parameters.

There are 3 samples files included you can take as an example for your own modifications:
a) "evmupdater_nocache.ini"
b) "evmupdater_L1d_L1P_cachemax.ini"
c) "evmupdater_slow_nocache.ini"

The configuration is the same for first 2 files, except as for cache memory. The first one "evmupdater_nocache.ini"
is similar as default evmupdater config when "evmupdater.ini" file is not found in user program directory:

CPU 891 MHz (27 * 33MHz)
DDR 265.9 MHz (fix speed if external clk is not changed)
EMIF 16 bits max wait states for cs3 and flash wait states for cs2...
caches L1D,L1P,L2 disable

The second "evmupdater_L1d_L1P_cachemax.ini" has the L1P and L1D both configured as MAX size cache (32K),
so only L2 and DDR2 memory are available in this configuration.

The last one "evmupdater_slow_nocache.ini" is a small variation with no cache and cpu running at a slow speed (it should
be seen that DDR2 and EMIF timing have not been optimized for this configuration, keeping same defaults values
as 891MHz):

CPU 561 MHz (17 * 33MHz)
DDR 265.9 MHz (fix speed if external clk is not changed)
EMIF 16 bits max wait states for cs3 and flash wait states for cs2...
caches L1D,L1P,L2 disable

To use one of these 3 samples files, just copy it to the user program directory then rename it "evmupdater.ini".
Burn the application as explained in section 2 above.

**********
IMPORTANT:
**********

The format of the "evmupdater.ini" file is critical and must be a fix format above the line written

"Do not edit above this line except changing values".

Do not change anything except editing the parameters value above this line in evmupdater.ini.
No validation is made on the format.
There is 11 parameters in the order described in the sample file.
Usually, parameter(s):
1 (PLL1_MULT) would be modified to run the DSP at a different speed (slowlier speed).
9-10-11 would be modified to configure the dsp cache needed as desired.
2-7 can be modified just if small performance tuning is needed but can keep these defaults

These are mostly DSP peripherals registers (check for similar DSP registers name).

Typical evmupdater.ini format:
=======================================================================================
0x1b
0x00000832
0x0000081A
0x42DB5BD9
0x00A4C722
0x50006405
0x00310181
0x0FFFFFFD
0x00000000
0x00000000
0x00000000
Do not edit above this line except changing values
--------------------------------------------------
CPU 891 MHz (27 * 33MHz)
DDR 265.9 MHz (fix speed if external clk is not changed)
EMIF 16 bits max wait states for cs3 and flash wait states for cs2...
caches L1D,L1P,L2 disable

Parameters above following this order:
PLL1_MULT
DDR_SDCFG
DDR_SDRFC
DDR_SDTIM1
DDR_SDTIM2
DDR_DMCCTL
EMIFB_CE2CFG
EMIFB_CE3CFG
CACHEL1D_CFG
CACHEL1P_CFG
CACHEL2_CFG

N.B. -Take care if cache(s) are activated that your program do not place code in
      internal ram memory where a cache has been activated (no validation is done!)
     -DSP pll multiplier register = PLL1_MULT-1
     -All parameters will be written to direct DSP matching registers except PLL1_MULT

All values must be in hex (C form 0xnnnnnnnn)
=======================================================================================




5- Burning a binary file in binary compilation mode III (advanced user only)
   -------------------------------------------------------------------------

Using burning mode III allows to do exactly the same thing that burning in binary mode II explained
above. This mode allows to compile a special version of evmupdater flash burner with a build in
user binary file. This mode could be used when a very big binary file needs to be burned and will
optimize programming time when used with a slow jtag emulator (when mode I and mode II gives very long
programming time). This mode will avoid downloading the user file at run time, but will download the
user application at loadtime when loading "evmupdater.out" in dsp memory. It could also be used to
optimize flash programming speed if the same file must be burned in multiple evm.

Requierements (for windows):

-CCS v3.3 or later
-DSPBIOS v5.31.02 or later (for "gmake.exe", if not user must provide "gmake.exe")

The following lines will explain how to burn a user binary file "test.bin" located in "c:\test" directory at
flash byte offset 0x0 (beginning of flash) in compilation mode:

a) Let's call your binary file "test.bin" that need to be burned at flash offset 0 (-B option will be
   used to specify binary flash offset in bytes from beginning of flash memory).
b) Prepare to compile evmupdater with the file "test.bin":
   I)   Open a "command prompt" (Program, Accessories, Command Prompt). All following operations must be made
        from the command prompt text box.
   II)  Change current directory to where evmupdater is installed.
        ex. cd C:\CCStudio33\boards\evmdm648\EVMUpdater\src
   III) Initialize CCS dos environment variables by running "dosrun.bat" located in CCS installation directory.
        (This must also set a path to "gmake.exe" from dsp bios directory. You can run "gmake" on the command
        prompt to verify if it is available after).
        ex. C:\CCStudio33\dosrun
   IV)  Compiles evmupdater with user file by using GEN batch file. This will create a file "srcfile.c"
        in this directory that is compiled with evmupdater library. If the complete flash must be bulk erased,
        uses the option like this instead "-e/-b0x0/". At compilation, this will build a command string for the
        burner, that will replace the one that should be entered by the user in binary mode II (explained above).
        ex. GEN "c:\test\test.bin" "-b0x0/"
        You should see and output in the command prompt window similar like this:

        GEN v1.00 @2007 Lyrtech
        EVMBIN2C V1.0.0.0 by Lyrtech @2007
        Target file: "srcfile.c", complete option string: "-b0/c:\test\test.bin".
        EVMBIN2C Done!
        MCLEAN v1.00 @2007 Lyrtech
        Cleaning.
        Wait...
        Cleaning completed!
        MREBUILD v1.00 @2007 Lyrtech
        Rebuilding.
        Wait...
        gmake  -f Evmupdaterb.mak Release FRC=force_rebuild
        gmake[1]: Entering directory `C:\CCStud~1\boards\evmdm648\EVMUpd~1\src'
        "cl6x" -fr"Release" -mv6400 "srcfile.c"
        "cl6x" -@"Evmupdaterb.Release.lkf"
        <Linking>
        gmake[1]: Leaving directory `C:\CCStud~1\boards\evmdm648\EVMUpd~1\src'
        Rebuilding completed!
        Done!
   V)   The new custom compiled version of evmupdater will be located in "src\release\evemupdater.out".
        This compiled version can only be used in binary mode III and will burn user file "test.bin"
        when run without asking any user information.
        ex.: C:\CCStudio33\boards\evmdm648\EVMUpdater\src\release\evemupdater.out

c) Starts the flash burner tool by loading the program "evmupdater.out" in CCS (File - Load Program)
d) Run the flash burner program (press <F5> key)
e) The file will now be burned to flash memory. You can check in CCS under the "stdout" tab the status of
   the burning process. It should stop with "Done." message if it was made correctly.
f) In case there are problems with a buggy burned application, to allow the evm to be used with a jtag debugger,
   power off the evm, set SW2 bank switches 1,2,3,4=OFF (Master Mode - Emulation Boot), then power on evm.

Typical program output (in binary compilation mode III):
=======================================================================================
EVM - Flash Updater V1.3.1.0 @2007 Lyrtech
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Opening "c:\test\test.bin" from builtin data buffer (compilation mode)...
File size:0x0015591C, flash offset:0x00000000.

Burning binary file in flash memory...

Reading Section...
Writing Section...

Done.
=======================================================================================




6- Bulk erase (chip erase) flash memory before programming
   -------------------------------------------------------

Evmupdater is only erasing flash sectors as needed to program new data to optimize speed.
In some situations, it could be necessary to erase the complete flash memory before
burning (clean flash programming to a known state). This could be achieve by using the
-E erase option.

1-) Example of programming "test.bin" in binary mode at offset 0 with complete chip erase.
Here are the parameters to give on input prompt: "-E/-B0x0/test.bin"

2-) Example of programming "test.out" in application mode (using bootloader) with complete
 chip erase. Here are the parameters to give on input prompt: "-E/test.out"

WARNING: bulk erasing complete flash memory could be very long (max 512 secs) and should be
done only if necessary to avoid long programming delays! It is usually not needed.
