read_me.txt

ThreadX for BLACKFIN BF561的源码。基于BLACKFIN的处理器。

                   Express Logic's ThreadX for BLACKFIN BF561

                     Using the VisualDSP Software Tools
                                 version 3.5.5.0

1.  Installation

ThreadX for the BLACKFIN is delivered on a single CD-ROM compatible disk.  
The entire distribution can be found in the sub-directory:

\THREADX

To install ThreadX to your hard-disk, make a THREADX directory on your 
hard-disk (we recommend C:\THREADX\BLACKFIN\VISUAL) and copy all the contents 
of the THREADX sub-directory on the distribution disk.  The following 
is an example MS-DOS copy command from the distribution directory
(assuming source is D: and C: is your hard-drive):


D:\THREADX> xcopy /S *.* C:\THREADX\BLACKFIN\VISUAL


2.  Demonstration System

The demonstration system delivered with ThreadX for the BLACKFIN using Analog Devices' 
VisualDSP++ development environment executes under the VisualDSP++ simulator and the
Analog Devices ADDS-BF561-EZ-LITE board. 

NOTE: To use this demonstration system with a different Analog Devices EZ-LITE board, you 
will need to select the appropriate"demo.ldf" file from those provided by Analog Devices, 
and you'll need to add the following lines of code to the end of that .ldf file in order 
for it to be used with ThreadX:

	threadx
	{
	ALIGN(4)
	tx_free_memory = .;
      } >MEM_B_L1_DATA_B

Please contact Express Logic if you require assistance with this operation. This step IS 
NOT REQUIRED if you will be running on the ADDS-BF561-EZ-LITE board, since the enclosed 
"demo.ldf" file has already been modified for use with ThreadX.

Building the demonstration is easy, simply execute the BUILD_AP.BAT file from your 
ThreadX directory:

C:\THREADX\BLACKFIN\VISUAL\ build_ap

This file produces the binary program images P0.DXE & P1.DXE for both processors.
These can be loaded on the VisualDSP simulator or EZ-LITE board.

A demo.dpj project file is also supplied which can be loaded by the IDE in
order to build the demo project.


3.  System Initialization

The system entry point using the VisualDSP tools is at the label ___lib_start.  
This is defined within the TX_ILL.ASM file.  From this point, the VisualDSP
initialization is invoked by calling ___lib_setup_c.  This is where all static
and global pre-set C variable initialization is done as well as clearing global
un-initialized data.  When this function returns, the application's main 
program is called.

ThreadX initialization is called once the application's main function calls
tx_kernel_enter.  The main initialization function is _tx_initialize_low_level 
and is located in the file TX_ILL.ASM.  This function is responsible for 
setting up various system data structures, interrupt vectors, and the periodic 
timer interrupt source of ThreadX.

In addition, _tx_initialize_low_level determines the first available address 
for use by the application.  By default free memory is assumed to start at the 
end of the L1_DATA section defined by the tx_free_memory, which is defined in 
the DEMO.LDF file.  This address is passed to the application definition function, 
tx_application_define.

The tx_port.h file contains the TX_INLINE_INITIALIZATION define which controls
whether ThreadX initialization functions are "inlined" or function calls.
Inlining is ON by default.


4.  Assembler / Compiler Switches

The following are compiler switches used in building the demonstration 
system:

Compiler Switch                 Meaning

    -proc ADSP-BF561    Select target processor
    -jcs2l              Automatically fix out of range jumps for linker
    -c                  Specifies object code generation
    -g                  Specifies complete debug information
    -o                  Specified the name of the output object file
    -stallcheck=none    Disable stall checking
    -threads            Use thread-safe libraries


5.  Register Usage and Stack Frames

The VisualDSP compiler assumes that registers r0-r3, p0-p2 are scratch 
registers for each function.  All other registers used by a C function 
must be preserved by the function.  ThreadX takes advantage of this in 
situations where a context switch happens as a result of making a ThreadX 
service call (which is itself a C function).  In such cases, the saved 
context of a thread is only the non-scratch registers.

The following defines the saved context stack frames for context switches
that occur as a result of interrupt handling or from thread-level API calls.
All suspended threads have one of these two types of stack frames.  The top
of the suspended thread's stack is pointed to by tx_stack_ptr in the 
associated thread control block TX_THREAD.  Optional savings on the non-
interrupt stack can be enabled via the TX_LOOP_SAVE define in tx_tsr/tx_ts.



    Offset        Interrupted Stack Frame        Non-Interrupt Stack Frame

      1             1                               0  
      2             imask                           imask
      3             p5                              p5
      4             p4                              p4
      5             p3                              p3
      6             p2                              r7
      7             p1                              r6 
      8             p0                              r5 
      9             r7                              r4  
      10            r6                              astat
      11            r5                              l3 (optional)
      12            r4                              l2 (optional)
      13            r3                              l1 (optional)
      14            r2                              l0 (optional)
      15            r1                              lb1 (optional) 
      16            r0                              lt1 (optional)
      17            astat                           lb0 (optional)
      18            l3                              lb1 (optional)
      19            l2                              fp 
      20            l1                              rets 
      21            l0                                
      22            lb1                               
      23            lt1                               
      24            lb0                           
      25            lb0                                 
      26            lc1                         
      27            lc0                                  
      28            b3                            
      29            b2                                    
      30            b1                             
      31            b0                                  
      32            m3                            
      33            m2                                   
      34            m1                             
      35            m0                                  
      36            i3                            
      37            i2                                    
      38            i1                             
      39            i0                                    
      40            a1.w                           
      41            a1.x                                           
      42            a0.w
      43            a0.x
      44            reti
      45            fp 
      46            rets


6.  Improving Performance

The distribution version of ThreadX is built without any compiler 
optimizations.  This makes it easy to debug because you can trace or set 
breakpoints inside of ThreadX itself.  Of course, this costs some 
performance.  To make it run faster, you can change the BUILD_TX.BAT file to 
remove the -g option and enable compiler optimizations with the -O1, -O2, or
-O3 options.  

In addition, you can eliminate the ThreadX basic API error checking by 
compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING 
defined. 


7.  Interrupt Handling

ThreadX provides complete and high-performance interrupt handling for BLACKFIN
targets.  This performance is achieved by initially saving a working group of
scratch registers suitable for high-speed assembly/C ISRs not managed by ThreadX.
For those ISRs requiring TX services and nesting, context_save then saves
those scratch registers that might be overwritten by a full function C ISR.
Finally,  context_restore saves the remaining "preserved" registers when a thread
is preempted as a result of calling a TX service from an ISR.


Application Threads execute at Level 15 on the BlackFin while the ThreadX
scheduler reserves level 14.


7.1  Vector Area

The initial BLACKFIN vectors are defined in the file TX_ILL.ASM and start at 
address EVT0.

7.2  Managed ISRs

Once program execution is in the handler, the following code fragment is 
necessary to call your ISR (this shell is also setup in TX_ILL.ASM for 
various interrupt sources):

__tx_interrupt_handler:
        LINK LINK_STACK_SIZE;
        [SP+20] = P2;
        [SP+24] = P1;
        [SP+28] = P0;

        [SP+48] = R3;
        [SP+52] = R2;
        [SP+56] = R1;
        [SP+60] = R0;

        R0 = astat;
        [SP+64] = R0;

        CALL __tx_thread_context_save;

//      [--SP] = RETI;                          // Use this for nested interrupts

//      Call your C ISR HERE  !!

//      RETI = [SP++];                          // Use this for nested interrupts

        JUMP __tx_thread_context_restore;       // No return



These scratch regs are saved in this order so the pop-multiple instruction can be used later
The context restore function takes care of all register saving for a preemption
When the ISR jumps to context restore, ThreadX will recover saved information and
return directly back to the point of interrupt if no preemption is required.
Otherwise, if preemption is required, ThreadX will save the remaining context of the
interrupted thread and return to the scheduler from context restore.


7.3  Fast Interrupts

Not all interrupts require ThreadX interaction, i.e. making ThreadX API calls
from the ISR.  In such cases, the application may define an ISR without using
the ThreadX context save/restore routines.  However, the application is then
responsible for preserving the interrupted environment and making sure that
ThreadX is not called.  


8.  ThreadX Timer Interrupt

ThreadX utilizes the BLACKFIN core timer (by default the low priority option)
to generate the interrupt pulse required for all time-slicing, thread sleeps, 
timeouts, and application timers.  The frequency of the timer is application
dependant, and is defined in TX_ILL.ASM.


9.  Revision History

07/15/2004  Initial ThreadX version of BLACKFIN561/VisualDSP port. 


Copyright(c) 1996-2004 Express Logic, Inc.


Express Logic, Inc.
11423 West Bernardo Court
San Diego, CA  92127

www.expresslogic.com