IBM
Contents Index Previous Next



The Target Library


General

The target library is a mandatory part of the SDL Target Tester. The SDL Target Tester is of no use without the functions and definitions contained within.

In order to use the options of SDL Target Tester's host site, the target library must be configured accordingly.

A lot of defines make it possible to reduce the SDL Target Tester's functions within the target, so that memory requirements can be reduced when necessary.

In the following sections are explanations of the file structure and the application program interface (API) within the target.

File Structure

The following picture explains the file structure for the SDL Target Testers target library.

Figure 611 : Files of the Cmicro Library

Description of Files

sdl_cfg.h

This file is generated automatically by the Cmicro SDL to C Compiler into the directory which is currently active. It contains compilation flags used for the automatic scaling of the Cmicro Library and the generated C code. The file must not be edited by the user.

Caution!

This file always carries the same name for each SDL system generated and is stored into the currently active directory. A conflict will occur if the user tries to generate several systems into the same directory.

Therefore be sure to use different working directories for each SDL system. Otherwise, unpredictable results during run-time of the generated code will occur, as some automatic scalable features may not re-compiled.

ml_typ.h

This file is the central header file in the Cmicro Package. It contains

tmcod.h

tmcod.h is an automatically generated file of the Target Message Coder Generator (TMCOD). All the SDL Target Tester command tags and the corresponding parameter structures are defined here. It is strongly recommended not to modify this file.

mt_cmd.c

This file is part of the command interface on the target site. The commands received via the communications link will be performed by this file.

mt_cod.c

This is the module which exports the functions to encode / decode any message from the Cmicro Protocol.

mt_opt.c

This module exports the functions which allow the user to define options regarding the tracer, recorder and player components.

Options may be specified to reduce the traffic load of the system, This is important when a slow communications interface is involved and the user wants to test in real-time.

mt_play.c

This file is part of the Cmicro Recorder and it contains all the functions for the play mode.

mt_rec.c

This file is part of the Cmicro Recorder and it contains all the functions for the record mode.

mt_tsdl.c

This module exports functions to trace SDL actions. These functions are mainly for the use of the Cmicro Kernel and Tester.

Functions to trace either into RAM, into a file or via a V.24 interface are delivered.

The module is common for all these trace methods. The functions exported are called directly by the Cmicro Kernel if the SDL Target Tester or part of the SDL Target Tester is involved when executing the SDL system.

mt_tsys.c

This module contains the functions which handle the trace of system events such as scheduler events or the trace of system errors.

mt_*.h

These header files contain the external definitions of the corresponding .c files.

The API on Target

General

The C application program interface (API) can be used both by SDL processes and / or by any other C function on the target.

The simplest method, however, is to set some options before initializing the SDL system and hold these options during the whole run-time. A more comfortable method is to set some options before initializing the SDL system and then change the options in an SDL process, when a specific situation is detected. By using this method it is possible to reduce the amount of information and to make it easier to find unwanted behavior or an erroneous situation in a trace. This can be achieved, for example, by writing the necessary C function call(s) into an SDL task symbol using the #CODE directive.

The following pages introduce the C function interface, which is used in the target to set the trace options.

Caution!

It is important to take care with function parameters. Any function return value should also be checked.

Initialization

void xmk_InitOptions ( void )

Initialization of the SDL Target Tester is absolutely necessary. It must be done before any other initialization, directly before the C function call xmk_InitSDL. The user should not remove this function call in the template main() function if one wants to use the SDL Target Tester.

Nothing happens before the C function xmk_OptionsSymbol is called, and xmk_TracerActive is set to XMK_TRUE.

Switch the Cmicro Tracer on / off

In order to get an execution trace it is first necessary to switch it on by assigning

xmk_TracerActive = XMK_TRUE

This should normally be done after the C function xmk_InitOptions.

The settings of functions whose names begin with xmk_Options* remains unaffected when changing the above flag.

The flag is not set by default.

Selecting SDL Symbols That are to Be Traced

xmk_OPT_INT xmk_OptionsSymbol ( unsigned char process-type-id,
                                long bitmask )

This function must be called in order to begin the trace. By default, no symbol is selected.

Select the trace for process-type-id and then set or un-set different symbols with the bit mask. If anything goes wrong the function will return XMK_ERROR, else XMK_OKAY.

It is possible to specify bit mask values for a specific SDL process, for all SDL processes, for the environment and for the kernel part of the Cmicro Library. The last possibility is necessary to allow the optional trace for system events like error trace and trace of scheduling events.

Allowed values for process-type-id:

0

First process-type-id, XPTID_ from sdl_cfg.h

1

Second.....

N-1

Last... (N is the maximum number of process types)

xNULLTYPE

specify trace for all processes

any other value

The environment

MICROKERNEL

specify trace for Cmicro Kernel

ENV

Indicates the SDL environment

Allowed values for bit mask:

SDL symbols System events

TSDL_STATE

TSYS_SCHEDULE

TSDL_INPUT

TSYS_ERROR

TSDL_SAVE

TSYS_SHOWPRIO

TSDL_OUTPUT


TSDL_CREATE


TSDL_STOP


TSDL_STATIC_CREATE


TSDL_DYNAMIC_CREATE


TSDL_DECISION


TSDL_TASK


TSDL_PROCEDURE


TSDL_RESULT


TSDL_TIMER


TSDL_SET


TSDL_RESET


TSDL_ACTUAL_RESET


TSDL_SIGNALPARAMS


TSDL_DISCARD


TSDL_IMPLICIT_CONSUMPTION


Selecting SDL Signals to Be Traced

xmk_OPT_INT  xmk_OptionsSignal ( xmk_T_SIGNAL signal id,  
                                 unsigned char bitmask )

This function is optionally called because the trace of all SDL signals is switched on per default.

Select the trace for signal id. Then set or un-set different symbols with bit mask. If anything went wrong, the function will return XMK_ERROR, else XMK_OKAY.

It is possible to specify either "off" for all signals, "on" for all signals, "off" for a specific signal or "on" for a specific signal.

Allowed values for signal-id:

0

First signal-id, #define from generated

C code and <systemname>.ifc

1

Second.....

N-1

Last.....

XMK_ALLOW_NO

Specify trace for all processes

XMK_ALLOW_ALL

Specify trace for Cmicro Kernel

Allowed values for bitmask:

Example to Set Trace Options

A simple method to set the trace options is to set them directly within the C function main, before the Cmicro Kernel is initialized. The user will find this example as a template in the file bare_ex.c delivered with the Cmicro Package, below the directory <sdtdir>/cmicro/template.

Example 623

#include "sdl_cfg.h"
#include "ml_typ.h"
    ... main ( ... )    {
  extern int xmk_TracerActive ;
  long       bitmask = 0      ;
  int        result  = XMK_OKAY ;

/* Initialize SDL Target Tester */
xmk_InitOptions ( );

/* Set all options ON */
result = xmk_OptionsSymbol (xNULLPID, 0xffffffff);
if (result != XMK_OKAY) ErrorInUsage ();

/* Set some options ON */
bitmask = TSDL_INPUT  ;
bitmask = TSDL_STATE  ;
bitmask = TSDL_OUTPUT ;

                 /*          +---- Proces-Type - Id (see automatically */
                 /*          |     generated file *.ifc)               */
                 /*          V                                         */
 result = xmk_OptionsSymbol (0, bitmask );
 if (result != XMK_OKAY) ErrorInUsage ();
 result = xmk_OptionsSymbol (1, 0x00000000 );
 if (result != XMK_OKAY) ErrorInUsage ();

/* S w i t c h   o n   t h e   t r a c e */
xmk_TracerActive                 = XMK_TRUE ;
/* Template to set options to filter signals */
                    /*                                           */
                    /* +---- Allow all Signals to be traced      */
                    /* V                                         */
 xmk_OptionsSignal (XMK_ALLOW_NO, 0);
                 /* +---- Signal id is to be set correctly !    */
                 /* |     according to the automatically        */
                 /* |     generated *.ifc - file                */
                 /* V                                           */
 xmk_OptionsSignal (1, 0xff);
 xmk_OptionsSignal (2, 0xff);
 xmk_OptionsSignal (3, 0xff);
/* I n i t i a l i z e   C m i c r o   K e r n e l */
xmk_InitSDL ()

/* R u n   C m i c r o   K e r n e l */
if (xmk_RunSDL (0xff) != XMK_STOP);
exit (0);  
}

Getting a Trace in SDL Tasks with C Code

The Cmicro SDL to C Compiler generates usable traces for SDL tasks only if it is a task containing at least one SDL assignment. Whenever C code is specified within a task symbol (by using the #CODE directive), the Cmicro SDL to C Compiler is not able to generate good trace information.

There are two C functions which enable a work-around:

in order to get a trace from C code. The trace output of a call like

 xmk_PrintString ('Hello SDL world')

looks like:

USER:   Hello SDL world

The strings have to be unique, in order to distinguish a trace of one process from another. Another difference between the above function is that the C function xmk_PrintString does not check if a trace is wanted or not. The trace will be done unconditionally via the SDL Target Tester's communications link.

Of course, the function may also be applied in non SDL program parts.

Using Record or Play Mode of the Cmicro Recorder

xmk_OPT_INT xmk_SetRecorderMode ( int mode )

This function must be called by the user in order to:

Allowed values for mode:

Environment Functions

xInEnv ()

void  xInEnv ( void )

This function is called each time the Cmicro Kernel's main loop is entered. A more detailed description of the C function xInEnv() can be found in xInEnv().

xOutEnv ()

int  xOutEnv ( xmk_T_SIGNAL sig,
               xmk_T_PRIO prio,
               xmk_T_MESS_LENGTH data_len,
               void *p_data,
               xPID Receiver

This function is called each time the SDL system wants to output a signal to the environment. If the environment should be another system (e.g., an MS DOS PC), the signal can be sent directly by calling the C function xmk_Cod_Encode (which is described in the following section). A more detailed description of the C function xOutEnv can be found in xOutEnv().

xmk_Cod_Decode ()

int  xmk_Cod_Decode ( char *p_RAWBuffer,     In
                      int *p_MessageClass,   Out
                      int *p_MessageTag,     Out
                      int *p_MessageLength,  Out
                      char *p_dest,          In/Out
                      int dest_len )         In

This function is free to be used on the target site. It decodes a given data link frame in the Cmicro Protocol format into the different pieces of data. MessageClass may be in the range from F3h to FFh. The value Fh in the higher nibble is used to synchronize the data stream if synchronization fails and 0h to 2h in the lower nibble is used by the SDL Target Tester itself. MessageTag may be of any value. p_struct is a pointer to a C structure which is to be transferred via the communications link. Struct_length is the result of the sizeof operator being applied to this structure.

The function is the counterpart to the C function xmk_Cod_Encode.

xmk_Cod_Encode ()

 int  xmk_Cod_Encode ( int MessageClass, 
                       int MessageTag, 
                       char *p_data, 
                       int length )

This function is free to be used on the target site: It encodes the given information into a data link frame of the Cmicro Protocol format and sends it via the communications interface. MessageClass may be in the range from F3h to FFh, the value Fh in the higher nibble is used to synchronize the data stream if synchronization fails and 0h to 2h in the lower nibble is used by the SDL Target Tester itself. MessageTag may be of any value. p_struct is a pointer to a C structure which is to be transferred via the communications link. Struct_length is the result of the sizeof operator being applied to this structure.

The function is the counterpart to the C function xmk_Cod_Decode.

Note:

The maximum amount of characters which can be transferred is restricted to 255 per default in this Cmicro Package version.

Compiling and Linking the Target Library

Some defines are to be set in order to compile and link the parts of the SDL Target Tester correctly. These defines can be set either on the command line when invoking make or in the header file ml_mcf.h. Be sure that for each configuration possibility all the defines are set appropriately.

The best way to select the compiler options for the SDL Target Tester is to use the Targeting Expert. Please view the section Configure the SDL Target Tester (Cmicro only).

Here is a first idea of what has to be to set in the configuration file ml_mcf.h:

#define XMK_ADD_MICRO_TESTER
#define XMK_ADD_MICRO_TRACER
#define XMK_USE_V24
#define XMK_USE_COMMLINK

Scaling of SDL Target Tester Functionality

In order to reduce the amount of memory - e.g. if memory gets scarce within a progressing project - it is possible to reduce the SDL Target Tester's functionality on target site.

Removing the whole SDL Target Tester

It is quite simple to remove any functionality used by the SDL Target Tester by specifying:

#undef XMK_ADD_MICRO_TESTER
Removing the Cmicro Tracer

This is possible by specifying

#define  XMK_ADD_MICRO_TESTER
#undef   XMK_ADD_MICRO_TRACER
Removing the Cmicro Recorder (Inclusive Play Mode)

This is possible by specifying

#define  XMK_ADD_MICRO_TESTER
#undef   XMK_ADD_MICRO_RECORDER
Removing the Command and Debug Interface

This is possible by specifying

#define  XMK_ADD_MICRO_TESTER
#undef   XMK_ADD_MICRO_COMMAND

Partial functionality may be left out by un-defining one of the defines described under Message Transfer and Presentation of Messages.

Configuration of Buffers

Users must configure buffers used by the SDL Target Tester.

The reason behind this is that the SDL Target Tester uses an efficient way to handle those buffers. This is of great importance especially for micro controllers.

Additionally, these buffers must be consistently dimensioned. For instance, the message buffer of the communications link must be able to handle the largest parameter list of a signal from SDL. The same situation arises in the trace of SDL tasks and procedure names.

Caution!

If any buffer is dimensioned too small a run-time error may result.

The following defines are used to dimension buffers.

XMK_MAX_PRINT_STRING

This define restricts the amount of characters transferred via the communications link when using the C function xmk_PrintString. This function is used only by the user.

XMK_MAX_LEN_SYMBOL_NAME

This define is used to restrict the amount of characters transferred via the communications link for the SDL tasks and SDL procedure names.

The transmit and receive buffers of the default communications link software must be configured in the data link (dl) module using the following defines:

Transmitter buffer:

#define XMK_MAX_SEND_ONE_ENTRY          1000
#define XMK_MAX_SEND_ENTRIES            20

Receiver buffer:

#define XMK_MAX_RECEIVE_ONE_ENTRY       1000
#define XMK_MAX_RECEIVE_ENTRIES         20

where *_ONE_ENTRY is the dimensioning of one message, and *_ENTRIES is the maximum amount of entries in the message FIFO of the data link module. Note, that *_ONE_ENTRY must be greater than the greatest of the XMK_MAX_* defines above, plus a reserve of 6 bytes.


http://www.ibm.com/rational
Contents Index Previous Next