IBM
Contents Index Previous Next



Functions of the Basic Cmicro Kernel


The list in the following section gives an overview of the functions exported by each module of the Cmicro Library in order to understand the module structure. The functions declared as static are not considered here.

If there is a reference to xmk_RAM_ptr, this can be replaced with a * (star) usually. This means that for example the declaration

xmk_T_CMD_QUERY_QUEUE_CNF xmk_RAM_ptr qinfo 

can be replaced with

xmk_T_CMD_QUERY_QUEUE_CNF *qinfo

which means to refer to a pointer to an object of the type xmk_T_CMD_QUERY_QUEUE_CNF.

Exported from env.c

xInitEnv

Parameters:

In/Out: -no-
Return: -no-

This function is called by the Cmicro Kernel during initialization of the
SDL system. The user may include initialization of the environment here.

xInEnv

Parameters:

In/Out: -no-
Return: -no-

This function is called by the Cmicro Kernel continuously to retrieve signals polled from the environment. Use the Cmicro Kernel function xmk_Send* to put signals into the system. The use of this function is not absolutely necessary in the case where the Cmicro Kernel is scaled to preemption and all external Events are put into the SDL system via an Interrupt Service Routines.

xOutEnv

Parameters:

In/Out:	 xmk_T_SIGNAL             sig,
	 xmk_T_PRIO               prio,
	 unsigned char            data_len,
	 void	 	 	 *p_data,
	 xPID	 	 	 Receiver

Return: xmk_OPT_INT

This function is called by the Cmicro Kernel if an SDL signal is to be sent to the environment.

Note:

The user has several possibilities to send signals to the environment. Please refer to the subsection about the Functions of the Expanded Cmicro Kernel.

The function must return with XMK_TRUE, if the Signal was sent to the environment, otherwise it must return with XMK_FALSE.

xCloseEnv

Parameters:

In/Out: -no-
Return: -no-

This function is called by the Cmicro Kernel during the exit phase of the
SDL system. The user may include de-initialization of the environment here.

Exported from mk_user.c

xSDLOpError

Parameters:

In/Out: char *xmk_String1 - SDL ADT operators name
	 char *xmk_String2 - The reason for failure
Return: -no-

This is a function which is to filled up by the user. The function is an central error handling function for ADTs. It is compiled only if XECSOP was defined in ml_mcf.h.

ErrorHandler

Parameters:

In/Out: int ErrorNo - the given error number
Return: -no-

This is a function which is to be filled out by the user. The Cmicro Kernel as well as the SDL application are the main clients of this function.

The user may distinguish between the different errors and define a specific reaction.

The different errors defined in the file ml_err.h below the Cmicro Kernel directory.

WatchdogTrigger

Parameters:

In/Out: -no-
Return: -no-

Description:
If selected this function is called by the Cmicro Kernel each time an SDL transition is executed

Caution!

Be sure, that the time-out used for the Watchdog is longer than the longest SDL Transition (in the case of non preemptive Cmicro Kernel). If the preemptive Cmicro Kernel configuration is used, then the Watchdog Trigger should not be used because the execution time of transitions cannot be calculated.

xRouteSignal

Parameters:

In/Out: xmk_T_SIGNAL xmk_TmpSignalID - Signal ID 
Return: xPID  Process - PID or xNULLPID
	 if no receiver is defined for the given
	 signal.

Description:
This function is called by the Cmicro Kernel, if SDL signals have no receiver. (undef XMK_USE_RECEIVER_PID_IN_SIGNAL) This might be useful in very small systems in order to spare some RAM memory.The following restrictions apply:

Note:

Timers are represented as signals, that's because xRouteSignal also has to map timers to the receiver process

Hint:

Each signal and timer is represented by a system wide unique integer number.

Exported from mk_main.c

xmk_InitSDL

Parameters:

In/Out: -no-
Return: -no-

This C function is called by the user before calling the C function xmk_RunSDL() and implements the initialization of the whole SDL system, namely Timer, Queue, Processes.

xmk_RunSDL

Parameters:

In/Out: -no-
Return: -no-

This function operates endlessly unless XMK_USE_SDL_SYSTEM_STOP is activated. Then the function is returned if the signal queue is empty or no process is alive. Before processing signals, SDL time-outs are checked and the C function xInEnv is called.

xmk_MicroTesterInit

Parameters:

In/Out: -no-
Return: -no-

This function is used to tell the target configuration to the SDL Target Tester. First the communication interface is initialized, then the startup message is sent to the host. After that the target waits for a "go forever" message from the host.

xmk_MicroTesterDeinit

Parameters:

In/Out: -no-
Return: -no-

This function is responsible for closing the communication interface to the host after the system has ended.

Exported from mk_sche.c

xmk_StartProcesses

Parameters:

In/Out: -no-
Return: -no-

This function implements the start-up phase of the SDL system. All static process-instances are created. This means executing the start-transition of all process-instances to be created. For each created process-instance, the first state is set. If configured right, the values SDL_SELF, SDL_PARENT and SDL_OFFSPRING are correctly initialized (only necessary if no semantic check was performed, i.e. if the Analyzer is not used).

xmk_ProcessSignal

Parameters:

In/Out: -no-
Return: -no-

This function processes an SDL signal and remains in an internal loop, until a signal has been processed or until no signal remains in any input-port in the SDL system.

xmk_CreateProcess

Parameters:

In/Out: ProcessID       - ID of the process type
Return: xmk_T_INSTANCE  - created Instance number ID

This function tries to create an instance of the given process-type. This can fail, either if the create signal cannot be allocated (no more memory) or if there is no free process instance of that type. E.g. if there is no instance in the DORMANT state.

The return value contains the process instance number ID, if one more process instance could be allocated. The return value is set to xNULLINST if the creation failed for some reason.

The process instance number is not the same as the process ID. The process ID is calculated from the process ID type plus the process ID instance number.

The generated C code does not use the return value, because the SDL offspring and the parent pid value are stored in the pid tables of the process instance.

xmk_IsAnyProcessAlive

Parameters:

In/Out: -no-
Return: xmk_T_BOOL

This function checks for any active instance of a process type by searching for instances not in the state XDORMANT.

The function returns with XMK_TRUE, if there is an active instance. It returns with XMK_FALSE if there is no instance active within the system.

xmk_IfExist

Parameters:

In/Out: xPID - Process ID of the process to be 
checked
Return: xmk_T_BOOL

This function checks if the given PID is valid or not. The return value is XMK_TRUE if the given PID is valid. If an instance with this PID does not exist, it returns with XMK_FALSE.

xmk_CheckNullPointerValue

Parameters:

In/Out: void*
Return: -no-

This function checks whether there is a pointer value in the SDL system that is used but has no value. The ErrorHandler is called with the right error message then. The error must be caught in the user's ErrorHandler in order to implement the right reaction on this fatal situation.

xmk_InitPreemptionVars

Parameters:

In/Out: -no-
Return: -no-

The variables used in preemption are initialized.

xmk_DisablePreemption

Parameters:

In/Out: -no-
Return: -no-

The variable which stores the preemption status is incremented. A value greater than zero means it is not allowed to perform a context-switch at the moment.

xmk_EnablePreemption

Parameters:

In/Out: -no-
Return: -no-

The variable which stores the preemption status is decremented if preemption was disabled. If the variable's value is zero after it is decremented, the function xmk_CheckIfSchedule() is called.

xmk_FetchHighestPrioLevel

Parameters:

In/Out: -no-
Return: xmk_T_PRIOLEVEL

This function searches for signals in the priority queue levels. This is done with decreasing priority in order to find the highest priority level at which signals exist. The return value is the highest priority level that contains a signal to process.

xmk_CheckIfSchedule

Parameters:

In/Out: -no-
Return: -no-

It is checked whether a context switch is admissible. If this is the case the current priority-level is compared with the highest priority-level where a signal exists. Supposing the highest level is higher than the current, a context-switch is performed using xmk_SwitchPrioLevel(). This is repeated until the current priority-level is the highest level.

xmk_SwitchPrioLevel

Parameters:

In/Out: xmk_T_PRIOLEVEL NewPrioLevel
Return: -no-

The global variables for the current priority-level are stored. Afterwards, the function xmk_ProcessSignal() is called in order to deal with the signals on the higher priority level. After returning from this function call the variables for the current priority-level are restored.

With the NewPrioLevel the next prio-level to deal with is specified.

xmk_KillProcess

Parameters:

In/Out: xPID Process ID
Return: xmk_T_BOOL

This function sets a process instance into the state XDORMANT, removes all signals directed to it from the queue and resets the local instance data. The return values are XMK_TRUE if the call was successfully and XMK_FALSE if the process was non-existent, currently running or already in the XDORMANT state.

Exported from mk_outp.c

xmk_SendSimple

Parameters:

In/Out: 
  #ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
    xmk_T_SIGNAL  sig
    xPID          Receiver
  #else
   xmk_T_SIGNAL   sig
  #endif

Return: -no-

This is a simple SDL output function which needs a maximum of only 2 Parameters. Most SDL systems consist of a lot of "normal" Signals without any parameters and no priority. It makes sense to use this simple function whenever possible to spare program code. The signal is put into the linked list of signals by using a default priority.

With the first parameter sig, the signal ID of the signal that is to be sent is specified. With the (optional) second parameter, the receiver process ID is specified. If XMK_USE_RECEIVER_PID_IN_SIGNAL is not defined, the user must implement the C function xRouteSignal() which is responsible to derive the receiver from the signal ID in that case. Using xRouteSignal() is recommended only if the last few bytes must be spared for transferring of signals.

xmk_Send

Parameters:

In/Out: 
        xmk_T_SIGNAL sig
 
        #ifdef XMK_USE_SIGNAL_PRIORITIES
          xmk_T_PRIO prio
        #endif
 
        #ifdef XMK_USED_SIGNAL_WITH_PARAMS
          xmk_T_MESS_LENGTH data_len
          void xmk_RAM_ptr  p_data
        #endif

        #ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
          xPID Receiver
        #endif

Return: -no-

This is, compared to the xmk_SendSimple function, a complete SDL output function which needs all possible signal parameters.

With the parameter sig, the signal ID is to be specified.

With the prio parameter, the signal's priority is to be specified (if conditionally compiled).

With the data_len, the number of bytes as the signal's parameters is to be specified. The number of bytes is evaluated by using a
sizeof (C struct) construct. If the signal carries no parameters, this value must be set to 0 (if conditionally compiled).

With the p_data parameter, a pointer to the memory area containing the parameter bytes of the signal is given. The memory area is not treated as dynamically allocated within this function. Because the function copies the parameter bytes, the caller may use any temporary memory (for example memory allocated from the C stack by declaring a C variable). This parameter should be set to NULL if no parameter bytes are to be transferred (if conditionally compiled).

With the last parameter Receiver, the PID of the receiving process is to be specified (if conditionally compiled).

If the XMK_USE_SIGNAL_PRIORITIES is not defined, the signal priorities which are specified with #PRIO in the diagrams is just ignored. The use of signal priorities is not recommended because the violation of SDL. A few bytes can be spared if signal priority is not used.

The XMK_USED_SIGNAL_WITH_PARAMS is automatically generated into the sdl_cfg.h file, from the Cmicro SDL to C Compiler. For tiny systems, if there are no SDL signals with parameters specified, this is undefined. It will reduce the amount of information which is to be transferred for each signal with a few bytes.

If XMK_USE_RECEIVER_PID_IN_SIGNAL is not defined, the user must implement the C function xRouteSignal() which is responsible to derive the receiver from the signal ID in that case. Using xRouteSignal() is recommended only if the last few bytes must be spared for transferring of signals.

XMK_SEND_ENV

Parameters:

In/Out: xPID Env_ID

        xmk_T_SIGNAL sig
 
        #ifdef XMK_USE_SIGNAL_PRIORITIES
          xmk_T_PRIO prio
        #endif
 
        #ifdef XMK_USED_SIGNAL_WITH_PARAMS
          xmk_T_MESS_LENGTH data_len,
          void xmk_RAM_ptr  p_data
        #endif

        #ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
          xPID Receiver
        #endif

Return: -no-

This function is to be called when a signal is to be sent into the SDL system, e.g. within the users xOutEnv() function. It must be called with one more parameter than the xmk_Send() function, which is the first parameter Env_ID.

The macro internally uses some variables which are to be declared before the macro can be used. For example in the xOutEnv function the XMK_SEND_TMP_VARS macro must be introduced for declaring these variables.

The function is implemented as a macro in C.

xmk_Determine_Receiver

Parameters:

In/Out: xmk_T_PROCESS proc_type - process type ID
Return: xPID                    - process PID

This function is used in the context of SDL output in generated C code. The function determines if any instance with the given process type-ID is available to receive the signal. If no instance can be found, xNULLPID is returned.

Exported from mk_queu.c

xmk_InitQueue

Parameters:

In/Out: -no-
Return: -no-

This function initializes the signal queue. It must be called before any other Cmicro Kernel function, e.g. before xmk_InitSDL(). All relevant pointers are initialized. All signal-elements are put into the free-list. The SAVE-state of all signals is set to false.

xmk_FirstSignal

Parameters:

In/Out: -no-
Return: xmk_T_MESSAGE*

The first signal in the current queue which is the one with the highest priority, is copied to the pointer of the currently treated signal and returned to the caller.

The function returns a pointer to the first signal in the queue or NULL, if there are no signals in the queue.

xmk_NextSignal

Parameters:

In/Out: -no-
Return: xmk_T_MESSAGE*

The signal following the current signal is copied to the current signal. If there are no more signals, NULL is returned.

xmk_InsertSignal

Parameters:

In/Out: xmk_T_MESSAGE xmk_RAM_ptr p_Message
Return: -no-

This function puts a signal into the queue. The position depends on only the signal priority, if specified.

With the parameter p_Message a pointer to the signal which is to be inserted is given.

xmk_RemoveCurrentSignal

Parameters:

In/Out: -no-
Return: -no-

The signal which was currently processed is removed from the queue and inserted into the list of free signals.

xmk_RemoveSignalBySignalID

Parameters:

In/Out: xmk_T_SIGNAL SignalId 
Return: -no-

This function is not used if timers with parameters are in the system (XMK_USED_TIMER_WITH_PARAMS macro is defined).

Signals of a given signal-code sent to the current process are removed from the queue and inserted in the list of free signals. The signal currently being processed must not be removed, as it is necessary for the current actions. It is only removed after processing is complete.

With the parameter SignalID, the signal ID of the signals which are to be removed for the currently active process instance is specified.

xmk_RemoveTimerWithParameter

Parameters:

In/Out: xmk_T_SIGNAL SignalId
In    : SDL_Integer  TimerParValue
Return: -no-

This function is only compiled if timers with parameters are in the system (XMK_USED_TIMER_WITH_PARAMS macro is defined).

This function has the same purpose as the above xmk_RemoveSignalBySignalID but, in addition, must look to the timer's parameter.

xmk_IsTimerInQueue

Parameters:

In/Out: xmk_T_SIGNAL TimerID
#ifdef XMK_USED_TIMER_WITH_PARAMS
In    : SDL_Integer  TimerParValue
#endif
Return: -no-

This function checks if the given timer is in the signal queue. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is checked also.

xmk_RemoveSignalsByProcessID

Parameters:

In/Out: xPID ProcessID - PID of Process
Return: XMK_TRUE   - Signal removed
	 XMK_FALSE  - no Signal removed

All signals addressed to a specific process are removed by calling this Function.

With the parameter ProcessId, the PID of the process for which all the signals are to be removed from the queue is specified.

xmk_AllocSignal

Parameters:

In/Out: -no-
Return: xmk_T_MESSAGE xmk_RAM_ptr

According to the principle chosen by the user (the user has to choose between XMK_USE_STATIC_QUEUE_ONLY and XMK_USE_STATIC_AND_DYNAMIC_QUEUE), and if possible, an initialized signal instance is returned. The signal instance is then either taken from the static memory pool or from the dynamic memory pool.

Allocation from the dynamic memory pool takes place by calling the xAlloc C function.

If XMK_USE_STATIC_QUEUE_ONLY is set, the ErrorHandler is called with the error "ERR_N_NO_FREE_SIGNAL". This indicates that no more memory is available to create one more signal instance, and the user may react appropriately in the ErrorHandler C function.

Otherwise, if XMK_USE_STATIC_AND_DYNAMIC_QUEUE is set, and if it is impossible to allocate one more instance from the predefined static memory pool, the ErrorHandler is called with the error "ERR_N_NO_FREE_SIGNAL". This indicates that dynamic memory allocation is started now, and the user may react appropriately in the ErrorHandler C function (for example, he might want to print out a warning message). If it is impossible to allocate one more signal from the dynamic memory pool, the ErrorHandler is called with the error "ERR_N_NO_FREE_SIGNAL_DYN". The user may then also decide what to do in the ErrorHandler C function.

A pointer to the signal that was allocated is returned usually, or NULL, if there is no space left to allocate one more signal.

xmk_FreeSignal

Parameters:

In/Out: xmk_T_MESSAGE xmk_RAM_ptr p_Message
Return: -no-

The given signal is de-allocated again.

If the signal was allocated from the static memory pool, it is returned to that pool by initializing it and inserting it into the free list at the first position.

Otherwise, if the signal was allocated from the dynamic memory pool, it will be returned to that pool (by calling the xFree C function).

The parameter p_Message must point to the signal that is to be initialized.

xmk_TestAndSetSaveState

Parameters:

In/Out: xmk_T_STATE State
Return: xmk_T_BOOL

This function checks whether a signal's SAVE-state is set or not. In testing, the SAVE-state is set to TRUE or FALSE.

With the parameter State, the value of the process' current state is to be specified.

The function returns with XMK_TRUE, if the given state equals the signal's SAVE-state, but returns with XMK_FALSE if the given state differs from the signal's save state.

xmk_QueueEmpty

Parameters:

In/Out: -no-
Return: -no-

This function tests whether there is at least one signal remaining in the queue(s) or not.

The function returns XMK_TRUE, if there are no signals in the queue, but returns XMK_FALSE if there is at least one signal in the queue. It does not matter if the signal is a saved signal or not.

When the Cmicro Kernel is configured for preemption, all the queues of the different priority levels are checked.

Exported from mk_tim1.c

xmk_InitTimer

Parameters:

In/Out: -no-
Return: -no-

All initialization of timers is performed within this function, which is called during SDL system start. It initializes some pointers and the free list of timers.

xmk_TimerSet

Parameters:

In/Out: xmk_T_TIME   time
        xmk_T_SIGNAL sid
#ifdef XMK_USED_TIMER_WITH_PARAMS
In    : SDL_Integer  TimerParValue
#endif
Return: -no-

This function activates an instance of a timer with the given "signal ID" value and the given time. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is used also (the value is set to 0 outside this function call if it is not a timer with parameter).

Working principles:

The first parameter time specifies the time at which the timer should expire. The call to SDL now is performed in generated C code.

The second parameter sid specifies the ID of the timer that is to be started.

If a timer instance of this type is already running, this will be deactivated. If no free timer is available, the ErrorHandler is called. After all these checks a timer instance is created for the currently running process.

xmk_TimerReset

Parameters:

In/Out: xmk_T_SIGNAL sid
#ifdef XMK_USED_TIMER_WITH_PARAMS
In    : SDL_Integer  TimerParValue
#endif
Return: -no-

This function resets the timer with the given "signal ID" value, if it is active and set by the currently running process. If an active timer instance is found, then the timer is inserted into the free-list. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is used also (the value is set to 0 outside this function call if it is not a timer with parameter).

The parameter sid specifies the ID of the timer which is to be reset.

xmk_TimerActive

Parameters:

In/Out: xmk_T_SIGNAL sid
#ifdef XMK_USED_TIMER_WITH_PARAMS
In    : SDL_Integer  TimerParValue
#endif
Return: xmk_T_BOOL

This function checks if a timer with the given 'Signal-ID' value is active in the current running process. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is used also (the value is set to 0 outside this function call if it is not a timer with parameter).

The parameter sid specifies the ID of the timer which is to be checked if it is active.

The function returns with XMK_TRUE if the timer is active in the process that is currently running, it returns XMK_FALSE otherwise.

xmk_ChkTimer

Parameters:

In/Out: -no-
Return: -no-

The main intention of this function is to check, if any of the timers which are in the list of active timers is expired. There is a list of active timers in which the active timers are stored in the order of their expiry.

This means that the timer that expires first stands in front of the list.

If a timer was recognized as expired, a timer signal is sent to the owning process instance, the timer is removed from the list of active timers and restored into the list of free timers.

If there is no timer that can expire, the function returns immediately.

Another task for this function is to check if the global system time is overrun. If this case occurs, the xmk_ChkTimer() function will readjust the global system time (by calling xmk_SetTime() from mk_cpu.c) and will readjust all the timers in the active list.

xmk_ResetAllTimer

Parameters:

In/Out: xPID pid
Return: -no-

All active timers of the given process instance are reset. This will occur if a process instance stops.

With the pid parameter the process instance is addressed.

Exported from mk_stim.c

xmk_InitSystime

Parameters:

In/Out: -no-
Return: -no-

This function initializes the hardware timer and is to be filled out by the user.

xmk_DeinitSystime

Parameters:

In/Out: -no-
Return: -no-

This function de-initializes the hardware Timer and is to be filled out by the user.

xmk_SetTime

Parameters:

In/Out: xmk_T_TIME time
Return: -no-

This function sets the system time to the given value time and is to be filled out by the user.

xmk_NOW

Parameters:

In/Out: -no-
Return: xmk_T_TIME

This function is used by

The current SDL system time is returned.

The function is to be filled out by the user.

Exported from ml_mem.c

xmk_MemInit

Parameters:

In/Out:	 char* _mem_begin
       	 char* _mem_end
Return:	 -no-

This function is to be called by the user, before dynamic memory management can be used. The user has to specify the beginning and the end of the area to be used for dynamic memory management. The function should be called before the first call to xAlloc(), e.g. as the first statement in the user's main() function.

xmk_Malloc

Parameters:

In/Out:	 unsigned long rsize
Return:	 void *

This function allocates one block of memory from the dynamic memory pool. It uses a first fit policy.

xmk_Calloc

Parameters:

In/Out: unsigned long RequestedSize
Return: void*

This function allocates one block of memory from the dynamic memory pool. It is the same as xmk_Malloc() but sets the allocated block to zero.

xmk_Free

Parameters:

In/Out: void *mem
Return: void

This function is the counterpart of xmk_Malloc(). A memory block is de-allocated again.

xmk_Memshrink

Parameters:

In/Out:	 void  *pMemBlock
	 unsigned long NewSize
Return:	 -no-

This function is an extension of the compared with the standard of dynamic memory management supported by usual C compilers. It allows the user to shrink down a memory area which was previously requested with xmk_Malloc().

memset

Parameters:

In/Out:	 char *p
	 char val
	 int length-
Return:	 -no-

This function is a template for the memset() implementation.

Caution!

Take care when the preemption policy is utilized.

memcpy

Parameters:

In/Out:	 char *dest
	 char *source
	 int length
Return: -no-

This function is a template for the memcpy() implementation.

Caution!

Take care when the preemption policy is utilized.

Exported from ml_mon.c

xmk_GetErrorClass

Parameters:

In/Out:	 xmk_T_ERR_NUM EightBitNumber
Return:	 int

This function returns the error class assigned to the given error number given by the caller. The error class can be one of XMK_FATAL_CLASS or XMK_WARNING_CLASS. This can be used to classify the predefined error and warning messages and to react properly if such a message occurs.

xmk_MonError

Parameters:

In/Out:	 FILE *fp
	 int nr
Return:	 -no-

This function is used to evaluate an ASCII error text from an errornumber given by the caller. The first parameter fp must contain a pointer to a valid (i.e. file is opened) file descriptor, for example it could be stdin, stdout, or a file which was opened with fopen. The second parameter nr contains one of the possible error numbers defined in ml_err.h.

xmk_MonPID

Parameters:

In/Out:	 char *ostring
	 xPID pid
Return:	 -no-

Used for test purposes, free use.

xmk_MonHexSingle

Parameters:

In/Out:	 char *p_text
	 unsigned char *p_adress
	 int length
Return:	 -no-

Used for test purposes, free use.

xmk_MonHex

Parameters:

In/Out:	 char *p_text
	 unsigned char *p_adress
	 int length
Return:	 -no-

Used for test purposes, free use.

xmk_MonHexAsc

Parameters:

In/Out: -no-
Return: -no-

Function for test purposes, free use.

xmk_MonConfig

Parameters:

In/Out: -no-
Return: -no-

Function for test purposes, free use.

Exported from mk_cpu.c

xmk_PutString

Parameters:

In/Out:	 char * Param1
Return:	 -no-

A template for how to print out a character string. The character string must be terminated with "\0".

The function must return immediately, i.e. may not be blocking on the output device. If the user does not care about this restriction, the correct function of other program parts cannot be guaranteed.

xmk_GetChar

Parameters:

In/Out: -no-
Return: int

This function checks if the user has pressed a key on the keyboard (unblocked). The function must return immediately, i.e. may not be blocking on the input device. If the user does not care about this restriction, the correct function of other program parts cannot be guaranteed.

xmk_printf

Parameters:

In/Out:	 char* format
	 format string
	 other parameters
Return:	 -no-

This function is called from any place in the Cmicro Library, Cmicro Kernel or generated C code, if the printf functionality is compiled with at least one of the XMK_ADD_PRINTF* defines.

The function must return immediately, i.e. may not be blocking on the output device. If the user does not care about this restriction, the correct function of other program parts cannot be guaranteed.

The function can be used for ANSI C compilers only, because optional argument lists are used like in the printf function of the standard C library.

The return value has no meaning and is introduced just for compatibility with printf.

xAlloc

Parameters:

In/Out:	 xptrint  Size
Return:	 void *

This function is called from any place in the Cmicro Library, Cmicro Kernel, SDL Target Tester or generated C code, if memory is to be allocated dynamically. The user may choose between the dynamic memory allocation functions from the C compiler or operating system or the dynamic memory allocation functions from Cmicro.

The return value points to the allocated buffer or is NULL if the operation was unsuccessful.

xFree

Parameters:

In/Out: void **
Return: -no-

This is the counterpart of xAlloc(). The function is called when a memory block that has been allocated with xAlloc() can be de-allocated again. The parameter is the address of the pointer to the allocated buffer.

Example 613 Using the xFree function

unsigned char *ptr;
ptr = xAlloc(100);
xFree (&ptr);      /* NOTE: Not xFree(ptr); */


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