IBM
Contents Index Previous Next



Functions of the Expanded Cmicro Kernel


The expanded Cmicro Kernel offers additional functionality that is usually not necessary for target applications. Extended functionality is for example required by the SDL Target Tester, but may also be required from the user if it comes to target integration.

It is not absolutely necessary to have knowledge of these functions but knowledge of the functions proves useful when it comes to debugging and testing an application.

Functions for Internal Queue Handling

Exported from mk_queu.c

xmk_SaveSignalsOnly

Parameters:

In/Out: -no-
Return: xmk_T_BOOL

This function tests whether there only are SAVE signals contained in the queue. This can be used in integrations with operating systems.

The function returns XMK_TRUE, if there are SAVE signals only in the queue, otherwise it returns XMK_FALSE.

Exported from mk_tim1.c

xmk_NextTimerExpiry

Parameters:

In/Out: xmk_T_TIME * RemainingTime
Return: xmk_T_BOOL

This function looks for the remaining time of the timer that expires next. This is useful for operating system integration. If there is no active timer, the function returns XMK_FALSE and the returned parameter RemainingTime is set to 0.

If there is an active timer, the function returns with XMK_TRUE and the returned parameter RemainingTime contains the time at which the timer expires next. XMK_TRUE means there is a timer active and the remaining time is returned in the parameter. XMK_FALSE means that there is no timer active and returned parameter is set to 0.

Functions to get System Information

Exported from mk_sche.c

xmk_GetProcessState

Parameters:

In/Out	 xPID pid
Return:	 xmk_T_STATE

The function evaluates the current SDL state of the SDL process pid with the given process PID and returns it to the caller. During the SDL system start-up, one possible return value might be XSTARTUP. This means that a process will be started during system start-up. During normal execution and system start-up, the return value XDORMANT may be returned. This means that an SDL process instance is either stopped or has never been created dynamically (created).

xmk_SetProcessState

Parameters:

In/Out:	 xPID pid,
	 xmk_T_STATE state
Return:	 xmk_OPT_INT

The function sets the SDL-state of the process pid that is addressed with the first parameter to the given value state within the second parameter. Note, that the value is not checked, because Cmicro does not store any information about this in the generated transition tables.

xmk_GetProcessInstanceData

Parameters:

In/Out:	 xPID pid
Return:	 void *

The function returns the address of the process instance data of the given process-PID, or XNOTEXISTENT, if the pid is not existent.

xmk_QueryQueue

Parameters:

In/Out:	 xmk_T_CMD_QUERY_QUEUE_CNF * qinfo
Return: -no-

This function evaluates the current SDL-Queue-State and returns some information to the caller:

Exported from mk_tim1.c

xmk_QueryTimer

Parameters:

In/Out:	 xmk_T_CMD_QUERY_TIMER_CNF *tinfo
Return:	 -no-

This function evaluates the current state of the SDL-Timer handling and returns it to the caller. The following information is contained in the C structure that is returned:

xmk_FirstTimer

Parameters:

In/Out:	 -no-
Return:	 xmk_T_TIMER *

The function returns a pointer to the first active timer. If there is no active timer in the queue, NULL will be returned.

xmk_NextTimer

Parameters:

In/Out:	 -no-
Return:	 xmk_T_TIMER *

The function returns a pointer to the next active timer in the list of active timers. If there is no or one active timer in the queue, NULL will be returned.

Exported from ml_mem.c

xmk_GetOccupiedMem

Parameters:

In/Out:	 -no-
Return:	 size_t

This function returns the currently occupied amount of memory from the pool. The pool size is defined with XMK_MAX_MALLOC_SIZE.

xmk_GetFreeMem

Parameters:

In/Out:	 -no-
Return:	 size_t

This function returns the amount of available memory from the pool. This means that it returns the difference between the size of the pool (XMK_MAX_MALLOC_SIZE) and the currently occupied memory.

xmk_CleanPool

Parameters:

In/Out:	 -no-
Return:	 int

This function reinitialize the memory pool to free memory leaks. The memory pool can only be cleaned if there are no allocated blocks left.

Alternative Function for sending to the Environment

Exported from mk_outp.c

xmk_EnvSend

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 function is an alternative to the standard function XMK_SEND_ENV for putting signals into the SDL system in external C code. The function is useful when signals are to be sent in interrupt service routines directly. If interrupt service routine is used and can result in signal sending the user need to manually define flag XMK_USE_INTERRUPT_SERVICE_ROUTINE to enable more critical paths in kernel. The function is shorter than XMK_SEND_ENV, but performs not so many error checks. It is especially not checked, if the receiver process ID exist. Usually there is also no call to functions which produce trace output because this would lead to problems in interrupt service routines. But for some error situations like either

the ErrorHandler() C function, which is to be implemented by the user, is called.

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 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.


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