![]() |
![]() |
![]() |
![]() |
![]() |
Compilation Flags
Compilation flags are used to decide the properties of the Cmicro Library and the generated C code. Both in the Cmicro Library and in the generated code #ifdef's are used to include or exclude parts of the code.
The switches used can be grouped:
- Flags defining the compiler
- Flags defining the properties of a compiler
- Flags defining the properties of the Cmicro Library
- Flags defining the implementation of a property
The first two groups are discussed in Adaptation to Compilers.
The remaining two groups are discussed under Manual Scaling and Automatic Scaling Included in Cmicro.
Use the default settings of these flags in order to reduce potential problems.
Manual Scaling
Users are able to scale some features of the Cmicro Library and the Cmicro Kernel in order to optimize the generated code. All the flags discussed in this section are used throughout the complete SDL system, therefore it is not possible to define flags for processes separately.
The manual scalings have to be done in the file ml_mcf.h. They are divided into the following groups:
- Cmicro Kernel/Library
- Support of SDL Constructs
- SDL Environment
- SDL Coder
- SDL Target Tester
- Communication Link and Compiler
In the following subsections, the way to configure the Cmicro Package by hand and all the available flags are described.
The user is asked to use the Targeting Expert to configure the Cmicro Package. A description of how to use the targeting Expert can be found in Targeting Work Flow.
To configure the Cmicro Package by hand, the user has to modify the file ml_mcf.h.
To use a Cmicro Package feature just define it in ml_mcf.h like
#define FLAG_NAME_AS_DESCRIBED_BELOWSometimes a flag just carries a value. In this case the user has to modify the value in ml_mcf.h
#define FLAG_CARRYING_VALUE VALUECmicro Kernel/Library
Kernel
General
- XMK_USE_KERNEL_INIT
- When this flag is defined, the Cmicro Kernel memsets all variables of the SDL processes to 0 before the process is created. This is useful to spare some ROM memory but has the disadvantage of a longer process creation phase. The ROM used by the yDef_SDL_* functions can be spared in this case where the initialization with 0 is appropriate.
- XMK_USE_SDL_SYSTEM_STOP
- Normally, it is unnecessary to have an SDL system stop in micro controller applications. An SDL system stop occurs if no living process in the SDL system exists and all queues are empty. This occurs if all process instances have executed an SDL stop and no create process action is open (create signal in any queue).
Defining XMK_USE_SDL_SYSTEM_STOP means that the C function main returns correctly with exit(...). To avoid this overhead in the Cmicro Kernel, the user should not define the above flag.
- XMK_SYSTEM_INFO
- If this flag is set, some functions available to get information about the SDL system during runtime. See Functions to get System Information
- XMK_USE_NO_AUTO_SCALING
- When this flag is defined, automatic scaling of SDL features is prevented. An example of flag usage is implementing a change to the SDL system which does not require re-compilation of the Cmicro Library. Note that if the number of processes, signals or timers is changed, the Cmicro Library must be re-compiled. The definitions contained in sdl_cfg.h are overwritten in ml_typ.h.
Kernel Limits
- XMK_USE_HUGE_TRANSITIONTABLES
- Per default the Cmicro Package can handle up to 252 different transitions per process. If the SDL system exceeds this size, it is necessary to set this flag. See Transition Table for further information.
Signal Structure
- XMK_USE_RECEIVER_PID_IN_SIGNAL
- When this flag is defined a receiver pid is included in each signal instance. It is possible to omit the receiver pid if the user writes a C function xRouteSignal() which is given as a template in mk_user.c. Each signal type is then mapped to a unique receiver. It is recommended to define this flag in small systems where unique receivers exist for each signal type. It is important to note that in the case of dynamically created processes an internal create signal is used. If there are any (x, N) where N > 1, declarations in the system, the create signal cannot contain the receiver pid. The receiver pid is necessary for correct creation of processes. Never leave it out when using dynamic process creation.
- XMK_MSG_BORDER_LEN
- The value of this macro gives the length of signal parameters carried inside the signal. Note: If the parameter length exceeds this value a memory allocation is performed and the signal parameters are copied into this buffer. The pointer to the allocated buffer is carried inside the signal's structure (see ml_typ.h for the typedef xmk_T_SIGNAL).
Signal Handling
Signal Queue
- XMK_USE_STATIC_QUEUE_ONLY
- Create signals only from the static memory. The static memory is predefined with XMK_MAX_SIGNALS.
- XMK_USE_STATIC_AND_DYNAMIC_QUEUE
- Create signals from the static memory which is predefined with XMK_MAX_SIGNALS. If more signals have to be inserted memory is allocated from the dynamic memory pool.
- XMK_MAX_SIGNALS
- In the Cmicro Package, the SDL queue is physically implemented as one queue for all processes. The define discussed in this section represents the maximum amount of signals in the static signal instance memory pool (see Dynamic Memory Allocation for more information). It may be difficult to evaluate the maximum entries required during run-time because this totally depends on how the SDL system is specified, and target hardware performance. It is for example, impossible to state how much time hardware requires to process an SDL signal.
By examining the SDL system it can be determined which processes have a long transition time and which processes send or receive more than one signal. Estimate by trying out worst case situations. A first estimation is also possible by calculating:
maximum amount of process instances * 3
For a more exact estimation the user should use the profiler contained in the SDL Target Tester to obtain the necessary information on how many entries are used during run time.
Another method of helping to determine the maximum amount of signals required by the system is to use the exception handling mechanism offered by the ErrorHandler, i.e. when the queue is full and another signal is to be inserted then the ErrorHandler function is called.
Light Integration
- XLI_INCLUDE
- The value of this is the name of the header file which is included in ml_typ.h when XLI_LIGHT_INTEGRATION is set. This file contains the definitions of the light integration macros. See Define the macros which are needed in the task function.
Tight Integration
The complexity of a tight integration is very high. But there is a generic solution available, which guides you through the integration.
Please contact IBM Rational local sales office/Professional Services for further information about this solution.
Error Handler
- XMK_USE_MAX_ERR_CHECK
- When this flag is defined, additional error checks are included in the generated code of the Cmicro Library. For further details, see the appropriate section on "errors and warnings". For example the Cmicro Kernel calls the ErrorHandler if a signal is sent to an undefined process (i.e. undefined pid value).
- XMK_ADD_PRINTF
- When this flag is defined some additional printf C function calls are compiled giving users more information about the internal work of the system. The printf function can be switched on separately for Cmicro Kernel, SDL Target Tester and SDL application. At a lower level, it can be switched on separately for each C module. Look at the defines in ml_typ.h, which are all named as XMK_ADD_PRINTF_*.
This flag must be undefined when compiling for the target, except in the case where there is a stdio implemented on the target. For correct compilation, the user must also set XMK_ADD_STDIO. If the user wishes to implement user specific printf functionality then this flag need not be set.Reactions on Warnings
- XMK_WARN_ACTION_HANG_UP
- If this flag is defined, the default behavior, if a warning is detected during SDL execution, is defined as "program hang up".
- The user might choose this reaction when there is no output device (like printf) available in the SDL program environment.
- The user should notice that a warning can lead to an illegal system behavior. As an example, this might come true for an implicit signal consumption. The system then hangs but the user might perhaps not be able to see the reason why this occurs. As a result, it is recommended to trace for warnings also.
Reaction on Errors
- XMK_ERR_ACTION_HANG_UP
- If this flag is defined, the default behavior, if a fatal system error is detected during SDL execution, is defined as "program hang up".
- The user might choose this reaction when there is no output device (like printf) available in the SDL program environment.
- The user should notice that if a fatal system error is ignored, this usually leads to an illegal system behavior. As an example, this might come true for any use of null pointer values, for which there is an error check. It is strongly recommended to trace for system errors and warnings.
Timer Scaling
If there are timers used within the SDL system, the timers have to be scaled.
Timer queue
- XMK_USE_GENERATED_AMOUNT_TIMER
- The code generator evaluates the amount of timers that are declared in the system. The result of this evaluation is then, after code generation, defined with XMK_MAX_TIMER_INST in the file sdl_cfg.h. Timer instances are, usually, implemented as a C array with Cmicro. If the XMK_USE_GENERATED_AMOUNT_TIMER flag is set, then the timer array is dimensioned with the evaluated amount (XMK_MAX_TIMER_INST).
- When timers with parameters are in the system, the automatically generated value XMK_MAX_TIMER_INST can be used to pre-define one timer instance of a timer declaration. If there are then more timers to be instantiated, dynamic memory allocation must take place. This cannot be evaluated by the code generator.
- As a result, if there are timers with parameters in the system, the user should think about how many timer instances there could be during execution and should decide upon the maximum amount by himself. In this way, memory consumption and performance can be balanced.
- XMK_MAX_TIMER_USER_VALUE
- If XMK_MAX_TIMER_USER is set, the value XMK_MAX_TIMER_USER_VALUE becomes meaningful. With this value, the user may specify how many timer instances should be predefined during compilation time. The predefined timer instances offer the advantage that no dynamic memory allocation is to be done for them. If the predefined amount of timer instances is exceeded, then dynamic memory allocation will occur. As a result, it is up to the user how he balances static and dynamic memory for timer instances by changing this value.
Execution Time
- XMK_USE_CHECK_TRANS_TIME
- When this flag is defined the time duration for each executed transition is checked against a predefined duration. If the executed duration is longer than the predefined duration set by the XMK_TRANS_TIME flag, the ErrorHandler() is called. The flag is only available when using a non preemptive Cmicro Kernel. No additional hardware is necessary as the evaluation is based on the SDL time value NOW which is provided by the same hardware source as for the system clock.
Signal Priorities
In the standard configuration of the Cmicro Kernel no signal priorities are used. So each signal sent is inserted at the end of the signal queue.
- XMK_USE_SIGNAL_PRIORITIES
- When this flag is defined, the header of each signal which is sent via the SDL queue has an additional entry, namely "priority". This is used to modify the ordering of signals in the queue.
This flag should be used in combination with using the #PRIO directive. It works for all the different scheduling methods.
If signal priorities are enabled, signal handling xmk_SendSimple has to be switched of.
- XMK_CREATE_PRIO
- Create signals can not be assigned a signal priority within the SDL system. As these signals are also handled over the signal queue, a default priority is necessary when signal priorities are selected (i.e. XMK_USE_SIGNAL_PRIORITIES is defined). A value between 0 (highest priority!) and 250 should be entered.
Preemption
Normally, the Cmicro Kernel is configured so that the simple scheduling policy is used, i.e. transitions of SDL processes are non interruptible.
The Cmicro preemptive kernel is only available if an according license is available.
- XMK_USE_PREEMPTIVE
- Usually the Cmicro Kernel is configured to "non preemptive". This means, that each transition must execute to its end, before the next transition can be processed.
This means, that the nextstate symbol of a process is executed, before the next SDL input can be handled. On the other hand, "preemptive scheduling" is useful, if an SDL process must directly execute when an external event from an interrupt source is detected and sent to the SDL system. In this case, an executing transition is possibly suspended, and another transition can be executed.
The kernel makes decisions based on the defined priority of processes when to schedule to another process. If the receiver of a signal which has been received from the environment (or a process inside the SDL system) has a higher priority than the currently executing process, the new signal is treated immediately.
A run-time error occurs if this definition is wrong. If the error checks are enabled, a check is made by the Cmicro Kernel and the C function ErrorHandler() is called if the check fails.
SDL Target Tester
Initialization
- XMK_ADD_MICRO_TESTER
- XMK_ADD_PROFILE
- XMK_ADD_MICRO_COMMAND
- This flag adds the command interface of the SDL Target Tester (please view The SDL Target Tester).
Trace
Trace Scaling
- XMK_USE_AUTO_MCOD
- Is this flag defined, the host get a further message for the message coder. Depending on this flag the Targeting Expert insert the entry `USE_AUTO_MCOD yes' into the sdtmt.opt file. The entrys LENGTH_, ENDIAN_, and ALIGN_ are ignored. For more information view The SDL Target Tester.
- XMK_ADD_SIGNAL_FILTER
- This flag conditionally compiles the signal filtering mechanism of the SDL Target Tester (please view The SDL Target Tester). With the signal filter, it is possible to specify that some signals should be traced while others are not.
- XMK_USE_SIGNAL_TIME_STAMP
- Defining this flag means that in the header of each signal which is sent via the SDL queue, there is an additional entry "time-stamp". When using the standard Cmicro Library, the Cmicro Kernel sets the time-stamp to NOW, if an SDL signal is inserted into the queue.
- This time-stamp is especially used by the Cmicro Recorder (XMK_ADD_MICRO_RECORDER) in order to enable the replay of an SDL session in simulated real-time.
- In other cases, the user is free to modify the type of time-stamp implementation.
Buffers
Recorder and Play
The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.
- XMK_ADD_MICRO_RECORDER
- This flag adds the functions of the record mode of the Cmicro Recorder (please view The SDL Target Tester).
Support of SDL Constructs
Predefined Sorts
Character Strings
- XRESTUSEOFCHARSTRING
- This flag must be seen in combination with XNOUSEOFCHARSTRING, which forbids the use of SDL charstrings. If this flag is set, SDL charstrings are only supported in a restricted way. I.e. constant character buffers are used in this implementation.
- As a third possible way XRESTUSEOFCHARSTRING and XNOUSEOFCHARSTRING should both be undefined to enable a full support of SDL charstrings.
The Cmicro Recorder is not able to handle SDL charstrings within signal parameters.
Predefined Sorts
- XNO_LONG_MACROS
- The setting of this flag prevents the use of predefined generators (please view sctpredg.h, sctpred.h and sctpred.c). This can be done to reduce the target's memory size. But must be done for some specific compilers as these are not able to handle long macro definitions. Please view the appropriate compiler section in ml_typ.h (Adaptation to Compilers)
ASN.1 Sorts
Error Checks
This flag should be used for testing purposes but uses lots of code size within the target.
- XERANGE
XTESTF
- These flags define that an SDL syntype is to be checked against its defined range. If the flags are not set, the code to perform this check is left out. The flag should be set for allowing better error checks, but may be unset for optimizing the target program code, as the checks occupy a lot of memory.
Size of Variables
- X_COMPACT_BOOL
- This flag defines that an SDL boolean is translated to unsigned char, when it is set. Otherwise each SDL boolean is translated to integer. Usually this flag should be left set, as it is in the default setting. An exception might become true when a C compiler can handle integer values more efficient than char values.
- X_SHORT_REAL
- When this flag is defined, then each SDL real value is translated to a float in C. If it is not defined, Cmicro assumes SDL real values are C double values. The user must take care that at no place in the SDL system there is a real value used that exceeds the maximum range of the appropriate C type.
Use of Memory
Memory Management
- XMK_USE_SDL_MEM
- If this flag is defined, then the Cmicro Kernel can use the dynamic memory management functions contained in the ml_mem module (xmk_Malloc(), xmk_Calloc() and xmk_Free()). This is necessary if the compiler in use has no malloc/free or if the user wishes to modify the standard behavior of these functions, i.e. using a best fit, instead of first fit searching algorithm. The user should refer to Dynamic Memory Allocation Functions - Cmicro also.
String Functions
SDL environment
- XMK_USE_xInitEnv
- This flag enables the C function xInitEnv() which is generated as a template in file env.c by the Targeting Expert.
- XMK_USE_xInEnv
- This flag enables the C function xInEnv() which is generated as a template in file env.c by the Targeting Expert.
- XMK_USE_xOutEnv
- This flag enables the C function xOutEnv() which is generated as a template in file env.c by the Targeting Expert.
- XMK_USE_SEND_ENV_FUNCTION
- This flag make it possible to use an alternative function to send signals to the environment. This is needed if the used compiler does not support re-entrant functions. The disadvantage of this implementation exists in the missing error checks. See Alternative Function for sending to the Environment
- XMK_ADD_STDIO
- The Cmicro Package is mainly intended for target implementation. However on some occasions the user may wish to use OS features. Normally this flag is undefined when compiling for the target system but may be defined if stdio is available and required on the target system.
Defining XMK_ADD_STDIO without setting XMK_ADD_PRINTF allows the user to exclude the default printfs of the Cmicro Library and instead implement user defined printfs.Automatic Scaling Included in Cmicro
The flags described in this section are automatically generated into the file sdl_cfg.h by the Cmicro SDL to C Compiler. The purpose is to exclude parts of the C code in order to reduce the generated code. Features or functions which are not required in the SDL description produce no (or only a small) overhead in the generated code.
If the user does not wish to employ automatic scaling facilities, for example if test and debugging proves too difficult, then simply define the flags XMK_USE_NO_AUTO_SCALING.
All the flags discussed in this section are used on the whole SDL system i.e. it is not possible to define flags for processes separately.
The Targeting Expert will use these flags, too, to optimize and ease the manual scaling.
- XMK_USED_ONLY_X_1
- XMK_USED_DYNAMIC_CREATE
- XMK_USED_DYNAMIC_STOP
- XMK_USED_SAVE
- If this flag is generated as defined, the SDL system uses the save feature of SDL. Using save means that there has to be additional overhead in each signal stored in the SDL queue (each signal is tagged as save or not save).
The save construct, although a useful construct for manipulation of the SDL FIFO queue mechanism, unfortunately imposes a large code overhead. The user should avoid the utilization of this construct where possible.- XMK_USED_TIMER
It is possible to implement a user defined timer model by un-defining these flags and defining some other macros.
It is not recommended in each case (because it is not SDL conform), but is possible to send parameters via global parameters by using C code in SDL.
- XMK_USED_TIMER_WITH_PARAMS
- This define is generated if there is at least on timer with parameter used in the system. If this is the case, additional functionality for this construct is added when the kernel is compiled. The timer operations will result in producing more overhead, both symbol by symbol and overhead in the kernel compared with the case if there are no timers with parameters defined.
- XMK_USED_SENDER, XMK_USED_PARENT, XMK_USED_OFFSPRING, XMK_USED_SELF
- XMK_USED_PWOS
Automatic Dimensioning in Cmicro
Some resources of the Cmicro Library are automatically dimensioned. These are described in the following subsections.
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |