########################################################################
     TTT         Real-Time Data Exchange RTDX(TM) Assembly Interface
     TTT i
 TTTTT  TiTTTT   This file contains information on how to use the RTDX
  T     -i-   T  Assembly macro include file to create RTDX applications
   TTT   i    T  for the C54X target.
    T TT    TT   
        TT TT    
          TTT    Copyright 1997-1998 Texas Instruments
            TT   RTDX is a trademark of Texas Instruments
########################################################################

The RTDX assembly macro include file can be used to interface to RTDX
at the assembly level.

########################################################################

I.   Assembly Interface Specification
II.  Examples
III. Release Notes

########################################################################


########################################################################

I.   Assembly Interface Specification
________________________________________________________________________

* The following four macros are used to declare RTDX control structures.

RTDX_input_channel ichan

        - Declare an input data channel (3 words in .bss section).

        Parameters:
                   ichan - A label for the input channel

RTDX_output_channel ochan

        - Declare an output data channel (3 words in .bss section).

        Parameters:
                   ochan - A label for the output channel

RTDX_event event,class

        - Declare an event and specify its event class
          (1 word in .bss section).

        Parameters:
                   event - A label for the an event
                   class - The class bit mask

RTDX_e_class_set eclass

        - Declare an event class (1 word in .bss section).

        Parameters:
                   eclass - A label for an event class

* The following macros call RTDX procedures for various purposes.
* Input channels, output channels & events have to be declared
  using the declaration macros previously listed.
* Registers and immediate data may be used for all other parameters

RTDX_Enable_Data_Output ochan

        - Enable an output channel

        Parameters:
                   ochan - Bitmask of event class(es) to enable

RTDX_Disable_Data_Output ochan

        - Disable an output channel

        Parameters:
                   ochan - Bitmask of event class(es) to enable

RTDX_Enable_Data_Input ichan

        - Enable an input channel

        Parameters:
                   ichan - The address of the input channel

RTDX_Disable_Data_Input ichan

        - Disable an input channel

        Parameters:
                   ichan - The address of the input channel

RTDX_Enable_Event_Class eclass

        - Enable an event class for recording

        Parameters:
                   eclass - The address of the event class

RTDX_Disable_Event_Class eclass

        - Disable an event class from recording

        Parameters:
                   eclass - The address of the event class

RTDX_Data_Write ochan,buffptr,bsize

        - Write data to the output data channel.

        Parameters:
                   ochan   - The address of the output channel
                   buffptr - A pointer to the buffer containing the data
                   bsize   - The size of the buffer in address units

RTDX_Data_Read ichan,buffptr,bsize

        - Declare and initialize buffer "buffptr" to receive data.  Read
          data from the input data channel.

        Parameters:
                   ichan   - The address of the input channel
                   buffptr - A pointer to the buffer that will receive
                             the data
                   bsize   - The size of the buffer in address units

RTDX_Data_Read_NB ichan,buffptr,bsize

        - Declare and initialize buffer "buffptr" to receive data.  Read
          data from the input data channel without blocking for data.

        Parameters:
                   ichan   - The address of the input channel
                   buffptr - A pointer to the buffer that will receive
                             the data
                   bsize   - The size of the buffer in address units

RTDX_Channel_Busy chan

        - This macro was designed to be used with RTDX_Data_Read_NB.
          This macro loads the status of the channel into the
          Accumulator.

        Parameters:
                   chan - The address of the channel

RTDX_Bytes_Read ichan,bsize

        - This macro was designed to be used with RTDX_Bytes_Read_NB.
          This macro compares the number of bytes read with the number
          of bytes expected.

        Parameters:
                   ichan - The address of the input channel
                   bsize - The expected number of bytes read

RTDX_Log_Event event

        - Record the occurrence of an event.  No additional data is
          recorded.

        Parameters:
                   event - The address of the event

RTDX_Log_Event_Data event,buffptr,bsize

        - Record the occurence of an event and also record additional
          data.

        Parameters:
                   event   - The address of the event
                   buffptr - A pointer to a buffer of related data to be
                             recorded
                   bsize   - The size of the buffer in address units

Note: Most of these macros call funtions within the RTDX user interface.
      Please see the User Library Interface, within the RTDX On-line
      help, for further information.

########################################################################


########################################################################

II.  Examples
________________________________________________________________________


* Use the batch file, make.bat, to build examples.
  ex.
     make Ta_write

Ta_write.asm

        - Target to Host transmission test.
          This test sends 100 consecutive integers starting from 0.
          Use the "h_read" VB macro of the Excel project, rtdx.xls, to
          view data on the host.

Ta_read.asm - Host to Target transmission test.
   
        - This test reads 100 integers
          Use the "h_write" VB macro of the Excel project, rtdx.xls, to
          send data to the target.

event.asm - Event logging test.
        - This test logs 2 events.  The first event (event) does not
          have data attached to it.  The second one (eventB) does.
          Use The Console Event Display to view data.

          Ex.
             EventProg.exe -2 2

             Enter a name(MAX of 80 CHARS.) for event 1 >event
             Enter a name(MAX of 80 CHARS.) for event 2 >eventB
        
########################################################################


########################################################################

III. Release Notes
________________________________________________________________________
- Programs must be linked with the C Runtimes.
  Programs must contain the symbol "_main".
- The CPL bit must be set before macros call the RTDX functions.
  See section 4.3 (Function Calling Conventions) of the TMS320C54x
  Optimizing C Compiler User's Guide for instructions on how to pass
  parameters to C functions.
- Registers AR1, AR6, AR7 & SP must be preserved.  See section 4.4.1
  (Assembly Language Modules) of the TMS320C54x Optimizing C Compiler
  User's Guide.

########################################################################