Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix #1355, improve documentation for resourceID patterns #1382

Merged
merged 1 commit into from
Apr 28, 2021
Merged

Fix #1355, improve documentation for resourceID patterns #1382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 42 additions & 5 deletions modules/es/fsw/src/cfe_es_cds.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,12 +267,24 @@ int32 CFE_ES_CDSHandle_ToIndex(CFE_ES_CDSHandle_t BlockID, uint32 *Idx);
/**
* @brief Get a registry record within the CDS, given a block ID/handle
*
* Retrieves a pointer to the registry record associated with a CDS block ID/handle
* Returns NULL if the handle is outside the valid range
* This only returns a pointer to the table entry where the record
* should reside, but does _not_ actually check/validate the entry.
*
* @note This only does the lookup, it does not validate that the handle
* actually matches the returned record. The caller should lock the CDS and
* confirm that the record is a match to the expected ID before using it.
* If the passed-in ID parameter is not within the acceptable range of ID
* values for CDS blocks, such that it could never be valid under
* any circumstances, then NULL is returned. Otherwise, a pointer to the
* corresponding table entry is returned, indicating the location where
* that ID _should_ reside, if it is currently in use.
*
* @note This only returns where the ID should reside, not that it actually
* resides there. If looking up an existing ID, then caller must additionally
* confirm that the returned record is a match to the expected ID before using
* or modifying the data within the returned record pointer.
*
* The CFE_ES_CDSBlockRecordIsMatch() function can be used to check/confirm
* if the returned table entry is a positive match for the given ID.
*
* @sa CFE_ES_CDSBlockRecordIsMatch()
*
* @param[in] BlockID the ID/handle of the CDS block to retrieve
* @returns Pointer to registry record, or NULL if ID/handle invalid.
Expand All @@ -287,6 +299,9 @@ CFE_ES_CDS_RegRec_t *CFE_ES_LocateCDSBlockRecordByID(CFE_ES_CDSHandle_t BlockID)
* As this dereferences fields within the record, global data must be
* locked prior to invoking this function.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] CDSBlockRecPtr pointer to Pool table entry
* @returns true if the entry is in use/configured, or false if it is free/empty
*/
Expand All @@ -300,6 +315,9 @@ static inline bool CFE_ES_CDSBlockRecordIsUsed(const CFE_ES_CDS_RegRec_t *CDSBlo
*
* This routine converts the table entry back to an abstract ID.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] CDSBlockRecPtr pointer to Pool table entry
* @returns BlockID of entry
*/
Expand All @@ -314,6 +332,9 @@ static inline CFE_ES_CDSHandle_t CFE_ES_CDSBlockRecordGetID(const CFE_ES_CDS_Reg
* This sets the internal field(s) within this entry, and marks
* it as being associated with the given Pool ID.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] CDSBlockRecPtr pointer to Pool table entry
* @param[in] PendingId the Pool ID of this entry
*/
Expand All @@ -328,6 +349,9 @@ static inline void CFE_ES_CDSBlockRecordSetUsed(CFE_ES_CDS_RegRec_t *CDSBlockRec
* This clears the internal field(s) within this entry, and allows the
* memory to be re-used in the future.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] CDSBlockRecPtr pointer to Pool table entry
*/
static inline void CFE_ES_CDSBlockRecordSetFree(CFE_ES_CDS_RegRec_t *CDSBlockRecPtr)
Expand All @@ -344,6 +368,16 @@ static inline void CFE_ES_CDSBlockRecordSetFree(CFE_ES_CDS_RegRec_t *CDSBlockRec
* As this dereferences fields within the record, CDS access mutex must be
* locked prior to invoking this function.
*
* This function may be used in conjunction with CFE_ES_LocateCDSBlockRecordByID()
* to confirm that the located record is a positive match to the expected ID.
* As such, the record pointer is also permitted to be NULL, to alleviate the
* need for the caller to handle this possibility explicitly.
*
* Once a record pointer has been successfully validated using this routine,
* it may be safely passed to all other internal functions.
*
* @sa CFE_ES_LocateCDSBlockRecordByID
*
* @param[in] CDSBlockRecPtr pointer to registry table entry
* @param[in] BlockID expected block ID
* @returns true if the entry matches the given block ID
Expand All @@ -365,6 +399,9 @@ static inline bool CFE_ES_CDSBlockRecordIsMatch(const CFE_ES_CDS_RegRec_t *CDSBl
* which contains error checking information. Therefore the usable data
* size is less than the raw block size.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] CDSBlockRecPtr pointer to registry table entry
* @returns Usable size of the CDS
*/
Expand Down
42 changes: 40 additions & 2 deletions modules/es/fsw/src/cfe_es_mempool.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,24 @@ int32 CFE_ES_MemPoolID_ToIndex(CFE_ES_MemHandle_t PoolID, uint32 *Idx);
/**
* @brief Locate the Pool table entry correlating with a given Pool ID.
*
* This only returns a pointer to the table entry and does _not_
* otherwise check/validate the entry.
* This only returns a pointer to the table entry where the record
* should reside, but does _not_ actually check/validate the entry.
*
* If the passed-in ID parameter is not within the acceptable range of ID
* values for memory pools, such that it could never be valid under
* any circumstances, then NULL is returned. Otherwise, a pointer to the
* corresponding table entry is returned, indicating the location where
* that ID _should_ reside, if it is currently in use.
*
* @note This only returns where the ID should reside, not that it actually
* resides there. If looking up an existing ID, then caller must additionally
* confirm that the returned record is a match to the expected ID before using
* or modifying the data within the returned record pointer.
*
* The CFE_ES_MemPoolRecordIsMatch() function can be used to check/confirm
* if the returned table entry is a positive match for the given ID.
*
* @sa CFE_ES_MemPoolRecordIsMatch()
*
* @param[in] PoolID the Pool ID to locate
* @return pointer to Pool Table entry for the given Pool ID
Expand All @@ -116,6 +132,9 @@ CFE_ES_MemPoolRecord_t *CFE_ES_LocateMemPoolRecordByID(CFE_ES_MemHandle_t PoolID
* As this dereferences fields within the record, global data must be
* locked prior to invoking this function.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] PoolRecPtr pointer to Pool table entry
* @returns true if the entry is in use/configured, or false if it is free/empty
*/
Expand All @@ -129,6 +148,9 @@ static inline bool CFE_ES_MemPoolRecordIsUsed(const CFE_ES_MemPoolRecord_t *Pool
*
* This routine converts the table entry back to an abstract ID.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] PoolRecPtr pointer to Pool table entry
* @returns PoolID of entry
*/
Expand All @@ -143,6 +165,9 @@ static inline CFE_ES_MemHandle_t CFE_ES_MemPoolRecordGetID(const CFE_ES_MemPoolR
* This sets the internal field(s) within this entry, and marks
* it as being associated with the given Pool ID.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] PoolRecPtr pointer to Pool table entry
* @param[in] PendingId the Pool ID of this entry
*/
Expand All @@ -157,6 +182,9 @@ static inline void CFE_ES_MemPoolRecordSetUsed(CFE_ES_MemPoolRecord_t *PoolRecPt
* This clears the internal field(s) within this entry, and allows the
* memory to be re-used in the future.
*
* @note This internal helper function must only be used on record pointers
* that are known to refer to an actual table location (i.e. non-null).
*
* @param[in] PoolRecPtr pointer to Pool table entry
*/
static inline void CFE_ES_MemPoolRecordSetFree(CFE_ES_MemPoolRecord_t *PoolRecPtr)
Expand All @@ -173,6 +201,16 @@ static inline void CFE_ES_MemPoolRecordSetFree(CFE_ES_MemPoolRecord_t *PoolRecPt
* As this dereferences fields within the record, global data must be
* locked prior to invoking this function.
*
* This function may be used in conjunction with CFE_ES_LocateMemPoolRecordByID()
* to confirm that the located record is a positive match to the expected ID.
* As such, the record pointer is also permitted to be NULL, to alleviate the
* need for the caller to handle this possibility explicitly.
*
* Once a record pointer has been successfully validated using this routine,
* it may be safely passed to all other internal functions.
*
* @sa CFE_ES_LocateMemPoolRecordByID
*
* @param[in] PoolRecPtr pointer to Pool table entry
* @param[in] PoolID expected Pool ID
* @returns true if the entry matches the given pool ID
Expand Down
Loading