File: @(#)r3ctmiREADME.txt	1.1 - 03/18/02

PROGRAM: Recon3 C/C++ Trace Manager Interface (r3ctmi)

SYNOPSIS:
The Recon3 C/C++ Trace Manager consists of two parts:
  - The Trace Manager Interface (r3ctmi) consisting of functions which
    are linked into the program that the user wants to trace. Calls
    to these functions cause trace records to be written to shared
    memory.
  - The Trace Manager Client (r3ctmc), a program that runs concurrently
    with the user's program. r3ctmc reads the trace records from
    shared memory and writes them to files (or elsewhere). r3ctmc
    also provides extensive facilities to control tracing on the
    fly, including turning tracing on and off selectively, changing
    the data content of each trace record, switching output from
    one file to another, etc.

This README file refers primarily to the Trace Manager Interface r3ctmi.

See the Recon3 web site at:
              http://www.cs.uwf.edu/~recon
for more information about how to use the different tools in the
Recon3 toolset. In accepting and using Recon3 you agree to the Disclaimer
of Warranty posted on that web site.

The functions that make up the Trace Manager Interface r3ctmi are:

   #include "r3ctminf.h"
   int  R3TmiOpen(void);
   void R3TmiClose(void);
   int  R3TmiReady(void);
   void R3TmiComment(char *);
   void R3TmiBlock(char *, int, int);
   int  R3TmiTrue(char *, int);
   int  R3TmiFalse(char *, int);
   int  R3TmiSwitch(char *, int, int);
   int  R3TmiEntry(char *, int, char *);
   void R3TmiReturn(char *, int, char *);
   int  R3TmiExit(char *, int, int);
   void R3TmiStart(char *, int, char *);
   void R3TmiRendevous(char *, int, char *);
   void R3TmiStop(char *, int, char *);
   void R3TmiUser(char *, int, char *);
   void R3TmiResume(void);
   void R3TmiSuspend(void);

For a precise description of each of these functions see Table 1
of the "Recon 3 C/C++ Trace Manager SRS", file r3ctsrs.htm.

DESCRIPTION:
Calls to the above listed functions are inserted into the program
the user wishes to trace (denominated the "target program") either
by hand or by an automatic "instrumentor" program such as the
Recon C/C++ instrumentor (r3cinst). The resulting "instrumented
target program" is then compiled and executed following the
user's normal build procedures.

At compile time, the user must define a target operating system
and a target architecture by defining appropriate preprocessor macros.
This may be done either:
  1. By uncommenting #define directives located in the file r3.h
  2. By specifying the macro on the compile command line, e.g.
       gcc -D R3_ARC_EXTENDED ... 
  3. By specifying the macro in the user's development environment

Please see the file r3.h for the available choices of operating system.

The two target architectures currently available are:
R3_ARC_BASIC (Recon3 Basic Architecture) and R3_ARC_EXTENDED
(Recon3 Extended Architecture).

The files r3ctminf.c and (for the Extended Architecture)
r3ulbsys.c need to be compiled and linked with the target program.
The header files r3.h, r3ctminf.h and r3ulbsys.h may also be needed.

When the instrumented target program is executed, the calls to the
functions cause trace records to be written. However the exact
behavior depends on the target architecture.

If R3_ARC_BASIC (the Recon3 Basic Architecture) was chosen,
each trace record is written immediately
to a file. The file name is specified in r3ctminf.h as
   #define R3T_OUT_FILENAME_DEFAULT "default.r3t"
but may be changed by the user before compilation if so desired.

If R3_ARC_EXTENDED (the Recon3 Extended Architecture) was chosen,
then each function first looks for a shared memory connection exists to
a Trace Manager Client (r3ctmc) process. If the connection exists
the trace record data is written to shared memory; the r3ctmc
process should pick up the record, process it as needed, and
eventually write it. If no shared memory connection can be established,
no trace data is written. (To reduce overhead when tracing
is not being used, the value of R3T_FAILURE_DELAY can be
set in r3ctminf.h to keep this check from being repeated on every
call).

The Recon3 Extended Architecture is recommended for multi-process
or multi-thread programs. It also allows the Trace Manager Client
(r3ctmc) to be used to control tracing on-the-fly, including
turning tracing on and off selectively, changing the data content
of each trace record, switching output from one file to another, etc. 

For the format of each trace record see Section 3.3 of "The
Architecture of Recon3", file r3uarch.htm.

SEE ALSO:

   r3ctmcREADME.txt - README file for the Recon3 C/C++ Trace Manager Client

The following documentation used by the Recon3 development team
provides detailed specifications which may be useful:

  r3uarch.htm - The Architecture of Recon3.
     Provides an overall description of the toolset, its design
     criteria, the relationships between the different tools,
     the different architectures (Basic, Extended, etc.), the
     different kinds of program events which may be traced,
     trace record and file formats in different modes, etc.

  r3csrs.htm - Recon Instrumentor for C/C++ - SRS.
     Provides a detailed Software Requirements Specification (SRS) for
     the Recon3 C/C++ instrumentor (r3cinst).

  r3ctsrs.htm - Recon3 C/C++ Trace Manager - SRS
     Provides a detailed Software Requirements Specification (SRS) for
     the Recon3 C/C++ trace manager (r3ctmc).