INIT_SemaClassProp

Initialize the Semaphore object class properties.

Synopsis

KSRC INIT_SemaClassProp

(const KCLASSPROP *pclassprop)

Input

Description

During the RTXC Kernel initialization procedure, you must define the kernel objects needed by the RTXC Kernel to perform the application. The INIT_SemaClassProp kernel service allocates space for the Semaphore object class in system RAM. The amount of RAM to allocate, and all other properties of the class, are specified in the structure pointed to by pclassprop.

Example 2-22 on page 62 shows the organization of the ^KCLASSPROP structure.

The attributes element of the Semaphore ^KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 3-1 on page 89.

Output

This service returns a ^KSRC value as follows:

` RC_GOOD if the service completes successfully.

` RC_NO_RAM if the initialization fails because there is insufficient system RAM available.

Example

During system initialization, the startup code must initialize the Semaphore object class before using any kernel service for that class.

The system generation process produces a ^KCLASSPROP structure containing the information about the semaphore object class necessary for its initialization. Example 3-11 references that structure externally to the code module.

pclassprop A pointer to a Semaphore object class properties structure.

INIT_SemaClassProp

Example 3-11. Initialize Semaphore Object Class

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

static char buf[128];

/* created by system generation*/

extern const SYSPROP sysprop;

extern const KCLASSPROP semaclassprop;

KSRC userinit (void) {

KSRC ksrc;

/* initialize the kernel workspace, allocate RAM for required classes, etc. */

if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) {

putline ("Kernel initialization failure\n");

return (ksrc); /* end initialization process */

}

/* kernel is initialized */

/* Need to initialize the necessary kernel object classes */

/* Initialize the Semaphore kernel object class */

if ((ksrc = INIT_SemaClassProp (&semaclassprop)) != RC_GOOD) {

putline ("No RAM for Semaphore init");

return (ksrc); /* end initialization process */

}

... Continue with system initialization }

Synopsis

KSRC KS_LookupSema (const char *pname, SEMA *psema)

Inputs

Description

^TheKS_LookupSema kernel service obtains the handle of the static or dynamic semaphore whose name matches the null-terminated string pointed to by pname. The lookup process terminates when it finds a match between the specified string and a static or dynamic semaphore name or when it finds no match. The service stores the matching semaphore’s handle in the variable pointed to by psema.

The service searches dynamic names, if any, first.

Note: To use this service on static semaphores, you must enable the Static Names attribute of the Semaphore class during system generation.

This service has no effect on the registration of the specified semaphore by the Current Task.

The time required to perform this operation varies with the number of semaphore names in use.

Output

This service returns a ^KSRC value as follows:

` RC_GOOD if the search succeeds. The service stores the matching semaphore’s handle in the variable pointed to by psema.

` RC_OBJECT_NOT_FOUND if the service finds no matching semaphore name.

pname A pointer to a null-terminated name string.

psema A pointer to a SEMA variable for storing the semaphore handle, if found.

KS_LookupSema

Example

In Example 3-12, the Current Task needs to use the ^Chnl2Sema dynamic semaphore. If the semaphore is found, it can then be used by the Current Task.

Example 3-12. Look Up Semaphore by Name

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

SEMA dynsema;

/* lookup the semaphore name to get its handle */

if (KS_LookupSema ("Chnl2Sema ", &dynsema) != RC_GOOD) {

... Semaphore name not found. Deal with it }

else /* got the handle for Chnl2Sema */

{

... Do something with the semaphore now }

Synopsis

KSRC KS_OpenSema (const char *pname, SEMA *psema)

Inputs

Description

^TheKS_OpenSema kernel services allocates, names, and obtains the handle of a dynamic semaphore. The service stores the handle of the new dynamic semaphore in the variable pointed to by psema. If there is no existing semaphore, static or dynamic, with a name matching the null-terminated string pointed to by pname, the service allocates a dynamic semaphore and applies the name referenced by pname to the new semaphore. The kernel stores only the address of the name internally, which means that the same array cannot be used to build multiple dynamic semaphore names.

If the service finds an existing semaphore with a matching name, it does not open a new semaphore and returns a value indicating an unsuccessful operation.

If pname is a null pointer ((char *)0), the service does not assign a name to the dynamic semaphore. However, if pname points to a null string, the name is legal as long as no other semaphore is already using a null string as its name.

Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.

If the pointer to the semaphore name is not null, the time required to perform this operation varies with the number of semaphore names in use.

If the pointer to the semaphore name is null, no search of semaphore names takes place and the time to perform the

pname A pointer to a null-terminated name string.

psema A pointer to a SEMA variable in which to store the allocated semaphore’s handle.

KS_OpenSema

service is fixed. You can define the semaphore name at a later time with a call to the KS_DefSemaName service.

Output

This service returns a ^KSRC value as follows:

` RC_GOOD if the service completes successfully. The service stores the handle of the new dynamic semaphore in the variable pointed to by psema.

` RC_OBJECT_ALREADY_EXISTS if the name search finds another semaphore whose name matches the specified string.

` RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic semaphores are in use.

Example

Example 3-13 on page 101 allocates a dynamic semaphore and names it MuxChnl2Sema. If the name is in use, the example outputs a message on the console using the ^putline routine.

Example 3-13. Allocate Dynamic Semaphore

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

KSRC ksrc;

SEMA dynsema;

if ((ksrc = KS_OpenSema ("MuxChnl2Sema", &dynsema)) != RC_GOOD) {

if (ksrc == RC_OBJECT_ALREADY_EXISTS)

putline ("MuxChnl2Sema semaphore name in use");

else if (ksrc == RC_NO_OBJECT_AVAILABLE)

putline ("No dynamic Semaphores available");

else

putline ("Semaphore class is not defined");

} else {

... semaphore was opened correctly. Okay to use it now }

XX_SignalSema

Synopsis

void XX_SignalSema (SEMA sema)

Input

Description

If the semaphore specified in sema has one or more waiters and a count value of 0, the count value of sema remains 0 and the waiters are processed according to sema’s signal type.

For each semaphore signaled, if its Signal Type attribute is in the default state, the service removes the SEMAPHORE_WAIT state of the first waiting task only. If Signal Type is set to

ATTR_MULTIPLE_WAITERS, the service removes the

SEMAPHORE_WAIT state for all tasks in the waiting list for the event.

If a waiting task becomes runnable as a result of the removal of its SEMAPHORE_WAIT state, the service places the task in the Ready List at a position dependent on its current priority.

If the semaphore has no waiters or has a non-zero count value, the XX_SignalSema kernel service simply increments the count value of the semaphore specified in sema and returns control to the calling task. The count value for sema never exceeds the maximum value for the ^SEMACOUNT type.

Output

This service does not return a value.

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.

sema The handle of the semaphore to signal.

XX_SignalSema

Example

Example 3-14 looks at the current size of the ^CHARQ static queue and signals the ^XOFF semaphore if the queue contains more than 20 entries. It signals the ^XON semaphore if the current size of the queue is less than four entries.

Example 3-14. Signal Semaphore from Zone 3

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

#include "kqueue.h" /* defines CHARQ */

#include "ksema.h" /* defines XOFF and XON */

static QUEUEPROP qprop;

/* get CHARQ properties */

KS_GetQueueProp (CHARQ, &qprop);

if (qprop.current_size > 20) KS_SignalSema (XOFF);

if (qprop.current_size < 4) KS_SignalSema (XON);

... continue

Synopsis

void XX_SignalSemaM (const SEMA *psemalist)

Input

Description

^TheXX_SignalSemaM kernel service performs the same service as the XX_SignalSema service, except that it uses a list of

semaphores associated with multiple events. The psemalist argument contains the address of the null-terminated semaphore list. For each semaphore handle in the semaphore list,

XX_SignalSemaM signals the associated semaphore.

For each semaphore signaled, if its Signal Type attribute is in the default state, the service removes the SEMAPHORE_WAIT state of the first waiting task only. If Signal Type is set to

ATTR_MULTIPLE_WAITERS, the service removes the

SEMAPHORE_WAIT state for all tasks in the waiting list for the event.

If a waiting task becomes runnable as a result of the removal of its SEMAPHORE_WAIT state, the service places the task in the Ready List at a position dependent on its current priority.

The count value for each semaphore referenced by psemalist never exceeds the maximum value for the ^SEMACOUNT type.

Output

This service does not return a value.

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.

psemalist A pointer to a null-terminated semaphore list.

XX_SignalSemaM

Example

In Example 3-15, the Current Task signals the ^SWITCH1, ^SWITCH2, and ^CHNLDONE static semaphores to indicate completion of the use of a multiplexor channel.

Example 3-15. Signal List of Semaphores from Zone 3

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

#include "ksema.h" /*defines SWITCH1, SWITCH2, & CHNLDONE */

const SEMA semalist[] = {

SWITCH1, SWITCH2, CHNLDONE,

(SEMA)0 /* null terminator */

}

... use multiplexor channel

KS_SignalSemaM (semalist);/* signal multiple semaphores */

... continue processing

Synopsis

KSRC KS_TestSema (SEMA sema)

Input

Description

^TheKS_TestSema kernel service polls the status of the semaphore specified in sema and returns a value indicating whether it detected a signal on the specified semaphore. If the semaphore is in a ^DONE state, KS_TestSema decrements the count by one. It does not change the semaphore count if the count is less than or equal to zero.

Output

This service returns a ^KSRC value as follows:

` RC_GOOD if the service detects a signal (semaphore count was >

0).

` RC_NO_SIGNAL if the service detects a semaphore count less than or equal to zero (0).

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.

Example

In Example 3-16 on page 107, the Current Task needs to poll the KEYPAD semaphore to determine if it has received a signal. If not, the task continues performing some other processing. If a signal is detected, some special event processing is required before proceeding.

sema The handle of the semaphore to test.

KS_TestSema

Example 3-16. Test Semaphore

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

#include "ksema.h" /* defines KEYPAD */

/* test for KEYPAD hit event */

for (;;) {

while (KS_TestSema (KEYPAD) == RC_NO_SIGNAL) {

... do some other operations until key is pressed }

... signal occurred, read the keypad and process the input character (s)

}

Synopsis

KSRC KS_TestSemaT (SEMA sema, COUNTER counter, TICKS ticks)

Inputs

Description

^TheKS_TestSemaT kernel service is similar to the

KS_TestSemaW kernel service. It tests the semaphore specified in sema for having received a signal and either blocks the Current Task or immediately returns to it depending on the value of the

semaphore count.

While the semaphore count remains less than or equal to zero (0), the service blocks the Current Task and starts an internal alarm for the interval specified in ticks on the specified counter. The task continues to be blocked until one of two events occurs:

` A signal to the semaphore specified by sema occurs when sema’s count value is equal to zero (0), or

` The specified number of ticks elapses.

If the semaphore count is greater than zero, it contains a value equal to the number of unprocessed signals the semaphore has received.

In such a case, the test of the semaphore causes the semaphore’s count to decrement by one and the service returns to the calling task immediately.

Output

This service returns a ^KSRC value as follows:

` RC_GOOD if a semaphore signal has occurred.

sema The handle of the semaphore to test.

counter The counter associated with the tick interval defined by ticks. ticks The number of ticks on the specified counter to wait for the

signal.

KS_TestSemaT

` RC_TICKOUT if the specified number of ticks elapses before the semaphore receives a signal.

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.

` FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

` FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.

Example

In Example 3-17, the Current Task needs to wait for a keypad character to be pressed, but it can’t wait for more than 100 msec using static counter ^MSCOUNTER because it has other jobs to do. It uses the KS_TestSemaT kernel service to perform a tick-limited wait on the ^KEYPAD event.

Example 3-17. Test Semaphore—Wait Number of Ticks for Signal

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

#include "ksema.h" /* defines KEYPAD */

#include "kcounter.h" /* defines MSCOUNTER */

#include "kproject.h" /* defines CLKTICK */

/* wait 100 msec for KEYPAD to be hit */

if (KS_TestSemaT (KEYPAD, MSCOUNTER, (TICKS)100/CLKTICK) == RC_GOOD)

... no keypad event and timeout happened }

KS_TestSemaM

Test a list of semaphores.

Synopsis

SEMA KS_TestSemaM (const SEMA *psemalist)

Input

Description

^TheKS_TestSemaM kernel service performs the same service as the KS_TestSema service, except that it uses a list of semaphores.

The psemalist argument contains the address of a null-terminated semaphore list.

The service first tests each semaphore in the list in succession. The first semaphore found that is in a ^DONE state ends the service and its handle is immediately reported to the requesting task. If no

semaphore is found to be in a ^DONE state, a value of zero is reported to the requesting task to indicate no signals were present.

Regardless of the states of the semaphores in the list, the service returns immediately to the requesting task.

Note: It is illegal for a semaphore to occur more than once in the semaphore list.

Output

This service returns the handle of the semaphore receiving the event signal.

If none of the semaphores in semaphore list contained an unprocessed signal, the service returns a value of zero.

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.

psemalist A pointer to a null-terminated semaphore list.

KS_TestSemaM

Example

In Example 3-18, the Current Task needs to know when any of three events occur. The ^SWITCH1 and ^SWITCH2 events are associated with switch closures, while the ^TIMERA event is associated with a timer.

When any one event occurs, the task performs a code segment specific to that event.

Example 3-18. Test List of Semaphores

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

#include "ksema.h" /* defines SWITCH1, SWITCH2, TIMERA */

SEMA cause;

const SEMA semalist[] = {

cause = KS_TestSemaM (semalist);

switch (cause)

Synopsis

SEMA KS_TestSemaMT (const SEMA *psemalist, COUNTER counter, TICKS ticks)

Inputs

Description

^TheKS_TestSemaMT kernel service performs the same function as the KS_TestSemaMW directive, except it uses a defined number of ticks on a specified counter to limit the duration of the waiting period. The KS_TestSemaMT service operates as a logical OR; the occurrence of any event associated with any one of the semaphores in the list causes resumption of the requesting task.

The service puts each semaphore in the list pointed to by psemalist into a ^WAITING state if it is in a ^PENDING state, or leaves it in the WAITING state if it is already ^WAITING. If the service finds that no semaphore in the list contains a signal, the service blocks the calling task, removes it from the Ready List, and starts an internal alarm on the specified counter for the duration interval specified in ticks.

The task continues to be blocked until one of two situations occurs:

` A signal to any one of the semaphores in the list pointed to by psemalist occurs, or

` The specified number of ticks elapses.

Note: It is illegal for a semaphore to occur more than once in the semaphore list.

psemalist A pointer to a null-terminated semaphore list.

counter The counter associated with the tick interval defined by ticks.

ticks The number of ticks on counter to wait for the signal.

KS_TestSemaMT

Output

If one of the semaphores is signaled before the specified number of ticks elapses, this service returns the handle of the semaphore associated with the triggering event.

The service returns zero (0) if the specified number of ticks elapses.

Note: If the service detects signals on multiple semaphores, it preserves the signaling order only for the first event. For example, a call to KS_TestSemaMT tests the A, B, and C semaphores and finds no signals. The service blocks the requesting task and starts a internal alarm. Now, suppose the C semaphore receives a signal before the specified number of ticks in the alarm elapses, but before the task can actually resume operation, the B and A semaphores receive signals. When the task actually regains CPU control, the KS_TestSemaMT service returns the handle of the C semaphore to identify it as having received the first signal.

If the task makes a subsequent call to KS_TestSemaMT, the task is not blocked and the service returns the handle of the A semaphore. Another call to KS_TestSemaMT

immediately returns the handle of the B semaphore.

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.

` FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

` FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.

Example

In Example 3-19 on page 114, the Current Task needs to know when

KS_TestSemaMT

However, if neither switch closes within the expected time of two seconds on counter[0], the task reads the lack of closure as a system malfunction and takes special action.

Example 3-19. Test List of Semaphores—Wait Number of Ticks for Signal

In document RTXC Kernel ServicesV2 Decrypted (Page 110-137)

INIT_SemaClassProp