[ae68ff0] | 1 | @c |
---|
[4ffbc49] | 2 | @c COPYRIGHT (c) 1988-2007. |
---|
[ae68ff0] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
[139b2e4a] | 6 | @c $Id$ |
---|
| 7 | @c |
---|
[ae68ff0] | 8 | |
---|
| 9 | @chapter Semaphore Manager |
---|
[20515fc] | 10 | |
---|
[169502e] | 11 | @cindex semaphores |
---|
| 12 | @cindex binary semaphores |
---|
| 13 | @cindex counting semaphores |
---|
| 14 | @cindex mutual exclusion |
---|
| 15 | |
---|
[ae68ff0] | 16 | @section Introduction |
---|
| 17 | |
---|
| 18 | The semaphore manager utilizes standard Dijkstra |
---|
| 19 | counting semaphores to provide synchronization and mutual |
---|
| 20 | exclusion capabilities. The directives provided by the |
---|
| 21 | semaphore manager are: |
---|
| 22 | |
---|
| 23 | @itemize @bullet |
---|
[f331481c] | 24 | @item @code{@value{DIRPREFIX}semaphore_create} - Create a semaphore |
---|
| 25 | @item @code{@value{DIRPREFIX}semaphore_ident} - Get ID of a semaphore |
---|
| 26 | @item @code{@value{DIRPREFIX}semaphore_delete} - Delete a semaphore |
---|
| 27 | @item @code{@value{DIRPREFIX}semaphore_obtain} - Acquire a semaphore |
---|
| 28 | @item @code{@value{DIRPREFIX}semaphore_release} - Release a semaphore |
---|
[5a69fe3] | 29 | @item @code{@value{DIRPREFIX}semaphore_flush} - Unblock all tasks waiting on a semaphore |
---|
[ae68ff0] | 30 | @end itemize |
---|
| 31 | |
---|
| 32 | @section Background |
---|
| 33 | |
---|
| 34 | A semaphore can be viewed as a protected variable |
---|
[75e22db] | 35 | whose value can be modified only with the |
---|
| 36 | @code{@value{DIRPREFIX}semaphore_create}, |
---|
| 37 | @code{@value{DIRPREFIX}semaphore_obtain}, and |
---|
| 38 | @code{@value{DIRPREFIX}semaphore_release} directives. RTEMS |
---|
[ae68ff0] | 39 | supports both binary and counting semaphores. A binary semaphore |
---|
| 40 | is restricted to values of zero or one, while a counting |
---|
| 41 | semaphore can assume any non-negative integer value. |
---|
| 42 | |
---|
| 43 | A binary semaphore can be used to control access to a |
---|
| 44 | single resource. In particular, it can be used to enforce |
---|
| 45 | mutual exclusion for a critical section in user code. In this |
---|
| 46 | instance, the semaphore would be created with an initial count |
---|
| 47 | of one to indicate that no task is executing the critical |
---|
| 48 | section of code. Upon entry to the critical section, a task |
---|
[75e22db] | 49 | must issue the @code{@value{DIRPREFIX}semaphore_obtain} |
---|
| 50 | directive to prevent other tasks from entering the critical section. |
---|
| 51 | Upon exit from the critical section, the task must issue the |
---|
| 52 | @code{@value{DIRPREFIX}semaphore_release} directive to |
---|
[ae68ff0] | 53 | allow another task to execute the critical section. |
---|
| 54 | |
---|
| 55 | A counting semaphore can be used to control access to |
---|
| 56 | a pool of two or more resources. For example, access to three |
---|
| 57 | printers could be administered by a semaphore created with an |
---|
| 58 | initial count of three. When a task requires access to one of |
---|
[75e22db] | 59 | the printers, it issues the @code{@value{DIRPREFIX}semaphore_obtain} |
---|
| 60 | directive to obtain access to a printer. If a printer is not currently |
---|
| 61 | available, the task can wait for a printer to become available or return |
---|
[ae68ff0] | 62 | immediately. When the task has completed printing, it should |
---|
[75e22db] | 63 | issue the @code{@value{DIRPREFIX}semaphore_release} |
---|
| 64 | directive to allow other tasks access to the printer. |
---|
[ae68ff0] | 65 | |
---|
| 66 | Task synchronization may be achieved by creating a |
---|
| 67 | semaphore with an initial count of zero. One task waits for the |
---|
[75e22db] | 68 | arrival of another task by issuing a @code{@value{DIRPREFIX}semaphore_obtain} |
---|
| 69 | directive when it reaches a synchronization point. The other task |
---|
| 70 | performs a corresponding @code{@value{DIRPREFIX}semaphore_release} |
---|
| 71 | operation when it reaches its synchronization point, thus unblocking |
---|
| 72 | the pending task. |
---|
[ae68ff0] | 73 | |
---|
| 74 | @subsection Nested Resource Access |
---|
| 75 | |
---|
| 76 | Deadlock occurs when a task owning a binary semaphore |
---|
| 77 | attempts to acquire that same semaphore and blocks as result. |
---|
| 78 | Since the semaphore is allocated to a task, it cannot be |
---|
| 79 | deleted. Therefore, the task that currently holds the semaphore |
---|
| 80 | and is also blocked waiting for that semaphore will never |
---|
| 81 | execute again. |
---|
| 82 | |
---|
| 83 | RTEMS addresses this problem by allowing the task |
---|
| 84 | holding the binary semaphore to obtain the same binary semaphore |
---|
[75e22db] | 85 | multiple times in a nested manner. Each |
---|
| 86 | @code{@value{DIRPREFIX}semaphore_obtain} must be accompanied with a |
---|
| 87 | @code{@value{DIRPREFIX}semaphore_release}. The semaphore will |
---|
[ae68ff0] | 88 | only be made available for acquisition by other tasks when the |
---|
[75e22db] | 89 | outermost @code{@value{DIRPREFIX}semaphore_obtain} is matched with |
---|
| 90 | a @code{@value{DIRPREFIX}semaphore_release}. |
---|
[ae68ff0] | 91 | |
---|
[edc1347e] | 92 | Simple binary semaphores do not allow nested access and so can be used for task synchronization. |
---|
| 93 | |
---|
[ae68ff0] | 94 | |
---|
| 95 | @subsection Priority Inversion |
---|
| 96 | |
---|
| 97 | Priority inversion is a form of indefinite |
---|
| 98 | postponement which is common in multitasking, preemptive |
---|
| 99 | executives with shared resources. Priority inversion occurs |
---|
| 100 | when a high priority tasks requests access to shared resource |
---|
| 101 | which is currently allocated to low priority task. The high |
---|
| 102 | priority task must block until the low priority task releases |
---|
| 103 | the resource. This problem is exacerbated when the low priority |
---|
| 104 | task is prevented from executing by one or more medium priority |
---|
| 105 | tasks. Because the low priority task is not executing, it |
---|
| 106 | cannot complete its interaction with the resource and release |
---|
| 107 | that resource. The high priority task is effectively prevented |
---|
| 108 | from executing by lower priority tasks. |
---|
| 109 | |
---|
| 110 | @subsection Priority Inheritance |
---|
| 111 | |
---|
| 112 | Priority inheritance is an algorithm that calls for |
---|
| 113 | the lower priority task holding a resource to have its priority |
---|
| 114 | increased to that of the highest priority task blocked waiting |
---|
| 115 | for that resource. Each time a task blocks attempting to obtain |
---|
| 116 | the resource, the task holding the resource may have its |
---|
| 117 | priority increased. |
---|
| 118 | |
---|
| 119 | RTEMS supports priority inheritance for local, binary |
---|
| 120 | semaphores that use the priority task wait queue blocking |
---|
| 121 | discipline. When a task of higher priority than the task |
---|
| 122 | holding the semaphore blocks, the priority of the task holding |
---|
| 123 | the semaphore is increased to that of the blocking task. When |
---|
| 124 | the task holding the task completely releases the binary |
---|
| 125 | semaphore (i.e. not for a nested release), the holder's priority |
---|
| 126 | is restored to the value it had before any higher priority was |
---|
| 127 | inherited. |
---|
| 128 | |
---|
| 129 | The RTEMS implementation of the priority inheritance |
---|
| 130 | algorithm takes into account the scenario in which a task holds |
---|
| 131 | more than one binary semaphore. The holding task will execute |
---|
| 132 | at the priority of the higher of the highest ceiling priority or |
---|
| 133 | at the priority of the highest priority task blocked waiting for |
---|
| 134 | any of the semaphores the task holds. Only when the task |
---|
| 135 | releases ALL of the binary semaphores it holds will its priority |
---|
| 136 | be restored to the normal value. |
---|
| 137 | |
---|
| 138 | @subsection Priority Ceiling |
---|
| 139 | |
---|
| 140 | Priority ceiling is an algorithm that calls for the |
---|
| 141 | lower priority task holding a resource to have its priority |
---|
| 142 | increased to that of the highest priority task which will EVER |
---|
| 143 | block waiting for that resource. This algorithm addresses the |
---|
| 144 | problem of priority inversion although it avoids the possibility |
---|
| 145 | of changing the priority of the task holding the resource |
---|
| 146 | multiple times. The priority ceiling algorithm will only change |
---|
| 147 | the priority of the task holding the resource a maximum of one |
---|
| 148 | time. The ceiling priority is set at creation time and must be |
---|
| 149 | the priority of the highest priority task which will ever |
---|
| 150 | attempt to acquire that semaphore. |
---|
| 151 | |
---|
| 152 | RTEMS supports priority ceiling for local, binary |
---|
| 153 | semaphores that use the priority task wait queue blocking |
---|
| 154 | discipline. When a task of lower priority than the ceiling |
---|
| 155 | priority successfully obtains the semaphore, its priority is |
---|
| 156 | raised to the ceiling priority. When the task holding the task |
---|
| 157 | completely releases the binary semaphore (i.e. not for a nested |
---|
| 158 | release), the holder's priority is restored to the value it had |
---|
| 159 | before any higher priority was put into effect. |
---|
| 160 | |
---|
| 161 | The need to identify the highest priority task which |
---|
| 162 | will attempt to obtain a particular semaphore can be a difficult |
---|
| 163 | task in a large, complicated system. Although the priority |
---|
| 164 | ceiling algorithm is more efficient than the priority |
---|
| 165 | inheritance algorithm with respect to the maximum number of task |
---|
| 166 | priority changes which may occur while a task holds a particular |
---|
| 167 | semaphore, the priority inheritance algorithm is more forgiving |
---|
| 168 | in that it does not require this apriori information. |
---|
| 169 | |
---|
| 170 | The RTEMS implementation of the priority ceiling |
---|
| 171 | algorithm takes into account the scenario in which a task holds |
---|
| 172 | more than one binary semaphore. The holding task will execute |
---|
| 173 | at the priority of the higher of the highest ceiling priority or |
---|
| 174 | at the priority of the highest priority task blocked waiting for |
---|
| 175 | any of the semaphores the task holds. Only when the task |
---|
| 176 | releases ALL of the binary semaphores it holds will its priority |
---|
| 177 | be restored to the normal value. |
---|
| 178 | |
---|
[ed11cadf] | 179 | @subsection Building a Semaphore Attribute Set |
---|
[ae68ff0] | 180 | |
---|
| 181 | In general, an attribute set is built by a bitwise OR |
---|
| 182 | of the desired attribute components. The following table lists |
---|
| 183 | the set of valid semaphore attributes: |
---|
| 184 | |
---|
| 185 | @itemize @bullet |
---|
[75e22db] | 186 | @item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default) |
---|
| 187 | |
---|
| 188 | @item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority |
---|
| 189 | |
---|
| 190 | @item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to |
---|
[3d4d5ee] | 191 | 0 and 1 |
---|
[75e22db] | 192 | |
---|
| 193 | @item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values |
---|
[3d4d5ee] | 194 | (default) |
---|
[75e22db] | 195 | |
---|
[edc1347e] | 196 | @item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to |
---|
[bb4b574] | 197 | 0 and 1, do not allow nested access, allow deletion of locked semaphore. |
---|
[edc1347e] | 198 | |
---|
[75e22db] | 199 | @item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority |
---|
| 200 | inheritance (default) |
---|
| 201 | |
---|
| 202 | @item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance |
---|
| 203 | |
---|
| 204 | @item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling |
---|
| 205 | |
---|
| 206 | @item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority |
---|
| 207 | ceiling (default) |
---|
| 208 | |
---|
| 209 | @item @code{@value{RPREFIX}LOCAL} - local task (default) |
---|
| 210 | |
---|
| 211 | @item @code{@value{RPREFIX}GLOBAL} - global task |
---|
[ae68ff0] | 212 | @end itemize |
---|
| 213 | |
---|
| 214 | Attribute values are specifically designed to be |
---|
| 215 | mutually exclusive, therefore bitwise OR and addition operations |
---|
| 216 | are equivalent as long as each attribute appears exactly once in |
---|
| 217 | the component list. An attribute listed as a default is not |
---|
| 218 | required to appear in the attribute list, although it is a good |
---|
| 219 | programming practice to specify default attributes. If all |
---|
[75e22db] | 220 | defaults are desired, the attribute |
---|
| 221 | @code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be |
---|
[ae68ff0] | 222 | specified on this call. |
---|
| 223 | |
---|
[169502e] | 224 | This example demonstrates the attribute_set parameter needed to create a |
---|
| 225 | local semaphore with the task priority waiting queue discipline. The |
---|
| 226 | attribute_set parameter passed to the |
---|
| 227 | @code{@value{DIRPREFIX}semaphore_create} directive could be either |
---|
| 228 | @code{@value{RPREFIX}PRIORITY} or @code{@value{RPREFIX}LOCAL @value{OR} |
---|
| 229 | @value{RPREFIX}PRIORITY}. The attribute_set parameter can be set to |
---|
| 230 | @code{@value{RPREFIX}PRIORITY} because @code{@value{RPREFIX}LOCAL} is the |
---|
| 231 | default for all created tasks. If a similar semaphore were to be known |
---|
| 232 | globally, then the attribute_set parameter would be |
---|
[a3a7527] | 233 | @code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}. |
---|
[ae68ff0] | 234 | |
---|
[bd861cc6] | 235 | Some combinatinos of these attributes are invalid. For example, priority |
---|
| 236 | ordered blocking discipline must be applied to a binary semaphore in order |
---|
| 237 | to use either the priority inheritance or priority ceiling functionality. |
---|
| 238 | The following tree figure illustrates the valid combinations. |
---|
| 239 | |
---|
| 240 | @float Figure,fig:semaphore-attributes |
---|
| 241 | @caption{Valid Semaphore Attributes Combinations} |
---|
| 242 | |
---|
| 243 | @ifset use-ascii |
---|
| 244 | @example |
---|
| 245 | @group |
---|
| 246 | Not available in ASCII representation |
---|
| 247 | @end group |
---|
| 248 | @end example |
---|
| 249 | @end ifset |
---|
| 250 | |
---|
| 251 | @ifset use-tex |
---|
| 252 | @example |
---|
| 253 | @image{semaphore_attributes,5in,3.5in} |
---|
| 254 | @end example |
---|
| 255 | @end ifset |
---|
| 256 | |
---|
| 257 | @ifset use-html |
---|
| 258 | @html |
---|
| 259 | <IMG SRC="semaphore_attributes.png" WIDTH=550 HEIGHT=400 ALT="Valid Semaphore Attribute Combinations"> |
---|
| 260 | @end html |
---|
| 261 | @end ifset |
---|
| 262 | @end float |
---|
| 263 | |
---|
[ae68ff0] | 264 | @subsection Building a SEMAPHORE_OBTAIN Option Set |
---|
| 265 | |
---|
| 266 | In general, an option is built by a bitwise OR of the |
---|
| 267 | desired option components. The set of valid options for the |
---|
[75e22db] | 268 | @code{@value{DIRPREFIX}semaphore_obtain} directive are listed |
---|
| 269 | in the following table: |
---|
[ae68ff0] | 270 | |
---|
| 271 | @itemize @bullet |
---|
[f331481c] | 272 | @item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default) |
---|
| 273 | @item @code{@value{RPREFIX}NO_WAIT} - task should not wait |
---|
[ae68ff0] | 274 | @end itemize |
---|
| 275 | |
---|
[169502e] | 276 | Option values are specifically designed to be mutually exclusive, |
---|
| 277 | therefore bitwise OR and addition operations are equivalent as long as |
---|
| 278 | each attribute appears exactly once in the component list. An option |
---|
| 279 | listed as a default is not required to appear in the list, although it is |
---|
| 280 | a good programming practice to specify default options. If all defaults |
---|
| 281 | are desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should be |
---|
[ae68ff0] | 282 | specified on this call. |
---|
| 283 | |
---|
| 284 | This example demonstrates the option parameter needed |
---|
| 285 | to poll for a semaphore. The option parameter passed to the |
---|
[75e22db] | 286 | @code{@value{DIRPREFIX}semaphore_obtain} |
---|
| 287 | directive should be @code{@value{RPREFIX}NO_WAIT}. |
---|
[ae68ff0] | 288 | |
---|
| 289 | @section Operations |
---|
[20515fc] | 290 | |
---|
[ae68ff0] | 291 | @subsection Creating a Semaphore |
---|
| 292 | |
---|
[75e22db] | 293 | The @code{@value{DIRPREFIX}semaphore_create} directive creates a binary or |
---|
[ae68ff0] | 294 | counting semaphore with a user-specified name as well as an |
---|
| 295 | initial count. If a binary semaphore is created with a count of |
---|
| 296 | zero (0) to indicate that it has been allocated, then the task |
---|
| 297 | creating the semaphore is considered the current holder of the |
---|
| 298 | semaphore. At create time the method for ordering waiting tasks |
---|
| 299 | in the semaphore's task wait queue (by FIFO or task priority) is |
---|
| 300 | specified. Additionally, the priority inheritance or priority |
---|
| 301 | ceiling algorithm may be selected for local, binary semaphores |
---|
| 302 | that use the priority task wait queue blocking discipline. If |
---|
| 303 | the priority ceiling algorithm is selected, then the highest |
---|
| 304 | priority of any task which will attempt to obtain this semaphore |
---|
| 305 | must be specified. RTEMS allocates a Semaphore Control Block |
---|
| 306 | (SMCB) from the SMCB free list. This data structure is used by |
---|
| 307 | RTEMS to manage the newly created semaphore. Also, a unique |
---|
| 308 | semaphore ID is generated and returned to the calling task. |
---|
| 309 | |
---|
| 310 | @subsection Obtaining Semaphore IDs |
---|
| 311 | |
---|
| 312 | When a semaphore is created, RTEMS generates a unique |
---|
| 313 | semaphore ID and assigns it to the created semaphore until it is |
---|
| 314 | deleted. The semaphore ID may be obtained by either of two |
---|
| 315 | methods. First, as the result of an invocation of the |
---|
[75e22db] | 316 | @code{@value{DIRPREFIX}semaphore_create} directive, the |
---|
| 317 | semaphore ID is stored in a user provided location. Second, |
---|
| 318 | the semaphore ID may be obtained later using the |
---|
| 319 | @code{@value{DIRPREFIX}semaphore_ident} directive. The semaphore ID is |
---|
[ae68ff0] | 320 | used by other semaphore manager directives to access this |
---|
| 321 | semaphore. |
---|
| 322 | |
---|
| 323 | @subsection Acquiring a Semaphore |
---|
| 324 | |
---|
[75e22db] | 325 | The @code{@value{DIRPREFIX}semaphore_obtain} directive is used to acquire the |
---|
[ae68ff0] | 326 | specified semaphore. A simplified version of the |
---|
[75e22db] | 327 | @code{@value{DIRPREFIX}semaphore_obtain} directive can be described as follows: |
---|
[ae68ff0] | 328 | |
---|
| 329 | @example |
---|
| 330 | if semaphore's count is greater than zero |
---|
| 331 | then decrement semaphore's count |
---|
| 332 | else wait for release of semaphore |
---|
| 333 | |
---|
| 334 | return SUCCESSFUL |
---|
| 335 | @end example |
---|
| 336 | |
---|
| 337 | When the semaphore cannot be immediately acquired, |
---|
| 338 | one of the following situations applies: |
---|
| 339 | |
---|
| 340 | @itemize @bullet |
---|
| 341 | @item By default, the calling task will wait forever to |
---|
| 342 | acquire the semaphore. |
---|
| 343 | |
---|
[169502e] | 344 | @item Specifying @code{@value{RPREFIX}NO_WAIT} forces an immediate return |
---|
| 345 | with an error status code. |
---|
[ae68ff0] | 346 | |
---|
| 347 | @item Specifying a timeout limits the interval the task will |
---|
| 348 | wait before returning with an error status code. |
---|
| 349 | @end itemize |
---|
| 350 | |
---|
| 351 | If the task waits to acquire the semaphore, then it |
---|
| 352 | is placed in the semaphore's task wait queue in either FIFO or |
---|
| 353 | task priority order. If the task blocked waiting for a binary |
---|
| 354 | semaphore using priority inheritance and the task's priority is |
---|
| 355 | greater than that of the task currently holding the semaphore, |
---|
| 356 | then the holding task will inherit the priority of the blocking |
---|
| 357 | task. All tasks waiting on a semaphore are returned an error |
---|
| 358 | code when the semaphore is deleted. |
---|
| 359 | |
---|
| 360 | When a task successfully obtains a semaphore using |
---|
| 361 | priority ceiling and the priority ceiling for this semaphore is |
---|
| 362 | greater than that of the holder, then the holder's priority will |
---|
| 363 | be elevated. |
---|
| 364 | |
---|
| 365 | @subsection Releasing a Semaphore |
---|
| 366 | |
---|
[75e22db] | 367 | The @code{@value{DIRPREFIX}semaphore_release} directive is used to release |
---|
[ae68ff0] | 368 | the specified semaphore. A simplified version of the |
---|
[169502e] | 369 | @code{@value{DIRPREFIX}semaphore_release} directive can be described as |
---|
| 370 | follows: |
---|
[ae68ff0] | 371 | |
---|
| 372 | @example |
---|
| 373 | if no tasks are waiting on this semaphore |
---|
| 374 | then increment semaphore's count |
---|
| 375 | else assign semaphore to a waiting task |
---|
| 376 | |
---|
| 377 | return SUCCESSFUL |
---|
| 378 | @end example |
---|
| 379 | |
---|
| 380 | If this is the outermost release of a binary |
---|
| 381 | semaphore that uses priority inheritance or priority ceiling and |
---|
| 382 | the task does not currently hold any other binary semaphores, |
---|
[75e22db] | 383 | then the task performing the @code{@value{DIRPREFIX}semaphore_release} |
---|
| 384 | will have its priority restored to its normal value. |
---|
[ae68ff0] | 385 | |
---|
| 386 | @subsection Deleting a Semaphore |
---|
| 387 | |
---|
[75e22db] | 388 | The @code{@value{DIRPREFIX}semaphore_delete} directive removes a semaphore |
---|
[ae68ff0] | 389 | from the system and frees its control block. A semaphore can be |
---|
| 390 | deleted by any local task that knows the semaphore's ID. As a |
---|
| 391 | result of this directive, all tasks blocked waiting to acquire |
---|
| 392 | the semaphore will be readied and returned a status code which |
---|
| 393 | indicates that the semaphore was deleted. Any subsequent |
---|
| 394 | references to the semaphore's name and ID are invalid. |
---|
| 395 | |
---|
| 396 | @section Directives |
---|
| 397 | |
---|
| 398 | This section details the semaphore manager's |
---|
| 399 | directives. A subsection is dedicated to each of this manager's |
---|
| 400 | directives and describes the calling sequence, related |
---|
| 401 | constants, usage, and status codes. |
---|
| 402 | |
---|
[169502e] | 403 | @c |
---|
| 404 | @c |
---|
| 405 | @c |
---|
[ae68ff0] | 406 | @page |
---|
| 407 | @subsection SEMAPHORE_CREATE - Create a semaphore |
---|
| 408 | |
---|
[169502e] | 409 | @cindex create a semaphore |
---|
| 410 | |
---|
[ae68ff0] | 411 | @subheading CALLING SEQUENCE: |
---|
| 412 | |
---|
[61389eac] | 413 | @ifset is-C |
---|
[169502e] | 414 | @findex rtems_semaphore_create |
---|
[ae68ff0] | 415 | @example |
---|
| 416 | rtems_status_code rtems_semaphore_create( |
---|
| 417 | rtems_name name, |
---|
[ae10dbd] | 418 | uint32_t count, |
---|
[ae68ff0] | 419 | rtems_attribute attribute_set, |
---|
| 420 | rtems_task_priority priority_ceiling, |
---|
| 421 | rtems_id *id |
---|
| 422 | ); |
---|
| 423 | @end example |
---|
[61389eac] | 424 | @end ifset |
---|
| 425 | |
---|
| 426 | @ifset is-Ada |
---|
| 427 | @example |
---|
| 428 | procedure Semaphore_Create ( |
---|
[4ffbc49] | 429 | Name : in RTEMS.Name; |
---|
| 430 | Count : in RTEMS.Unsigned32; |
---|
| 431 | Attribute_Set : in RTEMS.Attribute; |
---|
| 432 | Priority_Ceiling : in RTEMS.Task_Priority; |
---|
| 433 | ID : out RTEMS.ID; |
---|
| 434 | Result : out RTEMS.Status_Codes |
---|
[61389eac] | 435 | ); |
---|
| 436 | @end example |
---|
| 437 | @end ifset |
---|
[ae68ff0] | 438 | |
---|
| 439 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 440 | @code{@value{RPREFIX}SUCCESSFUL} - semaphore created successfully@* |
---|
[4dc6a46] | 441 | @code{@value{RPREFIX}INVALID_NAME} - invalid semaphore name@* |
---|
[f8892c9] | 442 | @code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@* |
---|
[f331481c] | 443 | @code{@value{RPREFIX}TOO_MANY} - too many semaphores created@* |
---|
| 444 | @code{@value{RPREFIX}NOT_DEFINED} - invalid attribute set@* |
---|
| 445 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid starting count for binary semaphore@* |
---|
| 446 | @code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@* |
---|
| 447 | @code{@value{RPREFIX}TOO_MANY} - too many global objects |
---|
[ae68ff0] | 448 | |
---|
| 449 | @subheading DESCRIPTION: |
---|
| 450 | |
---|
| 451 | This directive creates a semaphore which resides on |
---|
| 452 | the local node. The created semaphore has the user-defined name |
---|
| 453 | specified in name and the initial count specified in count. For |
---|
| 454 | control and maintenance of the semaphore, RTEMS allocates and |
---|
| 455 | initializes a SMCB. The RTEMS-assigned semaphore id is returned |
---|
| 456 | in id. This semaphore id is used with other semaphore related |
---|
| 457 | directives to access the semaphore. |
---|
| 458 | |
---|
| 459 | Specifying PRIORITY in attribute_set causes tasks |
---|
| 460 | waiting for a semaphore to be serviced according to task |
---|
| 461 | priority. When FIFO is selected, tasks are serviced in First |
---|
| 462 | In-First Out order. |
---|
| 463 | |
---|
| 464 | @subheading NOTES: |
---|
| 465 | |
---|
| 466 | This directive will not cause the calling task to be |
---|
| 467 | preempted. |
---|
| 468 | |
---|
| 469 | The priority inheritance and priority ceiling |
---|
| 470 | algorithms are only supported for local, binary semaphores that |
---|
| 471 | use the priority task wait queue blocking discipline. |
---|
| 472 | |
---|
| 473 | The following semaphore attribute constants are |
---|
| 474 | defined by RTEMS: |
---|
| 475 | |
---|
| 476 | @itemize @bullet |
---|
[75e22db] | 477 | @item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default) |
---|
| 478 | |
---|
| 479 | @item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority |
---|
| 480 | |
---|
| 481 | @item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to |
---|
[3d4d5ee] | 482 | 0 and 1 |
---|
[75e22db] | 483 | |
---|
| 484 | @item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values |
---|
[3d4d5ee] | 485 | (default) |
---|
[75e22db] | 486 | |
---|
[edc1347e] | 487 | @item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to |
---|
[bb4b574] | 488 | 0 and 1, block on nested access, allow deletion of locked semaphore. |
---|
[edc1347e] | 489 | |
---|
[75e22db] | 490 | @item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority |
---|
| 491 | inheritance (default) |
---|
| 492 | |
---|
| 493 | @item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance |
---|
| 494 | |
---|
| 495 | @item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling |
---|
| 496 | |
---|
| 497 | @item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority |
---|
| 498 | ceiling (default) |
---|
| 499 | |
---|
[bd861cc6] | 500 | @item @code{@value{RPREFIX}LOCAL} - local semaphore (default) |
---|
[75e22db] | 501 | |
---|
[bd861cc6] | 502 | @item @code{@value{RPREFIX}GLOBAL} - global semaphore |
---|
[ae68ff0] | 503 | @end itemize |
---|
| 504 | |
---|
| 505 | Semaphores should not be made global unless remote |
---|
| 506 | tasks must interact with the created semaphore. This is to |
---|
| 507 | avoid the system overhead incurred by the creation of a global |
---|
| 508 | semaphore. When a global semaphore is created, the semaphore's |
---|
| 509 | name and id must be transmitted to every node in the system for |
---|
| 510 | insertion in the local copy of the global object table. |
---|
| 511 | |
---|
[bd861cc6] | 512 | Note that some combinations of attributes are not valid. See the |
---|
| 513 | earlier discussion on this. |
---|
| 514 | |
---|
| 515 | The total number of global objects, including semaphores, is limited by |
---|
| 516 | the maximum_global_objects field in the Configuration Table. |
---|
[ae68ff0] | 517 | |
---|
[169502e] | 518 | @c |
---|
| 519 | @c |
---|
| 520 | @c |
---|
[ae68ff0] | 521 | @page |
---|
| 522 | @subsection SEMAPHORE_IDENT - Get ID of a semaphore |
---|
| 523 | |
---|
[169502e] | 524 | @cindex get ID of a semaphore |
---|
| 525 | @cindex obtain ID of a semaphore |
---|
| 526 | |
---|
[ae68ff0] | 527 | @subheading CALLING SEQUENCE: |
---|
| 528 | |
---|
[61389eac] | 529 | @ifset is-C |
---|
[169502e] | 530 | @findex rtems_semaphore_ident |
---|
[ae68ff0] | 531 | @example |
---|
| 532 | rtems_status_code rtems_semaphore_ident( |
---|
[ae10dbd] | 533 | rtems_name name, |
---|
| 534 | uint32_t node, |
---|
| 535 | rtems_id *id |
---|
[ae68ff0] | 536 | ); |
---|
| 537 | @end example |
---|
[61389eac] | 538 | @end ifset |
---|
| 539 | |
---|
| 540 | @ifset is-Ada |
---|
| 541 | @example |
---|
| 542 | procedure Semaphore_Ident ( |
---|
| 543 | Name : in RTEMS.Name; |
---|
| 544 | Node : in RTEMS.Unsigned32; |
---|
| 545 | ID : out RTEMS.ID; |
---|
| 546 | Result : out RTEMS.Status_Codes |
---|
| 547 | ); |
---|
| 548 | @end example |
---|
| 549 | @end ifset |
---|
[ae68ff0] | 550 | |
---|
| 551 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 552 | @code{@value{RPREFIX}SUCCESSFUL} - semaphore identified successfully@* |
---|
| 553 | @code{@value{RPREFIX}INVALID_NAME} - semaphore name not found@* |
---|
| 554 | @code{@value{RPREFIX}INVALID_NODE} - invalid node id |
---|
[ae68ff0] | 555 | |
---|
| 556 | @subheading DESCRIPTION: |
---|
| 557 | |
---|
| 558 | This directive obtains the semaphore id associated |
---|
| 559 | with the semaphore name. If the semaphore name is not unique, |
---|
| 560 | then the semaphore id will match one of the semaphores with that |
---|
| 561 | name. However, this semaphore id is not guaranteed to |
---|
| 562 | correspond to the desired semaphore. The semaphore id is used |
---|
| 563 | by other semaphore related directives to access the semaphore. |
---|
| 564 | |
---|
| 565 | @subheading NOTES: |
---|
| 566 | |
---|
| 567 | This directive will not cause the running task to be |
---|
| 568 | preempted. |
---|
| 569 | |
---|
[f331481c] | 570 | If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched |
---|
[ae68ff0] | 571 | with the local node being searched first. All other nodes are |
---|
| 572 | searched with the lowest numbered node searched first. |
---|
| 573 | |
---|
| 574 | If node is a valid node number which does not |
---|
| 575 | represent the local node, then only the semaphores exported by |
---|
| 576 | the designated node are searched. |
---|
| 577 | |
---|
| 578 | This directive does not generate activity on remote |
---|
| 579 | nodes. It accesses only the local copy of the global object |
---|
| 580 | table. |
---|
| 581 | |
---|
[169502e] | 582 | @c |
---|
| 583 | @c |
---|
| 584 | @c |
---|
[ae68ff0] | 585 | @page |
---|
| 586 | @subsection SEMAPHORE_DELETE - Delete a semaphore |
---|
| 587 | |
---|
[169502e] | 588 | @cindex delete a semaphore |
---|
| 589 | |
---|
[ae68ff0] | 590 | @subheading CALLING SEQUENCE: |
---|
| 591 | |
---|
[61389eac] | 592 | @ifset is-C |
---|
[169502e] | 593 | @findex rtems_semaphore_delete |
---|
[ae68ff0] | 594 | @example |
---|
| 595 | rtems_status_code rtems_semaphore_delete( |
---|
| 596 | rtems_id id |
---|
| 597 | ); |
---|
| 598 | @end example |
---|
[61389eac] | 599 | @end ifset |
---|
| 600 | |
---|
| 601 | @ifset is-Ada |
---|
| 602 | @example |
---|
| 603 | procedure Semaphore_Delete ( |
---|
| 604 | ID : in RTEMS.ID; |
---|
| 605 | Result : out RTEMS.Status_Codes |
---|
| 606 | ); |
---|
| 607 | @end example |
---|
| 608 | @end ifset |
---|
[ae68ff0] | 609 | |
---|
| 610 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 611 | @code{@value{RPREFIX}SUCCESSFUL} - semaphore deleted successfully@* |
---|
| 612 | @code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@* |
---|
| 613 | @code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@* |
---|
| 614 | @code{@value{RPREFIX}RESOURCE_IN_USE} - binary semaphore is in use |
---|
[ae68ff0] | 615 | |
---|
| 616 | @subheading DESCRIPTION: |
---|
| 617 | |
---|
[c85b8f2f] | 618 | This directive deletes the semaphore specified by @code{id}. |
---|
[ae68ff0] | 619 | All tasks blocked waiting to acquire the semaphore will be |
---|
| 620 | readied and returned a status code which indicates that the |
---|
| 621 | semaphore was deleted. The SMCB for this semaphore is reclaimed |
---|
| 622 | by RTEMS. |
---|
| 623 | |
---|
| 624 | @subheading NOTES: |
---|
| 625 | |
---|
| 626 | The calling task will be preempted if it is enabled |
---|
| 627 | by the task's execution mode and a higher priority local task is |
---|
| 628 | waiting on the deleted semaphore. The calling task will NOT be |
---|
| 629 | preempted if all of the tasks that are waiting on the semaphore |
---|
| 630 | are remote tasks. |
---|
| 631 | |
---|
| 632 | The calling task does not have to be the task that |
---|
| 633 | created the semaphore. Any local task that knows the semaphore |
---|
| 634 | id can delete the semaphore. |
---|
| 635 | |
---|
| 636 | When a global semaphore is deleted, the semaphore id |
---|
| 637 | must be transmitted to every node in the system for deletion |
---|
| 638 | from the local copy of the global object table. |
---|
| 639 | |
---|
| 640 | The semaphore must reside on the local node, even if |
---|
[75e22db] | 641 | the semaphore was created with the @code{@value{RPREFIX}GLOBAL} option. |
---|
[ae68ff0] | 642 | |
---|
| 643 | Proxies, used to represent remote tasks, are |
---|
| 644 | reclaimed when the semaphore is deleted. |
---|
| 645 | |
---|
[169502e] | 646 | @c |
---|
| 647 | @c |
---|
| 648 | @c |
---|
[ae68ff0] | 649 | @page |
---|
| 650 | @subsection SEMAPHORE_OBTAIN - Acquire a semaphore |
---|
| 651 | |
---|
[169502e] | 652 | @cindex obtain a semaphore |
---|
| 653 | @cindex lock a semaphore |
---|
| 654 | |
---|
[ae68ff0] | 655 | @subheading CALLING SEQUENCE: |
---|
| 656 | |
---|
[61389eac] | 657 | @ifset is-C |
---|
[169502e] | 658 | @findex rtems_semaphore_obtain |
---|
[ae68ff0] | 659 | @example |
---|
| 660 | rtems_status_code rtems_semaphore_obtain( |
---|
[ae10dbd] | 661 | rtems_id id, |
---|
[8ad2468c] | 662 | rtems_option option_set, |
---|
[ae10dbd] | 663 | rtems_interval timeout |
---|
[ae68ff0] | 664 | ); |
---|
| 665 | @end example |
---|
[61389eac] | 666 | @end ifset |
---|
| 667 | |
---|
| 668 | @ifset is-Ada |
---|
| 669 | @example |
---|
| 670 | procedure Semaphore_Obtain ( |
---|
| 671 | ID : in RTEMS.ID; |
---|
| 672 | Option_Set : in RTEMS.Option; |
---|
| 673 | Timeout : in RTEMS.Interval; |
---|
| 674 | Result : out RTEMS.Status_Codes |
---|
| 675 | ); |
---|
| 676 | @end example |
---|
| 677 | @end ifset |
---|
[ae68ff0] | 678 | |
---|
| 679 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 680 | @code{@value{RPREFIX}SUCCESSFUL} - semaphore obtained successfully@* |
---|
| 681 | @code{@value{RPREFIX}UNSATISFIED} - semaphore not available@* |
---|
| 682 | @code{@value{RPREFIX}TIMEOUT} - timed out waiting for semaphore@* |
---|
| 683 | @code{@value{RPREFIX}OBJECT_WAS_DELETED} - semaphore deleted while waiting@* |
---|
| 684 | @code{@value{RPREFIX}INVALID_ID} - invalid semaphore id |
---|
[ae68ff0] | 685 | |
---|
| 686 | @subheading DESCRIPTION: |
---|
| 687 | |
---|
| 688 | This directive acquires the semaphore specified by |
---|
[f331481c] | 689 | id. The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT} components of the options parameter |
---|
[ae68ff0] | 690 | indicate whether the calling task wants to wait for the |
---|
| 691 | semaphore to become available or return immediately if the |
---|
[f331481c] | 692 | semaphore is not currently available. With either @code{@value{RPREFIX}WAIT} or |
---|
| 693 | @code{@value{RPREFIX}NO_WAIT}, if the current semaphore count is positive, then it is |
---|
[ae68ff0] | 694 | decremented by one and the semaphore is successfully acquired by |
---|
| 695 | returning immediately with a successful return code. |
---|
| 696 | |
---|
[169502e] | 697 | If the calling task chooses to return immediately and the current |
---|
| 698 | semaphore count is zero or negative, then a status code is returned |
---|
| 699 | indicating that the semaphore is not available. If the calling task |
---|
| 700 | chooses to wait for a semaphore and the current semaphore count is zero or |
---|
| 701 | negative, then it is decremented by one and the calling task is placed on |
---|
| 702 | the semaphore's wait queue and blocked. If the semaphore was created with |
---|
| 703 | the @code{@value{RPREFIX}PRIORITY} attribute, then the calling task is |
---|
| 704 | inserted into the queue according to its priority. However, if the |
---|
| 705 | semaphore was created with the @code{@value{RPREFIX}FIFO} attribute, then |
---|
| 706 | the calling task is placed at the rear of the wait queue. If the binary |
---|
| 707 | semaphore was created with the @code{@value{RPREFIX}INHERIT_PRIORITY} |
---|
| 708 | attribute, then the priority of the task currently holding the binary |
---|
| 709 | semaphore is guaranteed to be greater than or equal to that of the |
---|
| 710 | blocking task. If the binary semaphore was created with the |
---|
| 711 | @code{@value{RPREFIX}PRIORITY_CEILING} attribute, a task successfully |
---|
| 712 | obtains the semaphore, and the priority of that task is greater than the |
---|
| 713 | ceiling priority for this semaphore, then the priority of the task |
---|
| 714 | obtaining the semaphore is elevated to that of the ceiling. |
---|
| 715 | |
---|
| 716 | The timeout parameter specifies the maximum interval the calling task is |
---|
| 717 | willing to be blocked waiting for the semaphore. If it is set to |
---|
| 718 | @code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever. |
---|
| 719 | If the semaphore is available or the @code{@value{RPREFIX}NO_WAIT} option |
---|
| 720 | component is set, then timeout is ignored. |
---|
[ae68ff0] | 721 | |
---|
| 722 | @subheading NOTES: |
---|
| 723 | The following semaphore acquisition option constants |
---|
| 724 | are defined by RTEMS: |
---|
| 725 | |
---|
| 726 | @itemize @bullet |
---|
[f331481c] | 727 | @item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default) |
---|
| 728 | @item @code{@value{RPREFIX}NO_WAIT} - task should not wait |
---|
[ae68ff0] | 729 | @end itemize |
---|
| 730 | |
---|
[169502e] | 731 | Attempting to obtain a global semaphore which does not reside on the local |
---|
| 732 | node will generate a request to the remote node to access the semaphore. |
---|
| 733 | If the semaphore is not available and @code{@value{RPREFIX}NO_WAIT} was |
---|
| 734 | not specified, then the task must be blocked until the semaphore is |
---|
| 735 | released. A proxy is allocated on the remote node to represent the task |
---|
| 736 | until the semaphore is released. |
---|
[ae68ff0] | 737 | |
---|
[1ca951ce] | 738 | A clock tick is required to support the timeout functionality of |
---|
| 739 | this directive. |
---|
| 740 | |
---|
[169502e] | 741 | @c |
---|
| 742 | @c |
---|
| 743 | @c |
---|
[ae68ff0] | 744 | @page |
---|
| 745 | @subsection SEMAPHORE_RELEASE - Release a semaphore |
---|
| 746 | |
---|
[169502e] | 747 | @cindex release a semaphore |
---|
| 748 | @cindex unlock a semaphore |
---|
| 749 | |
---|
[ae68ff0] | 750 | @subheading CALLING SEQUENCE: |
---|
| 751 | |
---|
[61389eac] | 752 | @ifset is-C |
---|
[169502e] | 753 | @findex rtems_semaphore_release |
---|
[ae68ff0] | 754 | @example |
---|
| 755 | rtems_status_code rtems_semaphore_release( |
---|
| 756 | rtems_id id |
---|
| 757 | ); |
---|
| 758 | @end example |
---|
[61389eac] | 759 | @end ifset |
---|
| 760 | |
---|
| 761 | @ifset is-Ada |
---|
| 762 | @example |
---|
| 763 | procedure Semaphore_Release ( |
---|
| 764 | ID : in RTEMS.ID; |
---|
| 765 | Result : out RTEMS.Status_Codes |
---|
| 766 | ); |
---|
| 767 | @end example |
---|
| 768 | @end ifset |
---|
[ae68ff0] | 769 | |
---|
| 770 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 771 | @code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@* |
---|
| 772 | @code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@* |
---|
| 773 | @code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore |
---|
[ae68ff0] | 774 | |
---|
| 775 | @subheading DESCRIPTION: |
---|
| 776 | |
---|
| 777 | This directive releases the semaphore specified by |
---|
| 778 | id. The semaphore count is incremented by one. If the count is |
---|
| 779 | zero or negative, then the first task on this semaphore's wait |
---|
| 780 | queue is removed and unblocked. The unblocked task may preempt |
---|
| 781 | the running task if the running task's preemption mode is |
---|
| 782 | enabled and the unblocked task has a higher priority than the |
---|
| 783 | running task. |
---|
| 784 | |
---|
| 785 | @subheading NOTES: |
---|
| 786 | |
---|
| 787 | The calling task may be preempted if it causes a |
---|
| 788 | higher priority task to be made ready for execution. |
---|
| 789 | |
---|
| 790 | Releasing a global semaphore which does not reside on |
---|
| 791 | the local node will generate a request telling the remote node |
---|
| 792 | to release the semaphore. |
---|
| 793 | |
---|
| 794 | If the task to be unblocked resides on a different |
---|
| 795 | node from the semaphore, then the semaphore allocation is |
---|
| 796 | forwarded to the appropriate node, the waiting task is |
---|
| 797 | unblocked, and the proxy used to represent the task is reclaimed. |
---|
| 798 | |
---|
| 799 | The outermost release of a local, binary, priority |
---|
| 800 | inheritance or priority ceiling semaphore may result in the |
---|
| 801 | calling task having its priority lowered. This will occur if |
---|
| 802 | the calling task holds no other binary semaphores and it has |
---|
| 803 | inherited a higher priority. |
---|
| 804 | |
---|
[5a69fe3] | 805 | @c |
---|
| 806 | @c |
---|
| 807 | @c |
---|
| 808 | @page |
---|
| 809 | @subsection SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore |
---|
| 810 | |
---|
| 811 | @cindex flush a semaphore |
---|
[6449498] | 812 | @cindex unblock all tasks waiting on a semaphore |
---|
[5a69fe3] | 813 | |
---|
| 814 | @subheading CALLING SEQUENCE: |
---|
| 815 | |
---|
| 816 | @ifset is-C |
---|
| 817 | @findex rtems_semaphore_flush |
---|
| 818 | @example |
---|
| 819 | rtems_status_code rtems_semaphore_flush( |
---|
| 820 | rtems_id id |
---|
| 821 | ); |
---|
| 822 | @end example |
---|
| 823 | @end ifset |
---|
| 824 | |
---|
| 825 | @ifset is-Ada |
---|
| 826 | @example |
---|
| 827 | procedure Semaphore_Flush ( |
---|
| 828 | ID : in RTEMS.ID; |
---|
| 829 | Result : out RTEMS.Status_Codes |
---|
| 830 | ); |
---|
| 831 | @end example |
---|
| 832 | @end ifset |
---|
| 833 | |
---|
| 834 | @subheading DIRECTIVE STATUS CODES: |
---|
| 835 | @code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@* |
---|
| 836 | @code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@* |
---|
| 837 | @code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores |
---|
| 838 | |
---|
| 839 | @subheading DESCRIPTION: |
---|
| 840 | |
---|
| 841 | This directive unblocks all tasks waiting on the semaphore specified by |
---|
| 842 | id. Since there are tasks blocked on the semaphore, the semaphore's |
---|
| 843 | count is not changed by this directive and thus is zero before and |
---|
| 844 | after this directive is executed. Tasks which are unblocked as the |
---|
| 845 | result of this directive will return from the |
---|
[8ad2468c] | 846 | @code{@value{DIRPREFIX}semaphore_obtain} directive with a |
---|
[5a69fe3] | 847 | status code of @code{@value{RPREFIX}UNSATISFIED} to indicate |
---|
| 848 | that the semaphore was not obtained. |
---|
| 849 | |
---|
| 850 | This directive may unblock any number of tasks. Any of the unblocked |
---|
| 851 | tasks may preempt the running task if the running task's preemption mode is |
---|
| 852 | enabled and an unblocked task has a higher priority than the |
---|
| 853 | running task. |
---|
| 854 | |
---|
| 855 | @subheading NOTES: |
---|
| 856 | |
---|
| 857 | The calling task may be preempted if it causes a |
---|
| 858 | higher priority task to be made ready for execution. |
---|
| 859 | |
---|
| 860 | If the task to be unblocked resides on a different |
---|
| 861 | node from the semaphore, then the waiting task is |
---|
| 862 | unblocked, and the proxy used to represent the task is reclaimed. |
---|
| 863 | |
---|
| 864 | |
---|