[PATCH 05/20] rtems: Update partition documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri Nov 20 11:15:11 UTC 2020
---
cpukit/include/rtems/rtems/partdata.h | 91 ++++++++++++++++++---------
cpukit/include/rtems/rtems/partimpl.h | 24 ++++++-
2 files changed, 84 insertions(+), 31 deletions(-)
diff --git a/cpukit/include/rtems/rtems/partdata.h b/cpukit/include/rtems/rtems/partdata.h
index d012367b2b..32289cd378 100644
--- a/cpukit/include/rtems/rtems/partdata.h
+++ b/cpukit/include/rtems/rtems/partdata.h
@@ -33,39 +33,71 @@ extern "C" {
*/
/**
- * The following defines the control block used to manage each partition.
+ * @brief The Partition Control Block (PTCB) represents a partition.
*/
typedef struct {
- /** This field is the object management portion of a Partition instance. */
- Objects_Control Object;
- /** This field is the lock of the Partition. */
- ISR_LOCK_MEMBER( Lock )
- /** This field is the physical starting address of the Partition. */
- void *starting_address;
- /** This field is the size of the Partition in bytes. */
- uintptr_t length;
- /** This field is the size of each buffer in bytes */
- size_t buffer_size;
- /** This field is the attribute set provided at create time. */
- rtems_attribute attribute_set;
- /** This field is the of allocated buffers. */
- uintptr_t number_of_used_blocks;
- /** This field is the chain used to manage unallocated buffers. */
- Chain_Control Memory;
-} Partition_Control;
+ /**
+ * @brief This member turns the PTCB into an object.
+ */
+ Objects_Control Object;
+
+ /**
+ * @brief This lock protects the chain of unallocated buffers and the number
+ * of allocated buffers.
+ */
+ ISR_LOCK_MEMBER( Lock )
+
+ /**
+ * @brief This member contains the physical starting address of the buffer
+ * area.
+ */
+ void *starting_address;
+
+ /**
+ * @brief This member contains the size of the buffer area in bytes.
+ */
+ uintptr_t length;
+
+ /**
+ * @brief This member contains the size of each buffer in bytes.
+ */
+ size_t buffer_size;
+
+ /**
+ * @brief This member contains the attribute set provided at creation time.
+ */
+ rtems_attribute attribute_set;
+
+ /**
+ * @brief This member contains the count of allocated buffers.
+ */
+ uintptr_t number_of_used_blocks;
+
+ /**
+ * @brief This chain is used to manage unallocated buffers.
+ */
+ Chain_Control Memory;
+} Partition_Control;
/**
- * @brief The Classic Partition objects information.
+ * @brief The Partition Manager objects information is used to manage the
+ * objects of this class.
+ *
+ * If #CONFIGURE_MAXIMUM_PARTITIONS is greater than zero, then the object
+ * information is defined by PARTITION_INFORMATION_DEFINE(), otherwise it is
+ * defined by OBJECTS_INFORMATION_DEFINE_ZERO().
*/
extern Objects_Information _Partition_Information;
#if defined(RTEMS_MULTIPROCESSING)
/**
- * @brief Partition_MP_Send_extract_proxy
+ * @brief Sends the extract proxy request.
+ *
+ * This routine is invoked when a task is deleted and it has a proxy which must
+ * be removed from a thread queue and the remote node must be informed of this.
*
- * This routine is invoked when a task is deleted and it
- * has a proxy which must be removed from a thread queue and
- * the remote node must be informed of this.
+ * @param[in, out] the_thread is the thread proxy.
+ * @param id is the partition identifier.
*/
void _Partition_MP_Send_extract_proxy (
Thread_Control *the_thread,
@@ -74,21 +106,20 @@ void _Partition_MP_Send_extract_proxy (
#endif
/**
- * @brief Macro to define the objects information for the Classic Partition
- * objects.
+ * @brief Defines the Partition Manager objects information.
*
- * This macro should only be used by <rtems/confdefs.h>.
+ * This macro should only be used by <rtems/confdefs/objectsclassic.h>.
*
- * @param max The configured object maximum (the OBJECTS_UNLIMITED_OBJECTS flag
- * may be set).
+ * @param _max is the configured object maximum (the #OBJECTS_UNLIMITED_OBJECTS
+ * flag may be set).
*/
-#define PARTITION_INFORMATION_DEFINE( max ) \
+#define PARTITION_INFORMATION_DEFINE( _max ) \
OBJECTS_INFORMATION_DEFINE( \
_Partition, \
OBJECTS_CLASSIC_API, \
OBJECTS_RTEMS_PARTITIONS, \
Partition_Control, \
- max, \
+ _max, \
OBJECTS_NO_STRING_NAME, \
_Partition_MP_Send_extract_proxy \
)
diff --git a/cpukit/include/rtems/rtems/partimpl.h b/cpukit/include/rtems/rtems/partimpl.h
index 5006f5cdc1..9327188eea 100644
--- a/cpukit/include/rtems/rtems/partimpl.h
+++ b/cpukit/include/rtems/rtems/partimpl.h
@@ -28,7 +28,7 @@ extern "C" {
#endif
/**
- * @defgroup ClassicPartImpl Classic Partition Manager Implementation
+ * @defgroup ClassicPartImpl Partition Manager Implementation
*
* @ingroup RTEMSImplClassic
*
@@ -177,6 +177,14 @@ RTEMS_INLINE_ROUTINE void _Partition_Free (
_Objects_Free( &_Partition_Information, &the_partition->Object );
}
+/**
+ * @brief Calls _Objects_Get() using the ::_Partition_Information.
+ *
+ * @param id is the object identifier.
+ * @param[out] lock_context is the lock context.
+ *
+ * @return See _Objects_Get().
+ */
RTEMS_INLINE_ROUTINE Partition_Control *_Partition_Get(
Objects_Id id,
ISR_lock_Context *lock_context
@@ -189,6 +197,13 @@ RTEMS_INLINE_ROUTINE Partition_Control *_Partition_Get(
);
}
+/**
+ * @brief Acquires the partition lock in an ISR disabled section.
+ *
+ * @param[in, out] the_partition is the partition control block.
+ *
+ * @param[in, out] lock_context is the lock context set up by _Partition_Get().
+ */
RTEMS_INLINE_ROUTINE void _Partition_Acquire_critical(
Partition_Control *the_partition,
ISR_lock_Context *lock_context
@@ -197,6 +212,13 @@ RTEMS_INLINE_ROUTINE void _Partition_Acquire_critical(
_ISR_lock_Acquire( &the_partition->Lock, lock_context );
}
+/**
+ * @brief Releases the partition lock and restores the ISR level.
+ *
+ * @param[in, out] the_partition is the partition control block.
+ *
+ * @param[in, out] lock_context is the lock context set up by _Partition_Get().
+ */
RTEMS_INLINE_ROUTINE void _Partition_Release(
Partition_Control *the_partition,
ISR_lock_Context *lock_context
--
2.26.2
More information about the devel
mailing list