[rtems-central commit] spec: Review Partition Manager
Sebastian Huber
sebh at rtems.org
Thu Oct 8 13:25:41 UTC 2020
Module: rtems-central
Branch: master
Commit: 74a75d8acc0da0eb6a7d7970c4b77b9c318a86ac
Changeset: http://git.rtems.org/rtems-central/commit/?id=74a75d8acc0da0eb6a7d7970c4b77b9c318a86ac
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Sep 30 15:20:34 2020 +0200
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(-)
diff --git a/spec/rtems/part/if/alignment.yml b/spec/rtems/part/if/alignment.yml
new file mode 100644
index 0000000..35ce39a
--- /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 e182b78..a150294 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 598b020..4c87a44 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 004567b..43dd30c 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 534d024..16e84c9 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 6c5118a..3878f14 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 0000000..9694a33
--- /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
More information about the vc
mailing list