Guru Challenge: Overlays for VS1053

Installing and using VSIDE tools for VLSI Solution's devices that contain a VSDSP signal processor.
Post Reply
User avatar
VSDSP Expert
Posts: 2800
Joined: Tue 2010-06-22 13:43

Guru Challenge: Overlays for VS1053

Post by Panu » Mon 2010-11-08 14:15

Dear Forum Members!

This is the announcement many have been waiting. Here is the first working release of overlay support for VS1053. With overlays, it's theoretically possible to extend the maximum program code size even up to 1 megabyte. This version handles image sizes correctly up to 64 kilobytes. It is distributed as a VSIDE solution. Upzip the solution to a new folder in your "solutions" folder. Open with VSIDE and Rebuild Solution.
overlays.png (37.87 KiB) Viewed 3573 times
An overlaid program consists of 1) the static part, which is always resident in memory and 2) any number of overlay parts, which are loaded into memory as necessary. The static part must contain all interrupt handlers, the overlay calling/loading code, and preferably any functions which are very common.

The overlay parts are binary executables, which contain code and data like any VS10xx program. But there are also many differences to a "normal" VS10xx program. First of all, the linker parameters and pre/post build steps need to be set very exactly. Second of all, some functions in each overlay are "entry" functions, which must have a prototype, which is castable to int(int). That is: each function takes one 16-bit parameter and returns a 16-bit return value. All entry functions are listed in a special file named "overlay_control". Entry functions can be called from the static part (fast) and also from other overlays (slow).

Overlay parts can also have global and static variables. They are not linked to the same addresses like program code is. All overlays can use public (those having extern definitions in main.h) global variables that are declared in the static part. Globals that are defined in an overlay are visible only within that overlay.

To get the hang of how the overlays work, see the source code. The example has a project for the static part, plus 3 overlays: alpha, beta and gamma. Also there is a library project called "symbols" which is compiled first.

The overlay linking is a 2 step process. At first link iteration, all modules are linked to find out their sizes. Then the address information is updated so all modules have the same idea of what are the addresses for overlaid symbols. At second link pass, the updated address information is used and an overlaid eeprom.img is generated. Also the "ovlinfo" program draws a memory map to show you what the program memory layout is going to be.

To compile the overlaid program, you must click "Rebuild Solution" 2 times. The second time will produce the loadable image eeprom.img. (with a very small change in program, which does not change any of the sizes of the objects, the first linker pass may also give you the working image).

To run the overlaid program, open a MS-Dos Prompt and navigate to the project directrory, such as ".../My Documents/solutions/vs1053_overlays". Then run uniprom.bat (by writing "uniprom") at the command line. Please make sure that VS3EMU.EXE is in the PATH (or copy VS3EMU.EXE to the project directory). Because the very idea of overlaid programs is that they are larger than the program memory size, it's not (usually) possible to run them directly with the serial port.

To actually see what is happening in the program, make a "COM monitoring cable" which "copies" PC side pins 2 and 5 from COM1 to COM2. Then you can run a terminal program such as HyperTerminal in COM2 in the background and see what's happening even if you use COM1 for running UNIPROM. The alternative is to program the EEPROM using UNIPROM, then start the HyperTerminal (115200, N-8-1, No flow control) and reset the board with SPI boot enabled. I also sometimes use an old black-and-white laptop running TELIX to monitor the debug printouts from the board.

When the program runs, you should see this output at the terminal:
Hello, System!
<<LOAD 0074 alph[]>> AlphaOne
<<LOAD 007C beta[]>> BetaOne

Below is a PC screen capture which has VSIDE, HyperTerminal showing the debug strings, command line prompt having programmed the flash, and OvlInfo in the backgroung.

Happy overlaying!
(506.02 KiB) Downloaded 858 times
overlay_build.png (108.04 KiB) Viewed 3573 times
Info: Line In and Line Out, VS1000 User interface, Overlay howto, Latest VSIDE, MCU Howto, Youtube
Panu-Kristian Poiksalo, VLSI Solution Oy

Post Reply