RTEMS 6.1-rc4
|
The Semaphore Manager utilizes standard Dijkstra counting semaphores to provide synchronization and mutual exclusion capabilities. More...
Functions | |
rtems_status_code | rtems_semaphore_create (rtems_name name, uint32_t count, rtems_attribute attribute_set, rtems_task_priority priority_ceiling, rtems_id *id) |
Creates a semaphore. | |
rtems_status_code | rtems_semaphore_ident (rtems_name name, uint32_t node, rtems_id *id) |
Identifies a semaphore by the object name. | |
rtems_status_code | rtems_semaphore_delete (rtems_id id) |
Deletes the semaphore. | |
rtems_status_code | rtems_semaphore_obtain (rtems_id id, rtems_option option_set, rtems_interval timeout) |
Obtains the semaphore. | |
rtems_status_code | rtems_semaphore_release (rtems_id id) |
Releases the semaphore. | |
rtems_status_code | rtems_semaphore_flush (rtems_id id) |
Flushes the semaphore. | |
rtems_status_code | rtems_semaphore_set_priority (rtems_id semaphore_id, rtems_id scheduler_id, rtems_task_priority new_priority, rtems_task_priority *old_priority) |
Sets the priority by scheduler for the semaphore. | |
The Semaphore Manager utilizes standard Dijkstra counting semaphores to provide synchronization and mutual exclusion capabilities.
rtems_status_code rtems_semaphore_create | ( | rtems_name | name, |
uint32_t | count, | ||
rtems_attribute | attribute_set, | ||
rtems_task_priority | priority_ceiling, | ||
rtems_id * | id | ||
) |
Creates a semaphore.
name | is the object name of the semaphore. | |
count | is the initial count of the semaphore. If the semaphore is a binary semaphore, then a count of 0 will make the calling task the owner of the binary semaphore and a count of 1 will create a binary semaphore without an owner. | |
attribute_set | is the attribute set of the semaphore. | |
priority_ceiling | is the priority ceiling if the semaphore is a binary semaphore with the priority ceiling or MrsP locking protocol as defined by the attribute set. | |
[out] | id | is the pointer to an rtems_id object. When the directive call is successful, the identifier of the created semaphore will be stored in this object. |
This directive creates a semaphore which resides on the local node. The semaphore has the user-defined object name specified in name
and the initial count specified in count
. The assigned object identifier is returned in id
. This identifier is used to access the semaphore with other semaphore related directives.
The attribute set specified in attribute_set
is built through a bitwise or of the attribute constants described below. Not all combinations of attributes are allowed. Some attributes are mutually exclusive. If mutually exclusive attributes are combined, the behaviour is undefined. Attributes not mentioned below are not evaluated by this directive and have no effect. Default attributes can be selected by using the RTEMS_DEFAULT_ATTRIBUTES constant. The attribute set defines
The semaphore has a local or global scope in a multiprocessing network (this attribute does not refer to SMP systems). The scope is selected by the mutually exclusive RTEMS_LOCAL and RTEMS_GLOBAL attributes.
The task wait queue discipline is selected by the mutually exclusive RTEMS_FIFO and RTEMS_PRIORITY attributes.
The semaphore class is selected by the mutually exclusive RTEMS_COUNTING_SEMAPHORE, RTEMS_BINARY_SEMAPHORE, and RTEMS_SIMPLE_BINARY_SEMAPHORE attributes.
Binary semaphores may use a locking protocol. If a locking protocol is selected, then the scope shall be local and the priority task wait queue discipline shall be selected. The locking protocol is selected by the mutually exclusive RTEMS_INHERIT_PRIORITY, RTEMS_PRIORITY_CEILING, and RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attributes.
priority_ceiling
.priority_ceiling
. This priority is used to set the priority ceiling for all schedulers. This can be changed later with the rtems_semaphore_set_priority() directive using the returned object identifier.RTEMS_SUCCESSFUL | The requested operation was successful. |
RTEMS_INVALID_NAME | The name parameter was invalid. |
RTEMS_INVALID_ADDRESS | The id parameter was NULL. |
RTEMS_INVALID_NUMBER | The count parameter was invalid. |
RTEMS_NOT_DEFINED | The attribute_set parameter was invalid. |
RTEMS_TOO_MANY | There was no inactive object available to create a semaphore. The number of semaphores available to the application is configured through the CONFIGURE_MAXIMUM_SEMAPHORES application configuration option. |
RTEMS_TOO_MANY | In multiprocessing configurations, there was no inactive global object available to create a global semaphore. The number of global objects available to the application is configured through the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. |
RTEMS_INVALID_PRIORITY | The priority_ceiling parameter was invalid. |
For control and maintenance of the semaphore, RTEMS allocates a SMCB from the local SMCB free pool and initializes it.
The SMCB for a global semaphore is allocated on the local node. Semaphores should not be made global unless remote tasks must interact with the 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 identifier must be transmitted to every node in the system for insertion in the local copy of the global object table.
The following constraints apply to this directive:
rtems_status_code rtems_semaphore_delete | ( | rtems_id | id | ) |
Deletes the semaphore.
id | is the semaphore identifier. |
This directive deletes the semaphore specified by id
.
RTEMS_SUCCESSFUL | The requested operation was successful. |
RTEMS_INVALID_ID | There was no semaphore associated with the identifier specified by id . |
RTEMS_ILLEGAL_ON_REMOTE_OBJECT | The semaphore resided on a remote node. |
RTEMS_RESOURCE_IN_USE | The binary semaphore had an owner. |
Binary semaphores with an owner cannot be deleted.
When a semaphore is deleted, all tasks blocked waiting to obtain the semaphore will be readied and returned a status code which indicates that the semaphore was deleted.
The SMCB for the deleted semaphore is reclaimed by RTEMS.
When a global semaphore is deleted, the semaphore identifier must be transmitted to every node in the system for deletion from the local copy of the global object table.
The semaphore must reside on the local node, even if the semaphore was created with the RTEMS_GLOBAL attribute.
Proxies, used to represent remote tasks, are reclaimed when the semaphore is deleted.
The following constraints apply to this directive:
rtems_status_code rtems_semaphore_flush | ( | rtems_id | id | ) |
Flushes the semaphore.
id | is the semaphore identifier. |
This directive unblocks all tasks waiting on the semaphore specified by id
. The semaphore's count is not changed by this directive. Tasks which are unblocked as the result of this directive will return from the rtems_semaphore_obtain() directive with a status code of RTEMS_UNSATISFIED to indicate that the semaphore was not obtained.
RTEMS_SUCCESSFUL | The requested operation was successful. |
RTEMS_INVALID_ID | There was no semaphore associated with the identifier specified by id . |
RTEMS_ILLEGAL_ON_REMOTE_OBJECT | The semaphore resided on a remote node. |
RTEMS_NOT_DEFINED | Flushing a semaphore using the MrsP locking protocol is undefined behaviour. |
If the task to be unblocked resides on a different node from the semaphore, then the waiting task is unblocked, and the proxy used to represent the task is reclaimed.
It is not allowed to flush a local, binary semaphore using the MrsP locking protocol and any attempt to do this will just return the RTEMS_NOT_DEFINED status code. This error can only happen in SMP configurations.
For barrier synchronization, the Barrier Manager offers a cleaner alternative to using the semaphore flush directive. Unlike POSIX barriers, they have a manual release option.
Using the semaphore flush directive for condition synchronization in concert with another semaphore may be subject to the lost wake-up problem. The following attempt to implement a condition variable is broken.
The following constraints apply to this directive:
rtems_status_code rtems_semaphore_ident | ( | rtems_name | name, |
uint32_t | node, | ||
rtems_id * | id | ||
) |
Identifies a semaphore by the object name.
name | is the object name to look up. | |
node | is the node or node set to search for a matching object. | |
[out] | id | is the pointer to an rtems_id object. When the directive call is successful, the object identifier of an object with the specified name will be stored in this object. |
This directive obtains a semaphore identifier associated with the semaphore name specified in name
.
The node to search is specified in node
. It shall be
RTEMS_SUCCESSFUL | The requested operation was successful. |
RTEMS_INVALID_ADDRESS | The id parameter was NULL. |
RTEMS_INVALID_NAME | The name parameter was 0. |
RTEMS_INVALID_NAME | There was no object with the specified name on the specified nodes. |
RTEMS_INVALID_NODE | In multiprocessing configurations, the specified node was invalid. |
If the semaphore name is not unique, then the semaphore identifier will match the first semaphore with that name in the search order. However, this semaphore identifier is not guaranteed to correspond to the desired semaphore.
The objects are searched from lowest to the highest index. If node
is RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being searched first. All other nodes are searched from lowest to the highest node number.
If node is a valid node number which does not represent the local node, then only the semaphores exported by the designated node are searched.
This directive does not generate activity on remote nodes. It accesses only the local copy of the global object table.
The semaphore identifier is used with other semaphore related directives to access the semaphore.
The following constraints apply to this directive:
rtems_status_code rtems_semaphore_obtain | ( | rtems_id | id, |
rtems_option | option_set, | ||
rtems_interval | timeout | ||
) |
Obtains the semaphore.
id | is the semaphore identifier. |
option_set | is the option set. |
timeout | is the timeout in clock ticks if the RTEMS_WAIT option is set. Use RTEMS_NO_TIMEOUT to wait potentially forever. |
This directive obtains the semaphore specified by id
.
The option set specified in option_set
is built through a bitwise or of the option constants described below. Not all combinations of options are allowed. Some options are mutually exclusive. If mutually exclusive options are combined, the behaviour is undefined. Options not mentioned below are not evaluated by this directive and have no effect. Default options can be selected by using the RTEMS_DEFAULT_OPTIONS constant.
The calling task can wait or try to obtain the semaphore according to the mutually exclusive RTEMS_WAIT and RTEMS_NO_WAIT options.
timeout
parameter defines how long the calling task is willing to wait. Use RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout interval in clock ticks.timeout
parameter is ignored. When the semaphore cannot be immediately obtained, then the RTEMS_UNSATISFIED status is returned.With either RTEMS_WAIT or RTEMS_NO_WAIT if the current semaphore count is positive, then it is decremented by one and the semaphore is successfully obtained by returning immediately with the RTEMS_SUCCESSFUL status code.
If the calling task chooses to return immediately and the current semaphore count is zero, then the RTEMS_UNSATISFIED status code is returned indicating that the semaphore is not available.
If the calling task chooses to wait for a semaphore and the current semaphore count is zero, then the calling task is placed on the semaphore's wait queue and blocked. If a local, binary semaphore was created with the RTEMS_INHERIT_PRIORITY attribute, then the priority of the task currently holding the binary semaphore will inherit the current priority set of the blocking task. The priority inheritance is carried out recursively. This means, that if the task currently holding the binary semaphore is blocked on another local, binary semaphore using the priority inheritance locking protocol, then the owner of this semaphore will inherit the current priority sets of both tasks, and so on. A task has a current priority for each scheduler.
RTEMS_SUCCESSFUL | The requested operation was successful. |
RTEMS_INVALID_ID | There was no semaphore associated with the identifier specified by id . |
RTEMS_NOT_DEFINED | The semaphore uses a priority ceiling and there was no priority ceiling defined for the home scheduler of the calling task. |
RTEMS_UNSATISFIED | The semaphore could not be obtained immediately. |
RTEMS_INVALID_PRIORITY | The semaphore uses a priority ceiling and the calling task had a current priority less than the priority ceiling. |
RTEMS_INCORRECT_STATE | Acquiring of the local, binary semaphore by the calling task would have cased a deadlock. |
RTEMS_INCORRECT_STATE | The calling task attempted to recursively obtain a local, binary semaphore using the MrsP locking protocol. |
RTEMS_UNSATISFIED | The semaphore was flushed while the calling task was waiting to obtain the semaphore. |
RTEMS_TIMEOUT | The timeout happened while the calling task was waiting to obtain the semaphore. |
RTEMS_OBJECT_WAS_DELETED | The semaphore was deleted while the calling task was waiting to obtain the semaphore. |
If a local, binary semaphore was created with the RTEMS_PRIORITY_CEILING or RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute, a task successfully obtains the semaphore, and the priority of that task is greater than the ceiling priority for this semaphore, then the priority of the task acquiring the semaphore is elevated to that of the ceiling.
Deadlock situations are detected for local, binary semaphores. If a deadlock is detected, then the directive immediately returns the RTEMS_INCORRECT_STATE status code.
It is not allowed to recursively obtain (nested access) a local, binary semaphore using the MrsP locking protocol and any attempt to do this will just return the RTEMS_INCORRECT_STATE status code. This error can only happen in SMP configurations.
If the semaphore was created with the RTEMS_PRIORITY attribute, then the calling task is inserted into the wait queue according to its priority. However, if the semaphore was created with the RTEMS_FIFO attribute, then the calling task is placed at the rear of the wait queue.
Attempting to obtain a global semaphore which does not reside on the local node will generate a request to the remote node to access the semaphore. If the semaphore is not available and RTEMS_NO_WAIT was not specified, then the task must be blocked until the semaphore is released. A proxy is allocated on the remote node to represent the task until the semaphore is released.
The following constraints apply to this directive:
rtems_status_code rtems_semaphore_release | ( | rtems_id | id | ) |
Releases the semaphore.
id | is the semaphore identifier. |
This directive releases the semaphore specified by id
. If the semaphore's wait queue is not empty, then
RTEMS_SUCCESSFUL | The requested operation was successful. |
RTEMS_INVALID_ID | There was no semaphore associated with the identifier specified by id . |
RTEMS_NOT_OWNER_OF_RESOURCE | The calling task was not the owner of the semaphore. |
RTEMS_UNSATISFIED | The semaphore's count already had the maximum value of UINT32_MAX. |
The calling task may be preempted if it causes a higher priority task to be made ready for execution.
The outermost release of a local, binary semaphore using the priority inheritance, priority ceiling, or MrsP locking protocol may result in the calling task having its priority lowered. This will occur if the highest priority of the calling task was available due to the ownership of the released semaphore. If a task was on the semaphore's wait queue, then the priority associated with the semaphore will be transferred to the new owner.
Releasing a global semaphore which does not reside on the local node will generate a request telling the remote node to release the semaphore.
If the task to be unblocked resides on a different node from the semaphore, then the semaphore allocation is forwarded to the appropriate node, the waiting task is unblocked, and the proxy used to represent the task is reclaimed.
The following constraints apply to this directive:
rtems_status_code rtems_semaphore_set_priority | ( | rtems_id | semaphore_id, |
rtems_id | scheduler_id, | ||
rtems_task_priority | new_priority, | ||
rtems_task_priority * | old_priority | ||
) |
Sets the priority by scheduler for the semaphore.
semaphore_id | is the semaphore identifier. | |
scheduler_id | is the identifier of the scheduler corresponding to the new priority. | |
new_priority | is the new priority corresponding to the specified scheduler. | |
[out] | old_priority | is the pointer to an rtems_task_priority object. When the directive call is successful, the old priority of the semaphore corresponding to the specified scheduler will be stored in this object. |
This directive sets the priority of the semaphore specified by semaphore_id
. The priority corresponds to the scheduler specified by scheduler_id
.
The special priority value RTEMS_CURRENT_PRIORITY can be used to get the current priority without changing it.
The availability and use of a priority depends on the class and locking protocol of the semaphore:
RTEMS_SUCCESSFUL | The requested operation was successful. |
RTEMS_INVALID_ADDRESS | The old_priority parameter was NULL. |
RTEMS_INVALID_ID | There was no scheduler associated with the identifier specified by scheduler_id . |
RTEMS_INVALID_ID | There was no semaphore associated with the identifier specified by semaphore_id . |
RTEMS_ILLEGAL_ON_REMOTE_OBJECT | The semaphore resided on a remote node. |
RTEMS_INVALID_PRIORITY | The new_priority parameter was invalid. |
RTEMS_NOT_DEFINED | Setting a priority for the class or locking protocol of the semaphore is undefined behaviour. |
Please have a look at the following example:
The following constraints apply to this directive: