From ede8f51e543b2e7d4fb43a19a2c22819359b2b2c Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 14 Oct 2020 09:43:48 +0200 Subject: rtems: Update partition documentation --- cpukit/include/rtems/rtems/partdata.h | 91 +++++++++++++++++++++++------------ cpukit/include/rtems/rtems/partimpl.h | 24 ++++++++- 2 files changed, 84 insertions(+), 31 deletions(-) (limited to 'cpukit') 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 . + * This macro should only be used by . * - * @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 -- cgit v1.2.3