|
RTEMS
|
The Semaphore Manager utilizes standard Dijkstra counting semaphores to provide synchronization and mutual exclusion capabilities. More...
Files | |
| file | sem.h |
| This header file defines the Semaphore Manager API. | |
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 with the specified properties and returns its identifier. More... | |
| rtems_status_code | rtems_semaphore_delete (rtems_id id) |
| % More... | |
| rtems_status_code | rtems_semaphore_flush (rtems_id id) |
| % More... | |
| rtems_status_code | rtems_semaphore_ident (rtems_name name, uint32_t node, rtems_id *id) |
| Identifies a semaphore object by the specified object name. More... | |
| rtems_status_code | rtems_semaphore_obtain (rtems_id id, rtems_option option_set, rtems_interval timeout) |
| % More... | |
| rtems_status_code | rtems_semaphore_release (rtems_id id) |
| % More... | |
| 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) |
| % More... | |
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 with the specified properties and returns its identifier.
This directive creates a semaphore which resides on the local node. The new 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 identifier is returned in id. This semaphore identifier is used with other semaphore related directives to access the semaphore.
The attribute set specified in attribute_set defines
The 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.
The scope of a semaphore is either the local node only (local scope) or all nodes in a multiprocessing network (global scope). 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 in all scheduler instances. This can be changed later with the rtems_semaphore_set_priority() directive using the returned semaphore identifier.This directive may cause the calling task to be preempted due to an obtain and release of the object allocator mutex.
Semaphores should not be made global unless remote tasks must interact with the new 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 total number of global objects, including semaphores, is limited by the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.
It is not allowed to create an initially locked MrsP semaphore and the RTEMS_INVALID_NUMBER status code will be returned in SMP configurations in this case. This prevents lock order reversal problems with the allocator mutex.
| name | is the object name of the new semaphore. | |
| count | is the initial count of the new semaphore. If the semaphore is a mutex, then a count of 0 will make the calling task the owner of the new mutex and a count of 1 will create a mutex without an owner. | |
| attribute_set | is the attribute set which defines the properties of the new semaphore. | |
| priority_ceiling | is the priority ceiling if the new semaphore is a binary semaphore with the priority ceiling or MrsP semaphore locking protocol as defined by the attribute set. | |
| [out] | id | is the pointer to an object identifier variable. The object identifier of the new semaphore will be stored in this variable, in case of a successful operation. |
| RTEMS_SUCCESSFUL | The requested operation was successful. |
| RTEMS_INVALID_ADDRESS | The priority_ceiling parameter was NULL. |
| RTEMS_INVALID_NAME | The semaphore name was invalid. |
| RTEMS_INVALID_PRIORITY | The priority ceiling was invalid. |
| RTEMS_NOT_DEFINED | The attribute set was invalid. |
| RTEMS_TOO_MANY | There was no inactive semaphore object available to create a new semaphore. The semaphore object maximum is defined by the CONFIGURE_MAXIMUM_SEMAPHORES application configuration option. |
| RTEMS_TOO_MANY | In multiprocessing configurations, there was no inactive global object available to create a new global semaphore. |
Definition at line 34 of file semcreate.c.
| rtems_status_code rtems_semaphore_delete | ( | rtems_id | id | ) |
| rtems_status_code rtems_semaphore_flush | ( | rtems_id | id | ) |
%
| id | % |
| rtems_status_code rtems_semaphore_ident | ( | rtems_name | name, |
| uint32_t | node, | ||
| rtems_id * | id | ||
| ) |
Identifies a semaphore object by the specified object name.
This directive obtains the semaphore identifier associated with the semaphore name specified in name.
The node to search is specified in node. It shall be
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 semaphore identifier is used with other semaphore related directives to access the semaphore.
If node is RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being searched first. All other nodes are searched with the lowest numbered node searched first.
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.
| 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 object identifier variable. The object identifier of an object with the specified name will be stored in this variable, in case of a successful operation. |
| 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. |
Definition at line 44 of file semident.c.
| rtems_status_code rtems_semaphore_obtain | ( | rtems_id | id, |
| rtems_option | option_set, | ||
| rtems_interval | timeout | ||
| ) |
| rtems_status_code rtems_semaphore_release | ( | rtems_id | id | ) |
| 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 | ||
| ) |
%
| semaphore_id | % |
| scheduler_id | % |
| new_priority | % |
| old_priority | % |
Definition at line 127 of file semsetpriority.c.
1.8.14