readme_c_overlay.txt

基于TS201 Sets up a skeleton overlay system in C

****************************************************************************

       ADSP-TS201S and ADSP-TS101S EZ-Kit Overlay example in C

Sets up a skeleton overlay system in C

Analog Devices, Inc.
DSP Division
Three Technology Way
P.O. Box 9106
Norwood, MA 02062

March-2004 AC
November-2002 BL

This directory contains an example ADSP-TS201S and ADSP-TS101S subroutine that 
implements memory overlays.

#defines have been added allowing the same source code to be used on both an ADSP-TS201S
or an ADSP-TS101S EZ-Kit.


Files contained in this directory:

ADSP-TS201_Ovl_MP_C.ldf			Linker description file 
ADSP-TS101_Ovl_MP_C.ldf			Linker description file 
OverlayExampleC_TS201.dpj		VisualDSP project file
OverlayExampleC_TS101.dpj		VisualDSP project file
MainA.c					Source file for DSPA
InitA.c					Source file containing one-time initialization code for DSPA
Variablesa.c				Volatile variables used by overlay manager and interrupt service routine
DMAInt.c				Interrupt service routine for DMA0
OvlyMgr.c				Source file containing overlay manager code
Function1.c				First overlayed function
Function2.c				Second overlayed function
Function3.c				Third overlayed function
Function4.c				Fourth overlayed function
MainB.c					Source file for Device 0
cache_macros.h				TS201S macro file which includes macros to enable the cache
OverlayCDef.h				Defines the TCB structure for DMA
TS101_EZ_KIT_Defines.h			Defines the revision of ADSP-TS101S EZ-Kit being used
README_C_OVRELAY.txt			This README file
 _________________________________________________________________

CONTENTS

I.    OVERLAYED FUNCTIONS DESCRIPTION
II.   OVERLAY MANAGER DESCRIPTION
         

I. OVERLAYED FUNCTIONS DESCRIPTION
For x=1,2,3,4 Functionx.c contain routines functx() that set bit (x-1)
in "LastOverlayRun". "LastOverlayRun" is an uninitialized volatile int declared
in 'Variablesa.c'. When all four functions have run it will contain the value 0x0000000f.

II.   OVERLAY MANAGER DESCRIPTION

'OvlyMgr.c' contains the overlay manager source code. This routine
is responsible for bringing in the new overlayed code and then
calling it.

The story begins in the LDF file with declaration

PLIT
{
	j4 = j31+PLIT_SYMBOL_OVERLAYID;;
	j5 = j31+PLIT_SYMBOL_ADDRESS;;
	JUMP _OverlayManager (NP);; 
}

This declaration instructs the linker to replace all calls to functions
that are overlayed for DSPA(defined with 'OVERLAY_INPUT' directive in the LDF file)
with the code above in PLIT. "PLIT_SYMBOL_OVERLAYID" is replaced with the
ID of the overlay (in our case 1, 2, 3 or 4) and "PLIT_SYMBOL_ADDRESS" is
replaced with the run address of the routine (i.e. the starting location 
in the internal memory where the routine must be moved to and then run
from).

The overlay manager itself (in 'OvlyMgr.c') contains the function
'OverlayManager'.

Overlay manager routine decrements "OverlayID" which is originally passed through J4
to obtain the offset for the tables that contain sources of the overlayed routines 
(liveAddresses), destinations of the overlayed routines (runAddresses) and word sizes
of the routines. These values are loaded into the TCB varaibles, DMA is started and
the processor sits in a WHILE loop waiting for the DMA to complete. Interrupt brings
the processor out of the while loop by setting the bool variable "OverlayReady" to true
in the DMA interrupt service routine. Then the overlay manager invalidates the BTB and 
calls the overlayed routine. The call to the overlay routine is performed by performing
a call to the function located at the address that is passed as the second parameter (J5)
to the 'OverlayManager' function.


Project options for ADSP-TS101S EZ-Kit: 
=======================================
Please refer to the VisualDSP++ release notes and the 
ADSP-TS101S anomaly listings for full details of the following switch usage, 
operation and silicon revision requirements

Assembler/Compiler switches to be used in the assembler and 
compiler property pages' Additional Options fields

'-default-branch-np'	Required for TS101S Rev 0.1 silicon. 
						Use in BOTH compiler AND Assembler property 
						page 'Additional Options' field.

"-align-branch-lines'	Required for TS101S Rev 0.1 and 0.2 silicon". 
						Although a specific example may not contain a 
						"jump(P)", to keep generality the switch is 
						required for all silicon versions. Use only 
						in Assembler property page 'Additional Options'
						field.


If any example code projects are built/rebuilt for the above mentioned 
silicon revisions, these switches must be used. The same holds true for 
user created code sets.

These switches have been included in the compiler and assembler additional options as default


Project options ADSP-TS201S EZ-Kit: 
==================================
Please refer to the VisualDSP++ release notes and the 
TS201S anomaly listing for full details of the following switch usage, 
operation and silicon revision requirements

Assembler/Compiler/Linker switches to be used in the assembler, linker,
and compiler property pages' Additional Options fields

'-si-revision 0.1'		Required for TS201S Rev 0.1 silicon. 
						Use in compiler AND Assembler AND linker property 
						page 'Additional Options' field.


If any example code projects are built/rebuilt for the above mentioned 
silicon revisions, these switches must be used. The same holds true for 
user created code sets.

cache_macros.h
================
After powerup/reset, the TS201 cache and BTB are not enabled

At the beginning of the program the cache must be enabled. The procedure is 
contained in the cache_enable macro that uses the refresh rate as input 
parameter
      -if CCLK=500MHz, refresh_rate=750
      -if CCLK=400MHz, refresh_rate=600
      -if CCLK=300MHz, refresh_rate=450
      -if CCLK=250MHz, refresh_rate=375

cache_macros.h performs the following:

-cache_enable(refresh_rate):
  -sets a new refresh rate
  -if the cache is enabled, it leaves it enabled.
  -if the cache is not enabled, it enables it in the correct way accounting for cache coherency
  -at the end enables the BTB if it was not already enabled
  -this macro should be used as the first line of code in every program

This header file also contains additional benchmarking macros which may be 
useful. Please see the header file source code and comments for additional 
information.

The cache_macros.h header file is included in 'Maina.c' as follows:

asm("#include <cache_macros.h>");

As this file is located in the actual project directory and not the default include
directories that are used by VisualDSP the following preprocessor warning is 
generated:

"pp0084 Preprocessor Warning: Include file not found in path; opening in connected directory.
This legacy behavior will not be supported in future releases.
Filename: 'cache_macros.h'"

The reason for this is that the connected directory is no longer an implicit part of the
search path for finding files included with #include directives. Previous releases would 
include the connected directory in their search. This behavior is now deprecated and may 
disappear from future releases of VisualDSP++. In order to make the transition to the new
behavior easier, the preprocessor will continue to search the connected directory but will
issue this warning.

To correct this warning the user must include the search path in the preprocessor project
options.
This can be found by selecting preprocessor from the "Catagory" field in the compiler tab of
the project options.

The project path then needs to included in the "Additional include directories" field.

In this case:
".\" is enough as this directs the preprocessor to search the directory where the project is located.

Simulator Information
===============
As the project is a multiprocessor project, the LDF is configured in such a way that by default 
the VisualDSP++ IDDE loads the generated executables to the correct processors on the EZ-Kit without
the user needing to correctly specify their placement in the "Load Multiprocessor Confirmation" window.

This results in the incorrect executable being loaded when the project is built in a simulator session.
To load the executable for DSPA in a simulator session, after successfully building the project,
select 'File->Load program' from the pulldown menu and select the 'DSPA.dxe' located in the debug or 
release folder.