[489740f] | 1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
| 2 | |
---|
[8ef6ea8] | 3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
| 4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
| 5 | .. COMMENT: All rights reserved. |
---|
| 6 | |
---|
[6c56401] | 7 | .. index:: partitions |
---|
| 8 | |
---|
[fd6dc8c8] | 9 | Partition Manager |
---|
[4da4a15] | 10 | ***************** |
---|
[fd6dc8c8] | 11 | |
---|
| 12 | Introduction |
---|
| 13 | ============ |
---|
| 14 | |
---|
[8ef6ea8] | 15 | The partition manager provides facilities to dynamically allocate memory in |
---|
| 16 | fixed-size units. The directives provided by the partition manager are: |
---|
[fd6dc8c8] | 17 | |
---|
[8ef6ea8] | 18 | - rtems_partition_create_ - Create a partition |
---|
[fd6dc8c8] | 19 | |
---|
[8ef6ea8] | 20 | - rtems_partition_ident_ - Get ID of a partition |
---|
[fd6dc8c8] | 21 | |
---|
[8ef6ea8] | 22 | - rtems_partition_delete_ - Delete a partition |
---|
[fd6dc8c8] | 23 | |
---|
[8ef6ea8] | 24 | - rtems_partition_get_buffer_ - Get buffer from a partition |
---|
[fd6dc8c8] | 25 | |
---|
[8ef6ea8] | 26 | - rtems_partition_return_buffer_ - Return buffer to a partition |
---|
[fd6dc8c8] | 27 | |
---|
| 28 | Background |
---|
| 29 | ========== |
---|
| 30 | |
---|
[6c56401] | 31 | .. index:: partition, definition |
---|
| 32 | |
---|
[fd6dc8c8] | 33 | Partition Manager Definitions |
---|
| 34 | ----------------------------- |
---|
| 35 | |
---|
[8ef6ea8] | 36 | A partition is a physically contiguous memory area divided into fixed-size |
---|
| 37 | buffers that can be dynamically allocated and deallocated. |
---|
[fd6dc8c8] | 38 | |
---|
[8ef6ea8] | 39 | .. index:: buffers, definition |
---|
| 40 | |
---|
| 41 | Partitions are managed and maintained as a list of buffers. Buffers are |
---|
| 42 | obtained from the front of the partition's free buffer chain and returned to |
---|
| 43 | the rear of the same chain. When a buffer is on the free buffer chain, RTEMS |
---|
| 44 | uses two pointers of memory from each buffer as the free buffer chain. When a |
---|
| 45 | buffer is allocated, the entire buffer is available for application use. |
---|
| 46 | Therefore, modifying memory that is outside of an allocated buffer could |
---|
| 47 | destroy the free buffer chain or the contents of an adjacent allocated buffer. |
---|
[fd6dc8c8] | 48 | |
---|
[6c56401] | 49 | .. index:: partition attribute set, building |
---|
| 50 | |
---|
[fd6dc8c8] | 51 | Building a Partition Attribute Set |
---|
| 52 | ---------------------------------- |
---|
| 53 | |
---|
[8ef6ea8] | 54 | In general, an attribute set is built by a bitwise OR of the desired attribute |
---|
| 55 | components. The set of valid partition attributes is provided in the following |
---|
| 56 | table: |
---|
[fd6dc8c8] | 57 | |
---|
[8ef6ea8] | 58 | .. list-table:: |
---|
| 59 | :class: rtems-table |
---|
[fd6dc8c8] | 60 | |
---|
[8ef6ea8] | 61 | * - ``RTEMS_LOCAL`` |
---|
| 62 | - local partition (default) |
---|
| 63 | * - ``RTEMS_GLOBAL`` |
---|
| 64 | - global partition |
---|
[fd6dc8c8] | 65 | |
---|
[8ef6ea8] | 66 | Attribute values are specifically designed to be mutually exclusive, therefore |
---|
| 67 | bitwise OR and addition operations are equivalent as long as each attribute |
---|
| 68 | appears exactly once in the component list. An attribute listed as a default |
---|
| 69 | is not required to appear in the attribute list, although it is a good |
---|
| 70 | programming practice to specify default attributes. If all defaults are |
---|
| 71 | desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this |
---|
| 72 | call. The attribute_set parameter should be ``RTEMS_GLOBAL`` to indicate that |
---|
| 73 | the partition is to be known globally. |
---|
[fd6dc8c8] | 74 | |
---|
| 75 | Operations |
---|
| 76 | ========== |
---|
| 77 | |
---|
| 78 | Creating a Partition |
---|
| 79 | -------------------- |
---|
| 80 | |
---|
[8ef6ea8] | 81 | The ``rtems_partition_create`` directive creates a partition with a |
---|
| 82 | user-specified name. The partition's name, starting address, length and buffer |
---|
| 83 | size are all specified to the ``rtems_partition_create`` directive. RTEMS |
---|
| 84 | allocates a Partition Control Block (PTCB) from the PTCB free list. This data |
---|
| 85 | structure is used by RTEMS to manage the newly created partition. The number |
---|
| 86 | of buffers in the partition is calculated based upon the specified partition |
---|
| 87 | length and buffer size. If successful,the unique partition ID is returned to |
---|
| 88 | the calling task. |
---|
[fd6dc8c8] | 89 | |
---|
| 90 | Obtaining Partition IDs |
---|
| 91 | ----------------------- |
---|
| 92 | |
---|
[8ef6ea8] | 93 | When a partition is created, RTEMS generates a unique partition ID and assigned |
---|
| 94 | it to the created partition until it is deleted. The partition ID may be |
---|
| 95 | obtained by either of two methods. First, as the result of an invocation of |
---|
| 96 | the ``rtems_partition_create`` directive, the partition ID is stored in a user |
---|
| 97 | provided location. Second, the partition ID may be obtained later using the |
---|
| 98 | ``rtems_partition_ident`` directive. The partition ID is used by other |
---|
| 99 | partition manager directives to access this partition. |
---|
[fd6dc8c8] | 100 | |
---|
| 101 | Acquiring a Buffer |
---|
| 102 | ------------------ |
---|
| 103 | |
---|
[8ef6ea8] | 104 | A buffer can be obtained by calling the ``rtems_partition_get_buffer`` |
---|
| 105 | directive. If a buffer is available, then it is returned immediately with a |
---|
| 106 | successful return code. Otherwise, an unsuccessful return code is returned |
---|
| 107 | immediately to the caller. Tasks cannot block to wait for a buffer to become |
---|
| 108 | available. |
---|
[fd6dc8c8] | 109 | |
---|
| 110 | Releasing a Buffer |
---|
| 111 | ------------------ |
---|
| 112 | |
---|
[8ef6ea8] | 113 | Buffers are returned to a partition's free buffer chain with the |
---|
| 114 | ``rtems_partition_return_buffer`` directive. This directive returns an error |
---|
| 115 | status code if the returned buffer was not previously allocated from this |
---|
| 116 | partition. |
---|
[fd6dc8c8] | 117 | |
---|
| 118 | Deleting a Partition |
---|
| 119 | -------------------- |
---|
| 120 | |
---|
[8ef6ea8] | 121 | The ``rtems_partition_delete`` directive allows a partition to be removed and |
---|
| 122 | returned to RTEMS. When a partition is deleted, the PTCB for that partition is |
---|
| 123 | returned to the PTCB free list. A partition with buffers still allocated |
---|
| 124 | cannot be deleted. Any task attempting to do so will be returned an error |
---|
| 125 | status code. |
---|
[fd6dc8c8] | 126 | |
---|
| 127 | Directives |
---|
| 128 | ========== |
---|
| 129 | |
---|
[8ef6ea8] | 130 | This section details the partition manager's directives. A subsection is |
---|
| 131 | dedicated to each of this manager's directives and describes the calling |
---|
| 132 | sequence, related constants, usage, and status codes. |
---|
| 133 | |
---|
[53bb72e] | 134 | .. raw:: latex |
---|
| 135 | |
---|
| 136 | \clearpage |
---|
| 137 | |
---|
[6c56401] | 138 | .. index:: create a partition |
---|
| 139 | .. index:: rtems_partition_create |
---|
[fd6dc8c8] | 140 | |
---|
[3384994] | 141 | .. _rtems_partition_create: |
---|
| 142 | |
---|
[fd6dc8c8] | 143 | PARTITION_CREATE - Create a partition |
---|
| 144 | ------------------------------------- |
---|
| 145 | |
---|
[53bb72e] | 146 | CALLING SEQUENCE: |
---|
| 147 | .. code-block:: c |
---|
| 148 | |
---|
| 149 | rtems_status_code rtems_partition_create( |
---|
| 150 | rtems_name name, |
---|
| 151 | void *starting_address, |
---|
| 152 | uint32_t length, |
---|
| 153 | uint32_t buffer_size, |
---|
| 154 | rtems_attribute attribute_set, |
---|
| 155 | rtems_id *id |
---|
| 156 | ); |
---|
| 157 | |
---|
| 158 | DIRECTIVE STATUS CODES: |
---|
| 159 | .. list-table:: |
---|
| 160 | :class: rtems-table |
---|
| 161 | |
---|
| 162 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 163 | - partition created successfully |
---|
| 164 | * - ``RTEMS_INVALID_NAME`` |
---|
| 165 | - invalid partition name |
---|
| 166 | * - ``RTEMS_TOO_MANY`` |
---|
| 167 | - too many partitions created |
---|
| 168 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 169 | - address not on four byte boundary |
---|
| 170 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 171 | - ``starting_address`` is NULL |
---|
| 172 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 173 | - ``id`` is NULL |
---|
| 174 | * - ``RTEMS_INVALID_SIZE`` |
---|
| 175 | - length or buffer size is 0 |
---|
| 176 | * - ``RTEMS_INVALID_SIZE`` |
---|
| 177 | - length is less than the buffer size |
---|
| 178 | * - ``RTEMS_INVALID_SIZE`` |
---|
| 179 | - buffer size not a multiple of 4 |
---|
| 180 | * - ``RTEMS_MP_NOT_CONFIGURED`` |
---|
| 181 | - multiprocessing not configured |
---|
| 182 | * - ``RTEMS_TOO_MANY`` |
---|
| 183 | - too many global objects |
---|
| 184 | |
---|
| 185 | DESCRIPTION: |
---|
| 186 | This directive creates a partition of fixed size buffers from a physically |
---|
| 187 | contiguous memory space which starts at starting_address and is length |
---|
| 188 | bytes in size. Each allocated buffer is to be of ``buffer_size`` in bytes. |
---|
| 189 | The assigned partition id is returned in ``id``. This partition id is used |
---|
| 190 | to access the partition with other partition related directives. For |
---|
| 191 | control and maintenance of the partition, RTEMS allocates a PTCB from the |
---|
| 192 | local PTCB free pool and initializes it. |
---|
| 193 | |
---|
| 194 | NOTES: |
---|
| 195 | This directive will not cause the calling task to be preempted. |
---|
| 196 | |
---|
| 197 | The ``starting_address`` must be properly aligned for the target |
---|
| 198 | architecture. |
---|
| 199 | |
---|
| 200 | The ``buffer_size`` parameter must be a multiple of the CPU alignment |
---|
| 201 | factor. Additionally, ``buffer_size`` must be large enough to hold two |
---|
| 202 | pointers on the target architecture. This is required for RTEMS to manage |
---|
| 203 | the buffers when they are free. |
---|
| 204 | |
---|
| 205 | Memory from the partition is not used by RTEMS to store the Partition |
---|
| 206 | Control Block. |
---|
| 207 | |
---|
| 208 | The following partition attribute constants are defined by RTEMS: |
---|
| 209 | |
---|
| 210 | .. list-table:: |
---|
| 211 | :class: rtems-table |
---|
| 212 | |
---|
| 213 | * - ``RTEMS_LOCAL`` |
---|
| 214 | - local partition (default) |
---|
| 215 | * - ``RTEMS_GLOBAL`` |
---|
| 216 | - global partition |
---|
| 217 | |
---|
| 218 | The PTCB for a global partition is allocated on the local node. The memory |
---|
| 219 | space used for the partition must reside in shared memory. Partitions |
---|
| 220 | should not be made global unless remote tasks must interact with the |
---|
| 221 | partition. This is to avoid the overhead incurred by the creation of a |
---|
| 222 | global partition. When a global partition is created, the partition's name |
---|
| 223 | and id must be transmitted to every node in the system for insertion in the |
---|
| 224 | local copy of the global object table. |
---|
| 225 | |
---|
| 226 | The total number of global objects, including partitions, is limited by the |
---|
| 227 | maximum_global_objects field in the Configuration Table. |
---|
| 228 | |
---|
| 229 | .. raw:: latex |
---|
| 230 | |
---|
| 231 | \clearpage |
---|
[8ef6ea8] | 232 | |
---|
[fd6dc8c8] | 233 | .. index:: get ID of a partition |
---|
| 234 | .. index:: obtain ID of a partition |
---|
| 235 | .. index:: rtems_partition_ident |
---|
| 236 | |
---|
[3384994] | 237 | .. _rtems_partition_ident: |
---|
| 238 | |
---|
[6c56401] | 239 | PARTITION_IDENT - Get ID of a partition |
---|
| 240 | --------------------------------------- |
---|
| 241 | |
---|
[53bb72e] | 242 | CALLING SEQUENCE: |
---|
| 243 | .. code-block:: c |
---|
[fd6dc8c8] | 244 | |
---|
[53bb72e] | 245 | rtems_status_code rtems_partition_ident( |
---|
| 246 | rtems_name name, |
---|
| 247 | uint32_t node, |
---|
| 248 | rtems_id *id |
---|
| 249 | ); |
---|
[fd6dc8c8] | 250 | |
---|
[53bb72e] | 251 | DIRECTIVE STATUS CODES: |
---|
| 252 | .. list-table:: |
---|
| 253 | :class: rtems-table |
---|
[8ef6ea8] | 254 | |
---|
[53bb72e] | 255 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 256 | - partition identified successfully |
---|
| 257 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 258 | - ``id`` is NULL |
---|
| 259 | * - ``RTEMS_INVALID_NAME`` |
---|
| 260 | - partition name not found |
---|
| 261 | * - ``RTEMS_INVALID_NODE`` |
---|
| 262 | - invalid node id |
---|
[fd6dc8c8] | 263 | |
---|
[53bb72e] | 264 | DESCRIPTION: |
---|
| 265 | This directive obtains the partition id associated with the partition name. |
---|
| 266 | If the partition name is not unique, then the partition id will match one |
---|
| 267 | of the partitions with that name. However, this partition id is not |
---|
| 268 | guaranteed to correspond to the desired partition. The partition id is |
---|
| 269 | used with other partition related directives to access the partition. |
---|
[fd6dc8c8] | 270 | |
---|
[53bb72e] | 271 | NOTES: |
---|
| 272 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 273 | |
---|
[53bb72e] | 274 | If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the |
---|
| 275 | local node being searched first. All other nodes are searched with the |
---|
| 276 | lowest numbered node searched first. |
---|
[fd6dc8c8] | 277 | |
---|
[53bb72e] | 278 | If node is a valid node number which does not represent the local node, |
---|
| 279 | then only the partitions exported by the designated node are searched. |
---|
[fd6dc8c8] | 280 | |
---|
[53bb72e] | 281 | This directive does not generate activity on remote nodes. It accesses |
---|
| 282 | only the local copy of the global object table. |
---|
[fd6dc8c8] | 283 | |
---|
[53bb72e] | 284 | .. raw:: latex |
---|
[fd6dc8c8] | 285 | |
---|
[53bb72e] | 286 | \clearpage |
---|
[8ef6ea8] | 287 | |
---|
[6c56401] | 288 | .. index:: delete a partition |
---|
| 289 | .. index:: rtems_partition_delete |
---|
[fd6dc8c8] | 290 | |
---|
[3384994] | 291 | .. _rtems_partition_delete: |
---|
| 292 | |
---|
[fd6dc8c8] | 293 | PARTITION_DELETE - Delete a partition |
---|
| 294 | ------------------------------------- |
---|
| 295 | |
---|
[53bb72e] | 296 | CALLING SEQUENCE: |
---|
| 297 | .. code-block:: c |
---|
[fd6dc8c8] | 298 | |
---|
[53bb72e] | 299 | rtems_status_code rtems_partition_delete( |
---|
| 300 | rtems_id id |
---|
| 301 | ); |
---|
[fd6dc8c8] | 302 | |
---|
[53bb72e] | 303 | DIRECTIVE STATUS CODES: |
---|
| 304 | .. list-table:: |
---|
| 305 | :class: rtems-table |
---|
[fd6dc8c8] | 306 | |
---|
[53bb72e] | 307 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 308 | - partition deleted successfully |
---|
| 309 | * - ``RTEMS_INVALID_ID`` |
---|
| 310 | - invalid partition id |
---|
| 311 | * - ``RTEMS_RESOURCE_IN_USE`` |
---|
| 312 | - buffers still in use |
---|
| 313 | * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` |
---|
| 314 | - cannot delete remote partition |
---|
[fd6dc8c8] | 315 | |
---|
[53bb72e] | 316 | DESCRIPTION: |
---|
| 317 | This directive deletes the partition specified by id. The partition cannot |
---|
| 318 | be deleted if any of its buffers are still allocated. The PTCB for the |
---|
| 319 | deleted partition is reclaimed by RTEMS. |
---|
[fd6dc8c8] | 320 | |
---|
[53bb72e] | 321 | NOTES: |
---|
| 322 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 323 | |
---|
[53bb72e] | 324 | The calling task does not have to be the task that created the partition. |
---|
| 325 | Any local task that knows the partition id can delete the partition. |
---|
[fd6dc8c8] | 326 | |
---|
[53bb72e] | 327 | When a global partition is deleted, the partition id must be transmitted to |
---|
| 328 | every node in the system for deletion from the local copy of the global |
---|
| 329 | object table. |
---|
[fd6dc8c8] | 330 | |
---|
[53bb72e] | 331 | The partition must reside on the local node, even if the partition was |
---|
| 332 | created with the ``RTEMS_GLOBAL`` option. |
---|
[fd6dc8c8] | 333 | |
---|
[53bb72e] | 334 | .. raw:: latex |
---|
[8ef6ea8] | 335 | |
---|
[53bb72e] | 336 | \clearpage |
---|
[fd6dc8c8] | 337 | |
---|
| 338 | .. index:: get buffer from partition |
---|
| 339 | .. index:: obtain buffer from partition |
---|
| 340 | .. index:: rtems_partition_get_buffer |
---|
| 341 | |
---|
[3384994] | 342 | .. _rtems_partition_get_buffer: |
---|
| 343 | |
---|
[6c56401] | 344 | PARTITION_GET_BUFFER - Get buffer from a partition |
---|
| 345 | -------------------------------------------------- |
---|
| 346 | |
---|
[53bb72e] | 347 | CALLING SEQUENCE: |
---|
| 348 | .. code-block:: c |
---|
[fd6dc8c8] | 349 | |
---|
[53bb72e] | 350 | rtems_status_code rtems_partition_get_buffer( |
---|
| 351 | rtems_id id, |
---|
| 352 | void **buffer |
---|
| 353 | ); |
---|
[fd6dc8c8] | 354 | |
---|
[53bb72e] | 355 | DIRECTIVE STATUS CODES: |
---|
| 356 | .. list-table:: |
---|
| 357 | :class: rtems-table |
---|
[fd6dc8c8] | 358 | |
---|
[53bb72e] | 359 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 360 | - buffer obtained successfully |
---|
| 361 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 362 | - ``buffer`` is NULL |
---|
| 363 | * - ``RTEMS_INVALID_ID`` |
---|
| 364 | - invalid partition id |
---|
| 365 | * - ``RTEMS_UNSATISFIED`` |
---|
| 366 | - all buffers are allocated |
---|
[fd6dc8c8] | 367 | |
---|
[53bb72e] | 368 | DESCRIPTION: |
---|
| 369 | This directive allows a buffer to be obtained from the partition specified |
---|
| 370 | in id. The address of the allocated buffer is returned in buffer. |
---|
[fd6dc8c8] | 371 | |
---|
[53bb72e] | 372 | NOTES: |
---|
| 373 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 374 | |
---|
[53bb72e] | 375 | All buffers begin on a four byte boundary. |
---|
[fd6dc8c8] | 376 | |
---|
[53bb72e] | 377 | A task cannot wait on a buffer to become available. |
---|
[fd6dc8c8] | 378 | |
---|
[53bb72e] | 379 | Getting a buffer from a global partition which does not reside on the local |
---|
| 380 | node will generate a request telling the remote node to allocate a buffer |
---|
| 381 | from the specified partition. |
---|
[fd6dc8c8] | 382 | |
---|
[53bb72e] | 383 | .. raw:: latex |
---|
[fd6dc8c8] | 384 | |
---|
[53bb72e] | 385 | \clearpage |
---|
[8ef6ea8] | 386 | |
---|
[6c56401] | 387 | .. index:: return buffer to partitition |
---|
| 388 | .. index:: rtems_partition_return_buffer |
---|
[fd6dc8c8] | 389 | |
---|
[3384994] | 390 | .. _rtems_partition_return_buffer: |
---|
| 391 | |
---|
[fd6dc8c8] | 392 | PARTITION_RETURN_BUFFER - Return buffer to a partition |
---|
| 393 | ------------------------------------------------------ |
---|
| 394 | |
---|
[53bb72e] | 395 | CALLING SEQUENCE: |
---|
| 396 | .. code-block:: c |
---|
[8ef6ea8] | 397 | |
---|
[53bb72e] | 398 | rtems_status_code rtems_partition_return_buffer( |
---|
| 399 | rtems_id id, |
---|
| 400 | void *buffer |
---|
| 401 | ); |
---|
[fd6dc8c8] | 402 | |
---|
[53bb72e] | 403 | DIRECTIVE STATUS CODES: |
---|
| 404 | .. list-table:: |
---|
| 405 | :class: rtems-table |
---|
[fd6dc8c8] | 406 | |
---|
[53bb72e] | 407 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 408 | - buffer returned successfully |
---|
| 409 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 410 | - ``buffer`` is NULL |
---|
| 411 | * - ``RTEMS_INVALID_ID`` |
---|
| 412 | - invalid partition id |
---|
| 413 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 414 | - buffer address not in partition |
---|
[fd6dc8c8] | 415 | |
---|
[53bb72e] | 416 | DESCRIPTION: |
---|
| 417 | This directive returns the buffer specified by buffer to the partition |
---|
| 418 | specified by id. |
---|
[fd6dc8c8] | 419 | |
---|
[53bb72e] | 420 | NOTES: |
---|
| 421 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 422 | |
---|
[53bb72e] | 423 | Returning a buffer to a global partition which does not reside on the local |
---|
| 424 | node will generate a request telling the remote node to return the buffer |
---|
| 425 | to the specified partition. |
---|
[fd6dc8c8] | 426 | |
---|
[53bb72e] | 427 | Returning a buffer multiple times is an error. It will corrupt the |
---|
| 428 | internal state of the partition. |
---|