[rtems commit] rtems: Clarify partition manager documentation

Sebastian Huber sebh at rtems.org
Wed Feb 3 05:17:34 UTC 2021


Module:    rtems
Branch:    master
Commit:    aa0060f4c15e37b76d0a22be3ba21c9dca70eb87
Changeset: http://git.rtems.org/rtems/commit/?id=aa0060f4c15e37b76d0a22be3ba21c9dca70eb87

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Feb  3 06:08:21 2021 +0100

rtems: Clarify partition manager documentation

Unify the wording across similar directives of other managers.  Add
"Constraints" paragraph.

Update #3993.

---

 cpukit/include/rtems/rtems/part.h | 168 ++++++++++++++++++++++++++++----------
 1 file changed, 124 insertions(+), 44 deletions(-)

diff --git a/cpukit/include/rtems/rtems/part.h b/cpukit/include/rtems/rtems/part.h
index 4979f8a..337e28c 100644
--- a/cpukit/include/rtems/rtems/part.h
+++ b/cpukit/include/rtems/rtems/part.h
@@ -9,7 +9,7 @@
  */
 
 /*
- * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+ * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
  * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
  *
  * Redistribution and use in source and binary forms, with or without
@@ -99,7 +99,7 @@ extern "C" {
  *
  * @brief Creates a partition.
  *
- * @param name is the name of the partition.
+ * @param name is the object name of the partition.
  *
  * @param starting_address is the starting address of the buffer area used by
  *   the partition.
@@ -113,34 +113,40 @@ extern "C" {
  * @param attribute_set is the attribute set of the partition.
  *
  * @param[out] id 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.
+ *   identifier of the created partition will be stored in this variable, in
+ *   case of a successful operation.
  *
  * This directive creates a partition of fixed size buffers from a physically
  * contiguous memory space which starts at ``starting_address`` and is
  * ``length`` bytes in size.  Each allocated buffer is to be of ``buffer_size``
- * in bytes.  The assigned object identifier is returned in ``id``.  This
+ * in bytes.  The partition has the user-defined object name specified in
+ * ``name``.  The assigned object identifier is returned in ``id``.  This
  * identifier is used to access the partition with other partition related
  * directives.
  *
  * The **attribute set** specified in ``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** scope is the default and can be emphasized through the use of
+ * *bitwise or* of the attribute constants described below.  Not all
+ * combinations of attributes are allowed.  Some attributes are mutually
+ * exclusive.  If mutually exclusive attributes are combined, the behaviour is
+ * undefined.  Attributes not mentioned below are not evaluated by this
+ * directive and have no effect.  Default attributes can be selected by using
+ * the #RTEMS_DEFAULT_ATTRIBUTES constant.
+ *
+ * The partition has a local or global **scope** in a multiprocessing network
+ * (this attribute does not refer to SMP systems).  The scope is selected by
+ * the mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL attributes.
+ *
+ * * A **local scope** is the default and can be emphasized through the use of
  *   the #RTEMS_LOCAL attribute.  A local partition can be only used by the
  *   node which created it.
  *
- * * A **global** scope is established if the #RTEMS_GLOBAL attribute is set.
+ * * A **global scope** is established if the #RTEMS_GLOBAL 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.
  *
  * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
  *
- * @retval ::RTEMS_INVALID_NAME The partition name was invalid.
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
  *
  * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
  *
@@ -161,14 +167,17 @@ extern "C" {
  *   on a pointer size boundary.
  *
  * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
- *   new partition.  The number of partitions available to the application is
- *   configured through the #CONFIGURE_MAXIMUM_PARTITIONS configuration option.
+ *   partition.  The number of partitions available to the application is
+ *   configured through the #CONFIGURE_MAXIMUM_PARTITIONS application
+ *   configuration option.
+ *
+ * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no
+ *   inactive global object available to create a global semaphore.  The number
+ *   of global objects available to the application is configured through the
+ *   #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.
  *
  * @par Notes
  * @parblock
- * 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 ``starting_address`` 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
@@ -193,10 +202,31 @@ extern "C" {
  * 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.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within device driver initialization
+ *   context.
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may obtain and release the object allocator mutex.  This may
+ *   cause the calling task to be preempted.
  *
- * The total number of global objects, including partitions, is limited by the
- * value of the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration
- * option.
+ * * The number of partitions available to the application is configured
+ *   through the #CONFIGURE_MAXIMUM_PARTITIONS application configuration
+ *   option.
+ *
+ * * Where the object class corresponding to the directive is configured to use
+ *   unlimited objects, the directive may allocate memory from the RTEMS
+ *   Workspace.
+ *
+ * * The number of global objects available to the application is configured
+ *   through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration
+ *   option.
  * @endparblock
  */
 rtems_status_code rtems_partition_create(
@@ -254,18 +284,30 @@ rtems_status_code rtems_partition_create(
  * If the partition name is not unique, then the partition identifier will
  * match the first partition with that name in the search order.  However, this
  * partition identifier is not guaranteed to correspond to the desired
- * partition.  The partition identifier is used with other partition related
- * directives to access the partition.
+ * partition.
  *
- * If node is #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local
- * node being searched first.  All other nodes are searched with the lowest
- * numbered node searched first.
+ * The objects are searched from lowest to the highest index.  If ``node`` is
+ * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being
+ * searched first.  All other nodes are searched from lowest to the highest
+ * node number.
  *
  * If node is a valid node number which does not represent the local node, then
  * only the partitions exported by the designated node are searched.
  *
  * This directive does not generate activity on remote nodes.  It accesses only
  * the local copy of the global object table.
+ *
+ * The partition identifier is used with other partition related directives to
+ * access the partition.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
  * @endparblock
  */
 rtems_status_code rtems_partition_ident(
@@ -283,8 +325,7 @@ rtems_status_code rtems_partition_ident(
  *
  * @param id is the partition identifier.
  *
- * This directive deletes the partition specified by the ``id`` parameter.  The
- * partition cannot be deleted if any of its buffers are still allocated.
+ * This directive deletes the partition specified by ``id``.
  *
  * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
  *
@@ -299,14 +340,10 @@ rtems_status_code rtems_partition_ident(
  *
  * @par Notes
  * @parblock
- * This directive may cause the calling task to be preempted due to an obtain
- * and release of the object allocator mutex.
+ * The partition cannot be deleted if any of its buffers are still allocated.
  *
  * The PTCB for the deleted partition is reclaimed by RTEMS.
  *
- * 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.
@@ -314,6 +351,25 @@ rtems_status_code rtems_partition_ident(
  * The partition must reside on the local node, even if the partition was
  * created with the #RTEMS_GLOBAL attribute.
  * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within device driver initialization
+ *   context.
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may obtain and release the object allocator mutex.  This may
+ *   cause the calling task to be preempted.
+ *
+ * * The calling task does not have to be the task that created the object.
+ *   Any local task that knows the object identifier can delete the object.
+ *
+ * * Where the object class corresponding to the directive is configured to use
+ *   unlimited objects, the directive may free memory to the RTEMS Workspace.
+ * @endparblock
  */
 rtems_status_code rtems_partition_delete( rtems_id id );
 
@@ -331,8 +387,8 @@ rtems_status_code rtems_partition_delete( rtems_id id );
  *   successful operation.
  *
  * This directive allows a buffer to be obtained from the partition specified
- * in the ``id`` parameter.  The address of the allocated buffer is returned
- * through the ``buffer`` parameter.
+ * by ``id``.  The address of the allocated buffer is returned through the
+ * ``buffer`` parameter.
  *
  * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
  *
@@ -346,8 +402,6 @@ rtems_status_code rtems_partition_delete( rtems_id id );
  *
  * @par Notes
  * @parblock
- * This directive will not cause the running task to be preempted.
- *
  * The buffer start alignment is determined by the memory area and buffer size
  * used to create the partition.
  *
@@ -357,6 +411,23 @@ rtems_status_code rtems_partition_delete( rtems_id id );
  * node will generate a request telling the remote node to allocate a buffer
  * from the partition.
  * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * When the directive operates on a local object, the directive may be called
+ *   from within interrupt context.
+ *
+ * * The directive may be called from within task context.
+ *
+ * * When the directive operates on a local object, the directive will not
+ *   cause the calling task to be preempted.
+ *
+ * * When the directive operates on a remote object, the directive sends a
+ *   message to the remote node and waits for a reply.  This will preempt the
+ *   calling task.
+ * @endparblock
  */
 rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer );
 
@@ -383,15 +454,24 @@ rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer );
  *   in the partition.
  *
  * @par Notes
+ * Returning a buffer multiple times is an error.  It will corrupt the internal
+ * state of the partition.
+ *
+ * @par Constraints
  * @parblock
- * This directive will not cause the running task to be preempted.
+ * The following constraints apply to this directive:
  *
- * 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 partition.
+ * * When the directive operates on a local object, the directive may be called
+ *   from within interrupt context.
  *
- * Returning a buffer multiple times is an error.  It will corrupt the internal
- * state of the partition.
+ * * The directive may be called from within task context.
+ *
+ * * When the directive operates on a local object, the directive will not
+ *   cause the calling task to be preempted.
+ *
+ * * When the directive operates on a remote object, the directive sends a
+ *   message to the remote node and waits for a reply.  This will preempt the
+ *   calling task.
  * @endparblock
  */
 rtems_status_code rtems_partition_return_buffer( rtems_id id, void *buffer );



More information about the vc mailing list