From 74a75d8acc0da0eb6a7d7970c4b77b9c318a86ac Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 30 Sep 2020 15:20:34 +0200 Subject: spec: Review Partition Manager --- spec/rtems/part/if/alignment.yml | 23 ++++++++ spec/rtems/part/if/create.yml | 111 +++++++++++++++++++++++++++++++---- spec/rtems/part/if/delete.yml | 42 +++++++++++-- spec/rtems/part/if/get-buffer.yml | 45 +++++++++++--- spec/rtems/part/if/ident.yml | 4 +- spec/rtems/part/if/return-buffer.yml | 36 +++++++++--- spec/score/cpu/if/sizeof-pointer.yml | 12 ++++ 7 files changed, 240 insertions(+), 33 deletions(-) create mode 100644 spec/rtems/part/if/alignment.yml create mode 100644 spec/score/cpu/if/sizeof-pointer.yml diff --git a/spec/rtems/part/if/alignment.yml b/spec/rtems/part/if/alignment.yml new file mode 100644 index 00000000..35ce39a4 --- /dev/null +++ b/spec/rtems/part/if/alignment.yml @@ -0,0 +1,23 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + This constant defines the minimum alignment of a partition buffer in + bytes. +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +definition: + default: ${/score/cpu/if/sizeof-pointer:/name} + variants: [] +description: null +enabled-by: true +index-entries: [] +interface-type: define +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: RTEMS_PARTITION_ALIGNMENT +notes: | + Use it with ${../../basedefs/if/aligned:/name} to define the alignment of + partition buffer types or statically allocated partition buffer areas. +type: interface diff --git a/spec/rtems/part/if/create.yml b/spec/rtems/part/if/create.yml index e182b78c..a1502946 100644 --- a/spec/rtems/part/if/create.yml +++ b/spec/rtems/part/if/create.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Creates a partition. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -15,9 +16,31 @@ definition: - ${../../type/if/id:/name} *${.:/params[5]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive creates a partition of fixed size buffers from a physically + contiguous memory space which starts at ``${.:/params[1]/name}`` and is + ``${.:/params[2]/name}`` bytes in size. Each allocated buffer is to be of + ``${.:/params[3]/name}`` in bytes. The assigned partition identifier is + returned in ``${.:/params[5]/name}``. This partition identifier is used to + access the partition with other partition related directives. + + The attribute set is built through a *bitwise or* of the attribute constants + described below. Attributes not mentioned below are not evaluated by this + directive and have no effect. + + The partition can have **local** or **global** scope in a multiprocessing + network (this attribute does not refer to SMP systems). + + * A **local** is the default and can be emphasized through the use of the + ${../../attr/if/local:/name} attribute. A local partition can be only used + by the node which created it. + + * A **global** is created if the ${../../attr/if/global:/name} attribute is + set. The memory space used for the partition must reside in shared memory. + Setting the global attribute in a single node system has no effect. enabled-by: true -index-entries: [] +index-entries: +- create a partition interface-type: function links: - role: interface-placement @@ -25,27 +48,93 @@ links: - role: interface-ingroup uid: group name: rtems_partition_create -notes: null +notes: | + This directive may cause the calling task to be preempted due to an obtain + and release of the object allocator mutex. + + The partition buffer area specified by the ``${.:/params[1]/name}`` must be + properly aligned. It must be possible to directly store target architecture + pointers and also the user data. For example, if the user data contains some + long double or vector data types, the partition buffer area and the buffer + size must take the alignment of these types into account which is usually + larger than the pointer alignment. A cache line alignment may be also a + factor. Use ${alignment:/name} to specify the minimum alignment of a + partition buffer type. + + The ``${.:/params[3]/name}`` parameter must be an integral multiple of the + pointer size on the target architecture. Additionally, + ``${.:/params[3]/name}`` must be large enough to hold two pointers on the + target architecture. This is required for RTEMS to manage the buffers when + they are free. + + For control and maintenance of the partition, RTEMS allocates a + ${/glossary/ptcb:/term} from the local PTCB free pool and initializes it. + Memory from the partition buffer area is not used by RTEMS to store the PTCB. + + The PTCB for a global partition is allocated on the local node. Partitions + should not be made global unless remote tasks must interact with the + partition. This is to avoid the overhead incurred by the creation of a + global partition. When a global partition is created, the partition'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 partitions, is limited by the + value of the ${/acfg/if/mp-max-global-objects:/name} application + configuration option. params: -- description: '%' +- description: is the name of the partition. dir: null name: name -- description: '%' +- description: is the starting address of the buffer area used by the partition. dir: null name: starting_address -- description: '%' +- description: is the length in bytes of the buffer area used by the partition. dir: null name: length -- description: '%' +- description: is the size in bytes of a buffer managed by the partition. dir: null name: buffer_size -- description: '%' +- description: is the attribute set of the partition. dir: null name: attribute_set -- description: '%' +- description: | + is the pointer to an object identifier variable. The identifier of the + created partition object will be stored in this variable, in case of a + successful operation. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The partition name was invalid. + value: ${../../status/if/invalid-name:/name} + - description: | + The ``${.:/params[5]/name}`` parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + The ``${.:/params[2]/name}`` parameter was 0. + value: ${../../status/if/invalid-size:/name} + - description: | + The ``${.:/params[3]/name}`` parameter was 0. + value: ${../../status/if/invalid-size:/name} + - description: | + The ``${.:/params[2]/name}`` parameter was less than the + ``${.:/params[3]/name}`` parameter. + value: ${../../status/if/invalid-size:/name} + - description: | + The ``${.:/params[3]/name}`` parameter was not an integral multiple of + the pointer size. + value: ${../../status/if/invalid-size:/name} + - description: | + The ``${.:/params[3]/name}`` parameter was less than two times the + pointer size. + value: ${../../status/if/invalid-size:/name} + - description: | + The ``${.:/params[1]/name}`` parameter was not on a pointer size + boundary. + value: ${../../status/if/invalid-address:/name} type: interface diff --git a/spec/rtems/part/if/delete.yml b/spec/rtems/part/if/delete.yml index 598b020b..4c87a44b 100644 --- a/spec/rtems/part/if/delete.yml +++ b/spec/rtems/part/if/delete.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the specified partition. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -10,9 +11,14 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive deletes the partition specified by the ${.:/params[0]/name} + parameter. The partition cannot be deleted if any of its buffers are still + allocated. The ${/glossary/ptcb:/term} for the deleted partition is + reclaimed by RTEMS. enabled-by: true -index-entries: [] +index-entries: +- delete a partition interface-type: function links: - role: interface-placement @@ -20,12 +26,36 @@ links: - role: interface-ingroup uid: group name: rtems_partition_delete -notes: null +notes: | + This directive may cause the calling task to be preempted due to an obtain + and release of the object allocator mutex. + + The calling task does not have to be the task that created the partition. + Any local task that knows the partition identifier can delete the partition. + + When a global partition is deleted, the partition identifier must be + transmitted to every node in the system for deletion from the local copy of + the global object table. + + The partition must reside on the local node, even if the partition was + created with the ${../../attr/if/global:/name} attribute. params: -- description: '%' +- description: is the partition identifier. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no partition with the specified identifier. + value: ${../../status/if/invalid-id:/name} + - description: | + The partition resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} + - description: | + There were buffers of the partition still in use. + value: ${../../status/if/resource-in-use:/name} type: interface diff --git a/spec/rtems/part/if/get-buffer.yml b/spec/rtems/part/if/get-buffer.yml index 004567b0..43dd30ca 100644 --- a/spec/rtems/part/if/get-buffer.yml +++ b/spec/rtems/part/if/get-buffer.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Tries to get a buffer from the specified partition. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,9 +12,14 @@ definition: - void **${.:/params[1]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive allows a buffer to be obtained from the partition specified in + the ${.:/params[0]/name} parameter. The address of the allocated buffer is + returned through the ${.:/params[1]/name} parameter. enabled-by: true -index-entries: [] +index-entries: +- get buffer from partition +- obtain buffer from partition interface-type: function links: - role: interface-placement @@ -21,15 +27,38 @@ links: - role: interface-ingroup uid: group name: rtems_partition_get_buffer -notes: null +notes: | + This directive will not cause the running task to be preempted. + + All buffers begin on a four byte boundary. + + A task cannot wait on a buffer to become available. + + Getting a buffer from a global partition which does not reside on the local + node will generate a request telling the remote node to allocate a buffer + from the specified partition. params: -- description: '%' +- description: is the partition identifier. dir: null name: id -- description: '%' - dir: null +- description: | + is the pointer to a buffer pointer variable. The pointer to the allocated + buffer will be stored in this variable, in case of a successful operation. + dir: out name: buffer return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no partition with the specified identifier. + value: ${../../status/if/invalid-id:/name} + - description: | + The ``${.:/params[1]/name}`` parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + There was no free buffer available to return. + value: ${../../status/if/unsatisfied:/name} type: interface diff --git a/spec/rtems/part/if/ident.yml b/spec/rtems/part/if/ident.yml index 534d0243..16e84c9d 100644 --- a/spec/rtems/part/if/ident.yml +++ b/spec/rtems/part/if/ident.yml @@ -29,7 +29,9 @@ description: | * the constant ${../../object/if/search-other-nodes:/name} to search in all nodes except the local node. enabled-by: true -index-entries: [] +index-entries: +- get ID of a partition +- obtain ID of a partition interface-type: function links: - role: interface-placement diff --git a/spec/rtems/part/if/return-buffer.yml b/spec/rtems/part/if/return-buffer.yml index 6c5118a5..3878f14f 100644 --- a/spec/rtems/part/if/return-buffer.yml +++ b/spec/rtems/part/if/return-buffer.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Returns a buffer to the specified partition. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,9 +12,12 @@ definition: - void *${.:/params[1]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive returns the buffer specified by ${.:/params[1]/name} to the + partition specified by ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- return buffer to partition interface-type: function links: - role: interface-placement @@ -21,15 +25,33 @@ links: - role: interface-ingroup uid: group name: rtems_partition_return_buffer -notes: null +notes: | + This directive will not cause the running task to be preempted. + + Returning a buffer to a global partition which does not reside on the local + node will generate a request telling the remote node to return the buffer to + the specified partition. + + Returning a buffer multiple times is an error. It will corrupt the internal + state of the partition. params: -- description: '%' +- description: is the partition identifier. dir: null name: id -- description: '%' +- description: is the pointer to the buffer to return. dir: null name: buffer return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no partition with the specified identifier. + value: ${../../status/if/invalid-id:/name} + - description: | + The buffer referenced by ``${.:/params[1]/name}`` was no in the specified + partition. + value: ${../../status/if/invalid-address:/name} type: interface diff --git a/spec/score/cpu/if/sizeof-pointer.yml b/spec/score/cpu/if/sizeof-pointer.yml new file mode 100644 index 00000000..9694a333 --- /dev/null +++ b/spec/score/cpu/if/sizeof-pointer.yml @@ -0,0 +1,12 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +index-entries: [] +interface-type: unspecified-define +links: +- role: interface-placement + uid: header +name: CPU_SIZEOF_POINTER +reference: null +type: interface -- cgit v1.2.3