                   Express Logic's ThreadX for MIPS32 4Kx 

                    Using the Green Hills Software Tools

1. Installation

ThreadX for the MIPS32_4Kx 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, either run the supplied installer 
program Setup.exe or copy the distribution from the CD manually. 

To copy the ThreadX distribution manually, make a threadx directory on your 
hard-disk (we recommend C:\threadx\MIPS32_4Kx\green) 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\MIPS32_4Kx\green


2. Open the ThreadX Project Workspace

In order to build the ThreadX library and the ThreadX demonstration first
load the ThreadX project workspace threadx_project_workspace.gpj, which is 
located inside your ThreadX directory:

C:\threadx\MIPS32_4Kx\green\threadx_project_workspace.gpj


3. Building the ThreadX run-time Library

Building the ThreadX library is easy; simply select the MULTI project file 
tx.gpj and then select the build button. You should now observe the 
compilation and assembly of the ThreadX library. This project build produces 
the ThreadX library file tx.a.


4. Demonstration System

The ThreadX demonstration is designed to execute under the MULTI environment
on the Green Hills MIPS32 4Kx simulator. The instructions that follow describe
how to get the ThreadX evaluation running under the MULTI MIPS32 4Kx simulation 
environment.

Building the demonstration is easy; simply select the MULTI project file 
demo_threadx.gpj. At this point, select the "Project Build" button and observe 
the compilation, assembly, and linkage of the ThreadX demonstration application. 

After the demonstration is built, invoke the  MULTI MIPS simulator by selecting 
the simulator connection from within the demo_thread.con connection file. Once
connected to the simulator, select the DEBUG button. You should now observe the 
main function of demo_threadx.c.

You are now ready to execute the ThreadX demonstration system. Select 
breakpoints and data watches to observe the execution of the demo_threadx.c 
application.


5. EventAnalyzer Demonstration

To build a demonstration system that also logs events for the MULTI EventAnalyzer, 
perform the same steps as the regular demo, except build the ThreadX library with 
txe.gpj file and use the demo_threadx_el.gpj build file to build the demonstration. 
The resulting image will log all system events, which can then be displayed by the 
MULTI EventAnalyzer.


6. System Initialization

The system entry point using the Green Hills tools is at the label _start. 
This is defined within the crt0.mip file supplied by Green Hills. In addition, 
this is where all static and global preset C variable initialization 
processing is called from.

After the Green Hills startup function returns, ThreadX initialization is
is called. The main initialization function is _tx_initialize_low_level and
is located in the file tx_initialize_low_level.mip. 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 where the first available 
RAM memory address is located. This address is supplied to tx_application_define.

By default, the first available RAM memory address is assumed to start at the 
beginning of the ThreadX section .free_mem. If changes are made to the 
demo_threadx.ld file, the .free_mem section should remain the last allocated 
section in the main RAM area. The starting address of this section is passed 
to tx_application_define.


7. User defines

The following defines and their associated action are as follows:

            Define                                          Meaning

    TX_DISABLE_ERROR_CHECKING                   If defined before tx_api.h is included,
                                                this define causes basic ThreadX error
                                                checking to be disabled. Please see
                                                Chapter 4 in the "ThreadX User Guide" 
                                                for more details.

    TX_ENABLE_EVENT_LOGGING                     This define enables event logging for any
                                                or all of the ThreadX source code. If this
                                                option is used anywhere, the tx_initialize_high_level.c 
                                                file must be compiled with it as well, since this
                                                is where the event log is initialized.

    TX_NO_EVENT_INFO                            This is a sub-option for event logging.
                                                If this is enabled, only basic information
                                                is saved in the log.

    TX_ENABLE_EVENT_FILTERS                     This is also a sub-option for event-logging.
                                                If this is enabled, run-time filtering logic
                                                is added to the event logging code.

    TX_MAX_PRIORITIES                           Defines the priority levels for ThreadX. 
                                                Legal values range from 32 through 
                                                1024 (inclusive) and MUST be evenly divisible 
                                                by 32. Increasing the number of priority levels 
                                                supported increases the RAM usage by 128 bytes 
                                                for every group of 32 priorities. However, there 
                                                is only a negligible effect on performance. By 
                                                default, this value is set to 32 priority levels.

    TX_MINIMUM_STACK                            Defines the minimum stack size (in bytes). It is 
                                                used for error checking when threads are created. 
                                                The default value is port-specific and is found 
                                                in tx_port.h.

    TX_TIMER_THREAD_STACK_SIZE                  Defines the stack size (in bytes) of the internal 
                                                ThreadX timer thread. This thread processes all 
                                                thread sleep requests as well as all service call 
                                                timeouts. In addition, all application timer callback 
                                                routines are invoked from this context. The default 
                                                value is port-specific and is found in tx_port.h.

    TX_TIMER_THREAD_PRIORITY                    Defines the priority of the internal ThreadX timer 
                                                thread. The default value is priority 0 - the highest 
                                                priority in ThreadX. The default value is defined 
                                                in tx_port.h.

    TX_TIMER_PROCESS_IN_ISR                     Defined, this option eliminates the internal system 
                                                timer thread for ThreadX. This results in improved 
                                                performance on timer events and smaller RAM requirements 
                                                because the timer stack and control block are no 
                                                longer needed. However, using this option moves all 
                                                the timer expiration processing to the timer ISR level. 
                                                By default, this option is not defined.

    TX_REACTIVATE_INLINE                        Defined, this option performs reactivation of ThreadX 
                                                timers in-line instead of using a function call. This 
                                                improves performance but slightly increases code size. 
                                                By default, this option is not defined.

    TX_DISABLE_STACK_FILLING                    Defined, placing the 0xEF value in each byte of each 
                                                thread's stack is disabled. By default, this option is 
                                                not defined.

    TX_ENABLE_STACK_CHECKING                    Defined, this option enables ThreadX run-time stack checking, 
                                                which includes analysis of how much stack has been used and 
                                                examination of data pattern "fences" before and after the 
                                                stack area. If a stack error is detected, the registered 
                                                application stack error handler is called. This option does 
                                                result in slightly increased overhead and code size. Please 
                                                review the tx_thread_stack_error_notify API for more information. 
                                                By default, this option is not defined.

    TX_DISABLE_PREEMPTION_THRESHOLD             Defined, this option disables the preemption-threshold feature 
                                                and slightly reduces code size and improves performance. Of course, 
                                                the preemption-threshold capabilities are no longer available. 
                                                By default, this option is not defined.

    TX_DISABLE_REDUNDANT_CLEARING               Defined, this option removes the logic for initializing ThreadX 
                                                global C data structures to zero. This should only be used if 
                                                the compiler's initialization code sets all un-initialized 
                                                C global data to zero. Using this option slightly reduces 
                                                code size and improves performance during initialization. 
                                                By default, this option is not defined.

    TX_DISABLE_NOTIFY_CALLBACKS                 Defined, this option disables the notify callbacks for various 
                                                ThreadX objects. Using this option slightly reduces code size 
                                                and improves performance.

    TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO       Defined, this option enables the gathering of performance 
                                                information on block pools. By default, this option is 
                                                not defined.

    TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO        Defined, this option enables the gathering of performance 
                                                information on byte pools. By default, this option is 
                                                not defined.

    TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO      Defined, this option enables the gathering of performance 
                                                information on event flags groups. By default, this option 
                                                is not defined.

    TX_MUTEX_ENABLE_PERFORMANCE_INFO            Defined, this option enables the gathering of performance 
                                                information on mutexes. By default, this option is 
                                                not defined.

    TX_QUEUE_ENABLE_PERFORMANCE_INFO            Defined, this option enables the gathering of performance 
                                                information on queues. By default, this option is 
                                                not defined.

    TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO        Defined, this option enables the gathering of performance 
                                                information on semaphores. By default, this option is 
                                                not defined.

    TX_THREAD_ENABLE_PERFORMANCE_INFO           Defined, this option enables the gathering of performance 
                                                information on threads. By default, this option is 
                                                not defined.

    TX_TIMER_ENABLE_PERFORMANCE_INFO            Defined, this option enables the gathering of performance 
                                                information on timers. By default, this option is 
                                                not defined.



8. Register Usage and Stack Frames

The Green Hills MIPS compiler assumes that registers t0-t9 ($8-$15, $24, $25) 
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_thread_stack_ptr in the 
associated thread control block TX_THREAD.



    Offset        Interrupted Stack Frame        Non-Interrupt Stack Frame

     0x00                   1                           0
     0x04                   s8  ($30)                   s8  ($30)
     0x08                   s7  ($23)                   s7  ($23)
     0x0C                   s6  ($22)                   s6  ($22)
     0x10                   s5  ($21)                   s5  ($21)
     0x14                   s4  ($20)                   s4  ($20)
     0x18                   s3  ($19)                   s3  ($19)
     0x1C                   s2  ($18)                   s2  ($18)
     0x20                   s1  ($17)                   s1  ($17)
     0x24                   s0  ($16)                   s0  ($16)
     0x28                   hi                          hi
     0x2C                   lo                          lo
     0x30                   t9  ($25)                   ra  ($31)    
     0x34                   t8  ($24)                   SR
     0x38                   t7  ($15)                   
     0x3C                   t6  ($14)                   
     0x40                   t5  ($13)                   
     0x44                   t4  ($12)                   
     0x48                   t3  ($11)                   
     0x4C                   t2  ($10)                   
     0x50                   t1  ($9)                    
     0x54                   t0  ($8)                    
     0x58                   a3  ($7)                    
     0x5C                   a2  ($6)                    
     0x60                   a1  ($5)                    
     0x64                   a0  ($4)                    
     0x68                   v1  ($3)                    
     0x6C                   v0  ($2)
     0x70                   at  ($1)
     0x74                   ra  ($31)
     0x78                   SR  
     0x7C                   EPC


9. 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 ThreadX run faster, you can change the tx.gpj project
to disable debug information and enable the desired optimizations. 

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


10. Interrupt Handling

ThreadX provides complete and high-performance interrupt handling for  MIPS32_4Kx
targets. The general exception handler is at address: 0x80000180 (0xA0000180 non-
cached). The ThreadX general exception handler is defined in the file 
tx_initialize_low_level.mip at the label _tx_exception_handler. A small piece of 
code to jump to this exception handler is copied to the general exception handler 
address during initialization.

10.1  Application ISRs

Multiple exceptions may be processed with a single execution of the exception 
handler. This is because the Cause register could indicate more than a single
exception. Processing for each exception is also located in the general 
exception handler that starts at the label: _tx_exception_handler. Application 
ISRs can be added into this handler.


11. Revision History

For generic code revision information, please refer to the readme_threadx_generic.txt
file, which is included in your distribution. The following details the revision
information associated with this specific port of ThreadX:

05/01/2010  ThreadX for MIPS32 4Kx using Green Hills tools version 5.2. This release includes 
            the following modifications:

            tx_port.h                           Changed version ID.            
            tx_thread_schedule.mip              Added execution change notification.
            tx_thread_context_restore.mip       Added execution change notification.
            tx_thread_context_save.mip          Added execution change notification.
            tx_thread_system_return.mip         Added execution change notification,  
                                                  and changed code to preserve
                                                  current time-slice value.
            *.mip                               Modified comment(s).

12/12/2008  ThreadX for MIPS32 4Kx using Green Hills tools version 5.1. This release includes 
            the following modifications:

            tx_port.h                           Modified version ID string, and changed 
                                                interrupt lockout to use status IE bit.
            tx_initialize_low_level.mip         Added logic to set IM bits.
            tx_thread_context_restore.mip       Changed interrupt lockout to use status 
                                                IE bit.
            tx_thread_interrupt_control.mip     Changed interrupt lockout to use status 
                                                IE bit.
            tx_thread_schedule.mip              Changed interrupt lockout to use status 
                                                IE bit.
            tx_thread_stack_build.mip           Changed to inherit initial status register.
            tx_thread_system_return.mip         Changed interrupt lockout to use status 
                                                IE bit.
            *.mip                               Modified comment(s).

12/12/2005  Initial ThreadX version of MIPS32 4Kx/Green Hills port. 


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


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

www.expresslogic.com

