![]() |
![]() |
![]() |
![]() |
![]() |
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.
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.
ml_typ.h
This file is the central header file in the Cmicro Package. It contains
- more #includes
- defines which are of global interest and Cmicro Library internal defines
- typedefs which are of global interest and Cmicro Library internal typedefs
- extern-declarations which are of global interest and Cmicro Library internal extern declarations
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.
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_TRUEThis 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:
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.
- Any value in the range of 0x00 to 0xff.
- A value != 0x00 switches the trace for the signal on.
- A value == 0x00 causes the trace for the given signal(s) to be switched off.
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.
#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')USER: Hello SDL worldThe 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:
- switch the record mode of the Cmicro Recorder on, or
- switch the play mode of the Cmicro Recorder on, or
- switch any function of the Cmicro Recorder off.
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 ReceiverThis 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, Inint *p_MessageClass, Outint *p_MessageTag, Outint *p_MessageLength, Outchar *p_dest, In/Outint dest_len ) InThis 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.
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_COMMLINKScaling 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_TESTERRemoving the Cmicro Tracer
This is possible by specifying
#define XMK_ADD_MICRO_TESTER#undef XMK_ADD_MICRO_TRACERRemoving the Cmicro Recorder (Inclusive Play Mode)
This is possible by specifying
#define XMK_ADD_MICRO_TESTER#undef XMK_ADD_MICRO_RECORDERRemoving the Command and Debug Interface
This is possible by specifying
#define XMK_ADD_MICRO_TESTER#undef XMK_ADD_MICRO_COMMANDPartial 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.
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:
#define XMK_MAX_SEND_ONE_ENTRY 1000#define XMK_MAX_SEND_ENTRIES 20#define XMK_MAX_RECEIVE_ONE_ENTRY 1000#define XMK_MAX_RECEIVE_ENTRIES 20where *_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 |
![]() |
![]() |
![]() |
![]() |