spec: Review Partition Manager

7 files changed, 240 insertions, 33 deletions

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