From e531836d26ea3cc0cbd25d647f461d81714d1550 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Mon, 19 Apr 2021 17:26:48 -0400 Subject: [PATCH] Fix #1355, improve documentation for resourceID patterns Improve the doxygen documentation on the various helper functions and common patterns dealing with Resource IDs. Specifically, document that the "IsMatch()" functions specifically accept NULL pointers to allow use with initial validation (gatekeeper), but all other helper functions assume a non-NULL pointer. --- modules/es/fsw/src/cfe_es_cds.h | 47 ++++++- modules/es/fsw/src/cfe_es_mempool.h | 42 +++++- modules/es/fsw/src/cfe_es_resource.h | 190 +++++++++++++++++++++++++-- modules/sb/fsw/src/cfe_sb_priv.h | 44 ++++++- 4 files changed, 300 insertions(+), 23 deletions(-) diff --git a/modules/es/fsw/src/cfe_es_cds.h b/modules/es/fsw/src/cfe_es_cds.h index 0a952a58a..eb5a2d7a3 100644 --- a/modules/es/fsw/src/cfe_es_cds.h +++ b/modules/es/fsw/src/cfe_es_cds.h @@ -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. @@ -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 */ @@ -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 */ @@ -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 */ @@ -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) @@ -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 @@ -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 */ diff --git a/modules/es/fsw/src/cfe_es_mempool.h b/modules/es/fsw/src/cfe_es_mempool.h index 5c15f4cf6..5ba2ddfe7 100644 --- a/modules/es/fsw/src/cfe_es_mempool.h +++ b/modules/es/fsw/src/cfe_es_mempool.h @@ -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 @@ -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 */ @@ -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 */ @@ -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 */ @@ -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) @@ -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 diff --git a/modules/es/fsw/src/cfe_es_resource.h b/modules/es/fsw/src/cfe_es_resource.h index 6d6f387b4..316e1e525 100644 --- a/modules/es/fsw/src/cfe_es_resource.h +++ b/modules/es/fsw/src/cfe_es_resource.h @@ -41,44 +41,108 @@ /** * @brief Locate the app table entry correlating with a given app 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 applications, 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_AppRecordIsMatch() function can be used to check/confirm + * if the returned table entry is a positive match for the given ID. + * + * @sa CFE_ES_AppRecordIsMatch() * * @param[in] AppID the app ID to locate - * @return pointer to App Table entry for the given app ID + * @return pointer to App Table entry for the given app ID, or NULL if out of range */ extern CFE_ES_AppRecord_t *CFE_ES_LocateAppRecordByID(CFE_ES_AppId_t AppID); /** * @brief Locate the Library table entry correlating with a given Lib 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 libraries, 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_LibRecordIsMatch() function can be used to check/confirm + * if the returned table entry is a positive match for the given ID. + * + * @sa CFE_ES_LibRecordIsMatch() * * @param[in] LibID the Lib ID to locate - * @return pointer to Library Table entry for the given Lib ID + * @return pointer to Library Table entry for the given Lib ID, or NULL if out of range */ extern CFE_ES_LibRecord_t *CFE_ES_LocateLibRecordByID(CFE_ES_LibId_t LibID); /** * @brief Locate the task table entry correlating with a given task 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 tasks, 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_TaskRecordIsMatch() function can be used to check/confirm + * if the returned table entry is a positive match for the given ID. + * + * @sa CFE_ES_TaskRecordIsMatch() * * @param[in] TaskID the task ID to locate - * @return pointer to Task Table entry for the given task ID + * @return pointer to Task Table entry for the given task ID, or NULL if out of range */ extern CFE_ES_TaskRecord_t *CFE_ES_LocateTaskRecordByID(CFE_ES_TaskId_t TaskID); /** * @brief Locate the Counter table entry correlating with a given Counter 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 counters, 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_CounterRecordIsMatch() function can be used to check/confirm + * if the returned table entry is a positive match for the given ID. + * + * @sa CFE_ES_CounterRecordIsMatch() * * @param[in] CounterID the Counter ID to locate - * @return pointer to Counter Table entry for the given Counter ID + * @return pointer to Counter Table entry for the given Counter ID, or NULL if out of range */ extern CFE_ES_GenCounterRecord_t *CFE_ES_LocateCounterRecordByID(CFE_ES_CounterId_t CounterID); @@ -90,6 +154,9 @@ extern CFE_ES_GenCounterRecord_t *CFE_ES_LocateCounterRecordByID(CFE_ES_CounterI * 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] AppRecPtr pointer to app table entry * @returns true if the entry is in use/configured, or false if it is free/empty */ @@ -103,6 +170,9 @@ static inline bool CFE_ES_AppRecordIsUsed(const CFE_ES_AppRecord_t *AppRecPtr) * * 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] AppRecPtr pointer to app table entry * @returns AppID of entry */ @@ -120,6 +190,9 @@ static inline CFE_ES_AppId_t CFE_ES_AppRecordGetID(const CFE_ES_AppRecord_t *App * 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] AppRecPtr pointer to app table entry * @param[in] PendingId the app ID of this entry */ @@ -137,6 +210,9 @@ static inline void CFE_ES_AppRecordSetUsed(CFE_ES_AppRecord_t *AppRecPtr, CFE_Re * 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] AppRecPtr pointer to app table entry */ static inline void CFE_ES_AppRecordSetFree(CFE_ES_AppRecord_t *AppRecPtr) @@ -153,7 +229,17 @@ static inline void CFE_ES_AppRecordSetFree(CFE_ES_AppRecord_t *AppRecPtr) * As this dereferences fields within the record, global data must be * locked prior to invoking this function. * - * @param[in] AppRecPtr pointer to app table entry + * This function may be used in conjunction with CFE_ES_LocateAppRecordByID() + * 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_LocateAppRecordByID + * + * @param[in] AppRecPtr pointer to app table entry, or NULL * @param[in] AppID expected app ID * @returns true if the entry matches the given app ID */ @@ -167,6 +253,9 @@ static inline bool CFE_ES_AppRecordIsMatch(const CFE_ES_AppRecord_t *AppRecPtr, * * Returns the name field from within the Application record * + * @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] AppRecPtr pointer to App table entry * @returns Pointer to Application name */ @@ -183,6 +272,9 @@ static inline const char *CFE_ES_AppRecordGetName(const CFE_ES_AppRecord_t *AppR * 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] LibRecPtr pointer to Lib table entry * @returns true if the entry is in use/configured, or false if it is free/empty */ @@ -196,6 +288,9 @@ static inline bool CFE_ES_LibRecordIsUsed(const CFE_ES_LibRecord_t *LibRecPtr) * * 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] LibRecPtr pointer to Lib table entry * @returns LibID of entry */ @@ -214,6 +309,9 @@ static inline CFE_ES_LibId_t CFE_ES_LibRecordGetID(const CFE_ES_LibRecord_t *Lib * This sets the internal field(s) within this entry, and marks * it as being associated with the given Lib 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] LibRecPtr pointer to Lib table entry * @param[in] PendingId the Lib ID of this entry */ @@ -228,6 +326,9 @@ static inline void CFE_ES_LibRecordSetUsed(CFE_ES_LibRecord_t *LibRecPtr, CFE_Re * 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] LibRecPtr pointer to Lib table entry */ static inline void CFE_ES_LibRecordSetFree(CFE_ES_LibRecord_t *LibRecPtr) @@ -244,6 +345,16 @@ static inline void CFE_ES_LibRecordSetFree(CFE_ES_LibRecord_t *LibRecPtr) * 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_LocateLibRecordByID() + * 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_LocateLibRecordByID + * * @param[in] LibRecPtr pointer to Lib table entry * @param[in] LibID expected Lib ID * @returns true if the entry matches the given Lib ID @@ -258,6 +369,9 @@ static inline bool CFE_ES_LibRecordIsMatch(const CFE_ES_LibRecord_t *LibRecPtr, * * Returns the name field from within the Library record * + * @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] LibRecPtr pointer to Lib table entry * @returns Pointer to Library name */ @@ -274,6 +388,9 @@ static inline const char *CFE_ES_LibRecordGetName(const CFE_ES_LibRecord_t *LibR * 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] TaskRecPtr pointer to Task table entry * @returns TaskID of entry */ @@ -290,6 +407,9 @@ static inline CFE_ES_TaskId_t CFE_ES_TaskRecordGetID(const CFE_ES_TaskRecord_t * * 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] TaskRecPtr pointer to task table entry * @returns true if the entry is in use/configured, or false if it is free/empty */ @@ -307,6 +427,9 @@ static inline bool CFE_ES_TaskRecordIsUsed(const CFE_ES_TaskRecord_t *TaskRecPtr * 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] TaskRecPtr pointer to Task table entry * @param[in] PendingId the Task ID of this entry */ @@ -323,6 +446,9 @@ static inline void CFE_ES_TaskRecordSetUsed(CFE_ES_TaskRecord_t *TaskRecPtr, CFE * 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] TaskRecPtr pointer to task table entry * @returns true if the entry is in use/configured, or false if it is free/empty */ @@ -340,6 +466,16 @@ static inline void CFE_ES_TaskRecordSetFree(CFE_ES_TaskRecord_t *TaskRecPtr) * 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_LocateTaskRecordByID() + * 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_LocateTaskRecordByID + * * @param[in] TaskRecPtr pointer to task table entry * @param[in] TaskID The expected task ID to verify * @returns true if the entry matches the given task ID @@ -354,6 +490,9 @@ static inline bool CFE_ES_TaskRecordIsMatch(const CFE_ES_TaskRecord_t *TaskRecPt * * Returns the name field from within the Task record * + * @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] TaskRecPtr pointer to Task table entry * @returns Pointer to Task name */ @@ -370,6 +509,9 @@ static inline const char *CFE_ES_TaskRecordGetName(const CFE_ES_TaskRecord_t *Ta * 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] CounterRecPtr pointer to Counter table entry * @returns true if the entry is in use/configured, or false if it is free/empty */ @@ -383,6 +525,9 @@ static inline bool CFE_ES_CounterRecordIsUsed(const CFE_ES_GenCounterRecord_t *C * * 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] CounterRecPtr pointer to Counter table entry * @returns CounterID of entry */ @@ -400,6 +545,9 @@ static inline CFE_ES_CounterId_t CFE_ES_CounterRecordGetID(const CFE_ES_GenCount * 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] CounterRecPtr pointer to Counter table entry * @param[in] PendingId the Counter ID of this entry */ @@ -417,6 +565,9 @@ static inline void CFE_ES_CounterRecordSetUsed(CFE_ES_GenCounterRecord_t *Counte * 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] CounterRecPtr pointer to Counter table entry */ static inline void CFE_ES_CounterRecordSetFree(CFE_ES_GenCounterRecord_t *CounterRecPtr) @@ -433,6 +584,16 @@ static inline void CFE_ES_CounterRecordSetFree(CFE_ES_GenCounterRecord_t *Counte * 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_LocateCounterRecordByID() + * 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_LocateCounterRecordByID + * * @param[in] CounterRecPtr pointer to Counter table entry * @param[in] CounterID expected Counter ID * @returns true if the entry matches the given Counter ID @@ -448,6 +609,9 @@ static inline bool CFE_ES_CounterRecordIsMatch(const CFE_ES_GenCounterRecord_t * * * Returns the name field from within the counter record * + * @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] CounterRecPtr pointer to Counter table entry * @returns Pointer to counter name */ diff --git a/modules/sb/fsw/src/cfe_sb_priv.h b/modules/sb/fsw/src/cfe_sb_priv.h index a607853fb..db93107c4 100644 --- a/modules/sb/fsw/src/cfe_sb_priv.h +++ b/modules/sb/fsw/src/cfe_sb_priv.h @@ -524,8 +524,24 @@ int32 CFE_SB_SendPrevSubsCmd(const CFE_SB_SendPrevSubsCmd_t *data); /** * @brief Locate the Pipe table entry correlating with a given Pipe 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 pipe IDs, 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_SB_PipeDescIsMatch() function can be used to check/confirm + * if the returned table entry is a positive match for the given ID. + * + * @sa CFE_SB_PipeDescIsMatch() * * @param[in] PipeId the Pipe ID to locate * @return pointer to Pipe Table entry for the given Pipe ID @@ -540,6 +556,9 @@ extern CFE_SB_PipeD_t *CFE_SB_LocatePipeDescByID(CFE_SB_PipeId_t PipeId); * As this dereferences fields within the descriptor, 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] PipeDscPtr pointer to Pipe table entry * @returns true if the entry is in use/configured, or false if it is free/empty */ @@ -553,6 +572,9 @@ static inline bool CFE_SB_PipeDescIsUsed(const CFE_SB_PipeD_t *PipeDscPtr) * * 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] PipeDscPtr pointer to Pipe table entry * @returns PipeID of entry */ @@ -570,8 +592,11 @@ static inline CFE_SB_PipeId_t CFE_SB_PipeDescGetID(const CFE_SB_PipeD_t *PipeDsc * As this dereferences fields within the descriptor, 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] PipeDscPtr pointer to Pipe table entry - * @param[in] PipeID the Pipe ID of this entry + * @param[in] PendingID the Pipe ID of this entry */ static inline void CFE_SB_PipeDescSetUsed(CFE_SB_PipeD_t *PipeDscPtr, CFE_ResourceId_t PendingID) { @@ -587,6 +612,9 @@ static inline void CFE_SB_PipeDescSetUsed(CFE_SB_PipeD_t *PipeDscPtr, CFE_Resour * As this dereferences fields within the descriptor, 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] PipeDscPtr pointer to Pipe table entry */ static inline void CFE_SB_PipeDescSetFree(CFE_SB_PipeD_t *PipeDscPtr) @@ -603,6 +631,16 @@ static inline void CFE_SB_PipeDescSetFree(CFE_SB_PipeD_t *PipeDscPtr) * As this dereferences fields within the descriptor, global data must be * locked prior to invoking this function. * + * This function may be used in conjunction with CFE_SB_LocatePipeDescByID() + * 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_SB_LocatePipeDescByID + * * @param[in] PipeDscPtr pointer to Pipe table entry * @param[in] PipeID expected Pipe ID * @returns true if the entry matches the given Pipe ID