RTEMS 4.5.1-pre3 On-Line Library

Semaphore Manager SEMAPHORE_CREATE - Create a semaphore

RTEMS Ada User's Guide

9.4.1: SEMAPHORE_CREATE - Create a semaphore

CALLING SEQUENCE:

procedure Semaphore_Create (
   Name          : in     RTEMS.Name;
   Count         : in     RTEMS.Unsigned32;
   Attribute_Set : in     RTEMS.Attribute;
   ID            :    out RTEMS.ID;
   Result        :    out RTEMS.Status_Codes
);

DIRECTIVE STATUS CODES:

RTEMS.SUCCESSFUL - semaphore created successfully
RTEMS.INVALID_NAME - invalid task name
RTEMS.TOO_MANY - too many semaphores created
RTEMS.NOT_DEFINED - invalid attribute set
RTEMS.INVALID_NUMBER - invalid starting count for binary semaphore
RTEMS.MP_NOT_CONFIGURED - multiprocessing not configured
RTEMS.TOO_MANY - too many global objects

DESCRIPTION:

This directive creates a semaphore which resides on the local node. The created semaphore has the user-defined name specified in name and the initial count specified in count. For control and maintenance of the semaphore, RTEMS allocates and initializes a SMCB. The RTEMS-assigned semaphore id is returned in id. This semaphore id is used with other semaphore related directives to access the semaphore.

Specifying PRIORITY in attribute_set causes tasks waiting for a semaphore to be serviced according to task priority. When FIFO is selected, tasks are serviced in First In-First Out order.

NOTES:

This directive will not cause the calling task to be preempted.

The priority inheritance and priority ceiling algorithms are only supported for local, binary semaphores that use the priority task wait queue blocking discipline.

The following semaphore attribute constants are defined by RTEMS:

RTEMS.FIFO - tasks wait by FIFO (default)
RTEMS.PRIORITY - tasks wait by priority
RTEMS.BINARY_SEMAPHORE - restrict values to 0 and 1 (default)
RTEMS.COUNTING_SEMAPHORE - no restriction on values
RTEMS.SIMPLE_BINARY_SEMAPHORE - restrict values to 0 and 1, block on nested access, allow deletion of locked semaphore.
RTEMS.NO_INHERIT_PRIORITY - do not use priority inheritance (default)
RTEMS.INHERIT_PRIORITY - use priority inheritance
RTEMS.PRIORITY_CEILING - use priority ceiling
RTEMS.NO_PRIORITY_CEILING - do not use priority ceiling (default)
RTEMS.LOCAL - local task (default)
RTEMS.GLOBAL - global task

Semaphores should not be made global unless remote tasks must interact with the created semaphore. This is to avoid the system overhead incurred by the creation of a global semaphore. When a global semaphore is created, the semaphore's name and id must be transmitted to every node in the system for insertion in the local copy of the global object table.

The total number of global objects, including semaphores, is limited by the maximum_global_objects field in the Configuration Table.

RTEMS Ada User's Guide