
==> Note 1: As an example, a compressed Blink application is included with this EE-Note for your convenience. It is suggested that you try the following steps using the included Blink application to familiarize yourself with the compression process, then try programming the last generated file (CompressedAppIntelHex.ldr) with the Flash Programmer to verify correct functionality.

==> Note 2: This compression algorithm requires about 50 KB of overhead (extra) memory. Therefore, it is useful only in applications of a significantly larger size.

POSSIBLE USER MODIFICATIONS

You can edit certain files or parameters in the project folder manually. The following guidelines describe the files or parameters that may need modification:

- Application folder: Replace the sample Blink application project with your user-application project.

- Init project: If you are not using an ADSP-BF533 or ADSP-BF561 EZ-KIT Lite board, you may need to modify the default linker sections in the .LDF file of the Initialization project.

- Init_code.c: Set the UNCOMPR_ADDR field to the intended destination address for the output of the uncompress function.

- Compress.bat: The source file path and compression level may be changed.

- IntelHex.bat: The output file name (2nd parameter) may be changed if desired.


INSTRUCTIONS


1) You must allocate an unused area of SDRAM memory in your user-application to store the uncompressed user-application loader image. The .LDF file of your user-application project must be modified to free a section of SDRAM memory of appropriate size. This region must be large enough to hold an entire loader build of your user-application, allowing uncompress() to deflate to that area in memory. The user-application loader image will then be loaded by the Boot ROM out of SDRAM.

For ADSP-BF561 processors, you must also free L2 memory addresses 0xFEB1 FC00 through 0xFEB1 FFE7 by keeping them out of any section in your user-application's .LDF file. These addresses are reserved for the 2nd-stage boot kernel. This is done in the .LDF file of the example ADSP-BF561 Blink program.

2) Set the UNCOMPR_ADDR field at the top of the Init_code.c file (Init folder) to the intended destination address for the output of the uncompress function (that is, the starting address of the reserved section or kept empty in the SDRAM memory of your user-application in Step 1). In the given example, this address is set to 0x4000.

3) Specify the user-application project to be built as a Loader file (via Load page of Project Options dialog box) and use SPI/ASCII/8-bit format. Note that the SPI setting is a workaround used to generate the output in ASCII format.

For ADSP-BF533 processors, specify the following path to the initialization project file: ../Init/Debug/ Init.dxe.

For ADSP-BF561 processors, select Boot kernel options from the Category list, select Use boot kernel, and specify the path to the kernel file as: ../Init/Debug/ p0.dxe. Also, under Additional options, insert: ./debug/p0.dxe.

When executed at the start of the boot process, this object file initializes SDRAM memory, finds the compressed user-application code, and decompresses it to the appropriate area in SDRAM memory.

4) Build the Init code project first, and then build your user-application. Ensure that the project to be built is active (highlighted in the Project window) and that project dependencies are set, if necessary. This should create an .LDR file in the Debug directory of your user-application.

5) In the root folder, edit the compress.bat file (use any text editor) to specify the path of the target loader file that has just been built from your user-application, as well as the desired level of compression (see Table 1 for compression levels).

*** Note that the entered path must be enclosed in double-quotes (") and must use forward-slashes or double-backslashes. An incorrectly specified path name or compression level may cause undesirable results.

6) Execute compress.bat (root folder) and ensure the result of the compression (returned on line 6 of the Output window) is successful by matching your return code with those listed in Table 2.

The Output window (Figure 2) returns important values calculated during compression, notably:
- Source file size (line 1)
- Source buffer start address (line 2)
- Number of bytes used for the source buffer (line 3)
- Application start address and number of bytes used for the Init code buffer (line 4)
- Application size and output buffer start address (line 5)
- Compression result (0 = success) and compressed application size (line 6)
- Path of the output file (line 7)

If successful, a file called CompressedApp.ldr is created in the same directory as your source loader file (that is, the Debug directory of your user-application). This ASCII format file contains both the Init (decompression) code and your compressed user-application code. 

7) Copy the CompressedApp.ldr file to the root folder, where you should then execute IntelHex.bat. This converts the compressed application loader file into Intel hexadecimal format and creates a new file called CompressedAppIntelHex.ldr. This conversion is necessary for the loader file to be understood by the Flash Programmer.

8) Run the VisualDSP++ Flash Programmer plug-in, specifying CompressedAppIntelHex.ldr as the source file. 


============================ 
TABLE 1: COMPRESSION LEVELS 
============================

Best Speed:             1 
Default Compression:  (-1) 
Best Compression:       9 

====================================================================================
TABLE 2: RETURN CODES

Return codes for the compression/decompression functions. Negative
values are errors, positive values are used for special but normal events.
====================================================================================

Z_OK            0
Z_STREAM_END    1
Z_NEED_DICT     2
Z_ERRNO        (-1)
Z_STREAM_ERROR (-2)
Z_DATA_ERROR   (-3)
Z_MEM_ERROR    (-4)
Z_BUF_ERROR    (-5)
Z_VERSION_ERROR (-6)