In This Chapter
We describe the Semaphore kernel services in detail. The Semaphore kernel services provide intertask synchronization between the calling task and other tasks through semaphores.
KS_CloseSema...80 KS_DefSemaCount...82 KS_DefSemaName...84 KS_DefSemaProp ...86 KS_GetSemaClassProp ...88 KS_GetSemaCount... 90 KS_GetSemaName...92 KS_GetSemaProp ...94 INIT_SemaClassProp ... 96 KS_LookupSema ...98 KS_OpenSema ...100 XX_SignalSema ... 102 XX_SignalSemaM... 104 KS_TestSema...106 KS_TestSemaT ... 108 KS_TestSemaM ... 110 KS_TestSemaMT ...112
KS_CloseSema
KS_CloseSema
End the use of a dynamic semaphore.
Synopsis
KSRC KS_CloseSema (SEMA sema)Input
Description
The KS_CloseSema kernel service ends the Current Task’s use of the dynamic semaphore specified in sema. When closing the semaphore, the kernel detaches the calling task’s use of sema. If the caller is sema’s last user, the kernel releases the semaphore to the free pool of dynamic semaphores for reuse. If there is at least one other task using sema, the kernel does not release the semaphore to the free pool.Be careful when closing a semaphore on which multiple tasks may be waiting. Closing the semaphore may cause waiters to be lost.
However, you can avoid this problem if each task that uses the semaphore makes a KS_UseSema call before it begins using the semaphore and then makes a KS_CloseSema call when it is done using the semaphore.
Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.
Output
This service returns a KSRC value as follows:` RC_GOOD if the service is successful.
` RC_STATIC_OBJECT if the specified semaphore is not dynamic.
` RC_OBJECT_NOT_INUSE if the specified semaphore does not correspond to an active dynamic semaphore.
` RC_OBJECT_INUSE if the Current Task’s use of the specified semaphore is closed but it remains open for use by other tasks.
sema The handle of the semaphore the Current Task should stop using.
KS_CloseSema
Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.
Error
This service may generate the following fatal error code:FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
Example
In Example 3-1, the Current Task waits on a signal from another task indicating that it is time to close a dynamic semaphore. The handle of the dynamic semaphore is specified in dynsema. When the signal is received on the ENDALL semaphore, the Current Task closes its use of the associated dynamic semaphore.Example 3-1. Close Semaphore
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "ksema.h" /* defines ENDALL */
SEMA dynsema; /* dynamic semaphore's handle */
KSRC ksrc;
KS_TestSemaW (ENDALL); /* wait for signal */
/* then close the semaphore */
if ((ksrc = KS_CloseSema (dynsema)) != RC_GOOD) {
... may want to test return code and do something }
... dynamic semaphore is closed, continue
See Also
KS_OpenSema, page 100 KS_UseSema, page 120KS_DefSemaCount
KS_DefSemaCount
Define a semaphore count.
Synopsis
void KS_DefSemaCount (SEMA sema, SEMACOUNT count)Inputs
Description
The KS_DefSemaCount kernel service manipulates the count of the semaphore specified in sema. The count argument may be any value. If count is less than or equal to the current semaphore count, the semaphore count is set to count. Otherwise, the semaphore is signaled a number of times equal to the difference between the current count and count.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.
Example
In Example 3-2 on page 83, the Current Task forces the count of the MYSEMA static semaphore to a PENDING (zero) value to ensure it is in a known condition before subsequent use. The task then increments the semaphore count to three and then to five.sema The handle of the semaphore being defined.
count The count value for the semaphore.
KS_DefSemaCount
Example 3-2. Set Semaphore Count
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "ksema.h" /* defines MYSEMA */
/* force count to zero (0) */
KS_DefSemaCount (MYSEMA, (SEMACOUNT)0);
count = KS_GetSemaCount (MYSEMA);
/* signal three times to bring count to 3 */
KS_DefSemaCount (MYSEMA, (SEMACOUNT)3);
count = KS_GetSemaCount (MYSEMA);
/* signal twice to bring count to 5 */
KS_DefSemaCount (MYSEMA, (SEMACOUNT)5);
count = KS_GetSemaCount (MYSEMA);
See Also
KS_GetSemaCount, page 90KS_DefSemaName
KS_DefSemaName
Define the name of a previously opened dynamic semaphore.
Synopsis
KSRC KS_DefSemaName (SEMA sema, const char *pname)Inputs
Description
The KS_DefSemaName kernel service names or renames the dynamic semaphore specified in sema. The service uses the null-terminated string pointed to by pname for the semaphore’s new name.Static semaphores cannot be named or renamed under program control.
Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.
This service does not check for duplicate semaphore names.
Output
This service returns a KSRC value as follows:` RC_GOOD if the service completes successfully.
` RC_STATIC_OBJECT if the semaphore being named is static.
` RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Semaphore class is not enabled.
` RC_OBJECT_NOT_INUSE if the specified semaphore does not correspond to an active dynamic semaphore.
Error
This service may generate the following fatal error code:FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
sema The handle of the semaphore being defined.
pname A pointer to a null-terminated name string.
KS_DefSemaName
Example
In Example 3-3, the dynsema variable contains the handle of a previously opened semaphore. Assign the name NewSema to that dynamic semaphore so other users may reference it by name.Example 3-3. Assign Semaphore Name
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
SEMA dynsema;
if (KS_DefSemaName (dynsema, "NewSema") != RC_GOOD) {
... Naming operation failed. Deal with it here }
... naming operation was successful. Continue
See Also
KS_OpenSema, page 100 KS_GetSemaName, page 92 KS_LookupSema, page 98 KS_UseSema, page 120KS_DefSemaProp
KS_DefSemaProp
Define the properties of a semaphore.
Synopsis
void KS_DefSemaProp (SEMA sema, const SEMAPROP *psemaprop)Inputs
Description
The KS_DefSemaProp kernel service defines the properties of the semaphore specified in sema using the values contained in the SEMAPROP structure pointed to by psemaprop.Example 3-4 shows the organization of the SEMAPROP structure.
Example 3-4. Semaphore Properties Structure typedef struct
{
KATTR attributes; /* Waiting Order & signal type */
} SEMAPROP;
You may define the following semaphore attribute values:
The default values for the Waiting Order and Signal Type attributes can be restored by ANDing the attributes field with
~ATTR_FIFO_ORDER or ~ATTR_MULTIPLE_WAITERS, respectively.
sema The handle of the semaphore being defined.
psemaprop A pointer to a semaphore properties structure.
Waiting Order Indicates the order in which tasks wait to receive a signal on a semaphore. The default order is by task priority. Waiting Order can be changed to
chronological ordering by ORing the
ATTR_FIFO_ORDER constant into the attributes field.
Signal Type Indicates which tasks in the waiting list should be notified of the signal. By default, the service signals only the first task in the waiter list. Signal Type can be changed to notify all tasks waiting on the semaphore by ORing the ATTR_MULTIPLE_WAITERS constant into the attributes field.
KS_DefSemaProp
Output
This service does not return a value.Error
This service may generate the following fatal error code:FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
Example
In Example 3-5, the Current Task defines the properties of the dynamic semaphore specified in dynsema so that any tasks waiting for the event are ordered in descending order of task priority.Example 3-5. Specify Semaphore Waiting Order
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
SEMA dynsema;
SEMAPROP sprop;
KSRC ksrc;
/* get current properties of the semaphore */
KS_GetSemaProp (dynsema, &sprop);
/* use priority waiters */
sprop.attributes &= ~ATTR_FIFO_ORDER;
KS_DefSemaProp (dynsema, &sprop); /* define properties */
... Continue
See Also
KS_GetSemaProp, page 94 INIT_SemaClassProp, page 96 KS_OpenSema, page 100KS_GetSemaClassProp
KS_GetSemaClassProp
Get the Semaphore object class properties.
Synopsis
const KCLASSPROP * KS_GetSemaClassProp (int *pint)Input
Description
The KS_GetSemaClassProp kernel service obtains a pointer to the KCLASSPROP structure which was used during systeminitialization by the INIT_SemaClassProp service to initialize the Semaphore object class properties.
If the pint pointer contains a non-zero address, the current number of unused dynamic semaphores is stored in the indicated address. If pint contains a null pointer ((int *)0), the service ignores the parameter.
Example 3-6 shows the organization of the KCLASSPROP structure.
Example 3-6. Class Properties Structure typedef struct
{
KATTR attributes;
KOBJECT n_statics; /* number of static objects */
KOBJECT n_dynamics; /* number of dynamic objects */
short objsize; /* used for calculating offsets */
short totalsize; /* used to alloc object array RAM */
ksize_t namelen /* length of name string */
const char *pstaticnames;
} KCLASSPROP;
The attributes element of the Semaphore KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 3-1 on page 89.
pint A pointer to an integer variable in which to store the current number of unused dynamic semaphores.
KS_GetSemaClassProp
Output
If successful, this service returns a pointer to a KCLASSPROP structure.If the Semaphore class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).
If pint is not null ((int *)0), the service returns the number of available dynamic semaphores in the variable pointed to by pint.
Example
In Example 3-7, the Current Task needs the information contained in the KCLASSPROP structure for the Semaphore object class.Example 3-7. Read Semaphore Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KCLASSPROP *psemaclass;
int free_dyn;
/* Get the semaphore kernel object class properties */
if ((psemaclassprop = KS_GetSemaClassProp (&free_dyn)) == (const KCLASSPROP *)0)
{
putline ("Semaphore Class not initialized");
} else {
... /* semaphore object class properties are available for use */
Table 3-1. Semaphore Class Attributes and Masks
Attribute Mask
Static Names ATTR_STATIC_NAMES
Dynamics ATTR_DYNAMICS
Statistics ATTR_STATISTICS
KS_GetSemaCount
KS_GetSemaCount
Get the current semaphore count.
Synopsis
SEMACOUNT KS_GetSemaCount (SEMA sema)Input
Description
The KS_GetSemaCount kernel service obtains the count of the semaphore specified in sema. The state of the semaphore isdetermined by the value of the semaphore count. This service does not change the semaphore count.
Warning: The count, and therefore the state, of the semaphore may actually change between the time the request is issued and the time the semaphore count is returned. An exception that alters the state of the semaphore may interrupt the system after the kernel service has completed but before control can be returned to the Current Task.
Output
This service returns a SEMACOUNT value indicating the semaphore state as follows:` 0 means the semaphore contains no unprocessed signals.
` > 0 means the semaphore has signals that are unprocessed. The number of unprocessed signals is equal to the returned value.
` < 0 means ignore the next SEMACOUNT signals.
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 being queried.
KS_GetSemaCount
Example
In Example 3-8, the Current Task wants to determine if the AIDONE semaphore received a signal without waiting for the next signal. If the semaphore has received a signal, the task performs some processing.Example 3-8. Read Semaphore Count
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "ksema.h" /* defines AIDONE */
SEMACOUNT count;
if ((count = KS_GetSemaCount (AIDONE)) > (SEMACOUNT)0 ) {
... semaphore has been signaled, process something }
else {
... no signals, do something else }
See Also
XX_SignalSema, page 102 KS_DefSemaCount, page 82KS_GetSemaName
KS_GetSemaName
Get the name of a semaphore.
Synopsis
char * KS_GetSemaName (SEMA sema)Input
Description
The KS_GetSemaName kernel service obtains a pointer to the null-terminated string containing the name of the semaphore specified in sema. The semaphore may be static or dynamic.Note: To use this service on static semaphores, you must enable the Static Names attribute of the Semaphore class during system generation.
Output
If the semaphore has a name, this service returns a pointer to the null-terminated name string.If the semaphore has no name, the service returns a null pointer ((char *)0).
Error
This service may generate the following fatal error code:FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
Example
In Example 3-9 on page 93, the Current Task needs to report the name of the dynamic semaphore specified in dynsema.sema The handle of the semaphore being queried.
KS_GetSemaName
Example 3-9. Read Semaphore Name
#include <stdio.h> /* standard i/o */
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
static char buf[128];
SEMA dynsema;
char *pname;
if ((pname = KS_GetSemaName (dynsema)) == (char *)0 ) sprintf (buf, "Semaphore %d has no name\n", dynsema);
else
sprintf (buf, "Semaphore %d name is %s\n", dynsema, pname);
putline (buf); /* send message to console */
See Also
KS_DefSemaName, page 84 KS_OpenSema, page 100KS_GetSemaProp
KS_GetSemaProp
Get the properties of a semaphore.
Synopsis
void KS_GetSemaProp (SEMA sema, SEMAPROP *psemaprop)Inputs
Description
The KS_GetSemaProp kernel service obtains all of the property values of the semaphore specified in sema in a single call. The service stores the property values in the SEMAPROP structure pointed to by psemaprop.The SEMAPROP structure has the following organization:
typedef struct_semaprop {
KATTR attributes; /* Signal Type, Waiting Order */
} SEMAPROP;
Output
This service returns the semaphore’s properties in the structure pointed to by psemaprop.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-10 on page 95, the Current Task needs to ensure that the properties of the dynamic semaphore specified in dynsema are defined so that tasks waiting for the associated event are ordered in descending order of task priority. The task first reads the existing properties of the specified semaphore and then forces priority order waiting.sema The handle of the semaphore being queried.
psemaprop A pointer to the Semaphore properties structure in which to store the semaphore’s properties.
KS_GetSemaProp
Example 3-10. Read Semaphore Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
SEMA dynsema;
SEMAPROP sprop;
KS_GetSemaProp (dynsema, &sprop); /* get properties */
if (sprop.attributes & ATTR_FIFO_ORDER) {
/* use priority mode*/
sprop.attributes &= ~ATTR_FIFO_ORDER;
/* define properties */
KS_DefSemaProp (dynsema, &sprop);
}
... continue