RTEMS 4.0.0 On-Line Library

Semaphore Manager SEMAPHORE_CREATE - Create a semaphore

RTEMS C User's Guide

8.4.1: SEMAPHORE_CREATE - Create a semaphore

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_create(
  rtems_name           name,
  rtems_unsigned32     count,
  rtems_attribute      attribute_set,
  rtems_task_priority  priority_ceiling,
  rtems_id            *id
);

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_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 C User's Guide