| (Q) + Why do I see event messages in my console window? + | |
| + By default, the events are configured to transmit out a "port" that shows event messages + in the console + | |
| (Q) + What is the difference between event services and the ES System Log + | |
| + Events are within the context of an App or cFE Service (requires registration with ES). + The system log can be written to outside of the Application or cFE Service context, + for example during application startup to report errors before registration. | |
| Document ID - | Document Title + | Document Title + | Link |
|---|---|---|---|
| MKS ID 112 - | cFE Requirements Document + | cFE System (L4) Requirements Document + | cfe/docs/'cfe requirements.docx' |
| 582-2007-001 - | cFE Application Developers Guide + | cFE Functional (L5) Requirements Document + | cfe/docs/cFE_FunctionalRequirements.csv |
| 582-2007-001 | cFE Application Developers Guide + | cfe/docs/'cFE Application Developers Guide.md' | |
| 582-2008-012 - | cFS Deployment Guide - | ||
| - | OS Abstraction Layer (OSAL) Library API + | cFE User's Guide (includes API) + | Autogenerated from code, provided with releases in cFE repository |
| 582-2007-00 - | OS Abstraction Layer (OSAL) Configuraion Guide + | OS Abstraction Layer (OSAL) API + | Autogenerated from code, provided with releases in OSAL repository |
| Acronym - | Description + | Acronym + | Description | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| AC | Attitude Control
@@ -365,8 +314,8 @@
Executive Services API
Events Services API
File Services API
Software Bus API
Table Services API
Time Services API
-** \b NOTE: This is a nominal return code informing the calling application -** that the table identified in the call has had its contents updated since -** the last time the application obtained its address or status. -** -*/ + * @brief Updated + * + * The calling Application has identified a table that has been updated. + * \b NOTE: This is a nominal return code informing the calling application + * that the table identified in the call has had its contents updated since + * the last time the application obtained its address or status. + * + */ #define CFE_TBL_INFO_UPDATED ((int32)0x4c00000E) /** -** The calling Application has tried to allocate a working buffer but -** none were available. -** -*/ + * @brief No Buffer Available + * + * The calling Application has tried to allocate a working buffer but + * none were available. + * + */ #define CFE_TBL_ERR_NO_BUFFER_AVAIL ((int32)0xcc00000F) /** -** The calling Application has attempted to perform a load on a -** table that was created with "Dump Only" attributes. -** -*/ + * @brief Dump Only Error + * + * The calling Application has attempted to perform a load on a + * table that was created with "Dump Only" attributes. + * + */ #define CFE_TBL_ERR_DUMP_ONLY ((int32)0xcc000010) /** -** The calling Application called #CFE_TBL_Load with an illegal -** value for the second parameter. -** -*/ + * @brief Illegal Source Type + * + * The calling Application called #CFE_TBL_Load with an illegal + * value for the second parameter. + * + */ #define CFE_TBL_ERR_ILLEGAL_SRC_TYPE ((int32)0xcc000011) /** -** The calling Application called #CFE_TBL_Load when another Application -** was trying to load the table. -** -*/ + * @brief Load In Progress + * + * The calling Application called #CFE_TBL_Load when another Application + * was trying to load the table. + * + */ #define CFE_TBL_ERR_LOAD_IN_PROGRESS ((int32)0xcc000012) /** -** The calling Application called #CFE_TBL_Load with a bad filename. -** -*/ + * @brief File Not Found + * + * The calling Application called #CFE_TBL_Load with a bad filename. + * + */ #define CFE_TBL_ERR_FILE_NOT_FOUND ((int32)0xcc000013) /** -** The calling Application called #CFE_TBL_Load with a filename that specified a file -** that contained more data than the size of the table OR which contained more data -** than specified in the table header. -** -*/ + * @brief File Too Large + * + * The calling Application called #CFE_TBL_Load with a filename that specified a file + * that contained more data than the size of the table OR which contained more data + * than specified in the table header. + * + */ #define CFE_TBL_ERR_FILE_TOO_LARGE ((int32)0xcc000014) /** -** The calling Application called #CFE_TBL_Load with a filename that specified a file -** that started with the first byte of the table but contained less data than the size of the table. -** It should be noted that #CFE_TBL_WARN_PARTIAL_LOAD also indicates a partial load (one that starts -** at a non-zero offset). -** -*/ + * @brief Short File Warning + * + * The calling Application called #CFE_TBL_Load with a filename that specified a file + * that started with the first byte of the table but contained less data than the size of the table. + * It should be noted that #CFE_TBL_WARN_PARTIAL_LOAD also indicates a partial load (one that starts + * at a non-zero offset). + * + */ #define CFE_TBL_WARN_SHORT_FILE ((int32)0x4c000015) /** -** The calling Application called #CFE_TBL_Load with a filename that specified a file -** whose content ID was not that of a table image. -** -*/ + * @brief Bad Content ID + * + * The calling Application called #CFE_TBL_Load with a filename that specified a file + * whose content ID was not that of a table image. + * + */ #define CFE_TBL_ERR_BAD_CONTENT_ID ((int32)0xcc000016) /** -** The calling Application has attempted to update a table without a pending load. -** -*/ + * @brief No Update Pending + * + * The calling Application has attempted to update a table without a pending load. + * + */ #define CFE_TBL_INFO_NO_UPDATE_PENDING ((int32)0x4c000017) /** -** The calling Application tried to update a table that is locked by another user. -** -*/ + * @brief Table Locked + * + * The calling Application tried to update a table that is locked by another user. + * + */ #define CFE_TBL_INFO_TABLE_LOCKED ((int32)0x4c000018) /** -** The calling Application should call #CFE_TBL_Validate for the specified table. -** -*/ + * Validation Pending + * + * The calling Application should call #CFE_TBL_Validate for the specified table. + * + */ #define CFE_TBL_INFO_VALIDATION_PENDING ((int32)0x4c000019) /** -** The calling Application tried to validate a table that did not have a validation request pending. -** -*/ + * No Validation Pending + * + * The calling Application tried to validate a table that did not have a validation request pending. + * + */ #define CFE_TBL_INFO_NO_VALIDATION_PENDING ((int32)0x4c00001A) /** -** The calling Application tried to access a table file whose Subtype identifier indicated it was not -** a table image file. -** -*/ + * @brief Bad Subtype ID + * + * The calling Application tried to access a table file whose Subtype identifier indicated it was not + * a table image file. + * + */ #define CFE_TBL_ERR_BAD_SUBTYPE_ID ((int32)0xcc00001B) /** -** The calling Application tried to access a table file whose Subtype identifier indicated it was not -** a table image file. -** -*/ + * @brief File Size Inconsistent + * + * The calling Application tried to access a table file whose Subtype identifier indicated it was not + * a table image file. + * + */ #define CFE_TBL_ERR_FILE_SIZE_INCONSISTENT ((int32)0xcc00001C) /** -** The calling Application tried to access a table file whose standard cFE File Header was the wrong size, etc. -** -*/ + * @brief No Standard Header + * + * The calling Application tried to access a table file whose standard cFE File Header was the wrong size, etc. + * + */ #define CFE_TBL_ERR_NO_STD_HEADER ((int32)0xcc00001D) /** -** The calling Application tried to access a table file whose standard cFE -** Table File Header was the wrong size, etc. -** -*/ + * @brief No Table Header + * + * The calling Application tried to access a table file whose standard cFE + * Table File Header was the wrong size, etc. + * + */ #define CFE_TBL_ERR_NO_TBL_HEADER ((int32)0xcc00001E) /** -** The calling Application tried to load a table using a filename -** that was too long. -** -*/ + * @brief Filename Too Long + * + * The calling Application tried to load a table using a filename + * that was too long. + * + */ #define CFE_TBL_ERR_FILENAME_TOO_LONG ((int32)0xcc00001F) /** -** The calling Application tried to load a table using a file whose -** header indicated that it was for a different table. -** -*/ + * @brief File For Wrong Table + * + * The calling Application tried to load a table using a file whose + * header indicated that it was for a different table. + * + */ #define CFE_TBL_ERR_FILE_FOR_WRONG_TABLE ((int32)0xcc000020) /** -** The calling Application tried to load a table file whose header -** claimed the load was larger than what was actually read from the file. -** -*/ + * @brief Load Incomplete + * + * The calling Application tried to load a table file whose header + * claimed the load was larger than what was actually read from the file. + * + */ #define CFE_TBL_ERR_LOAD_INCOMPLETE ((int32)0xcc000021) /** -** The calling Application tried to load a table file whose header -** claimed the load did not start with the first byteIt should be noted -** that #CFE_TBL_WARN_SHORT_FILE also indicates a partial load. -** -*/ + * @brief Partial Load Warning + * + * The calling Application tried to load a table file whose header + * claimed the load did not start with the first byteIt should be noted + * that #CFE_TBL_WARN_SHORT_FILE also indicates a partial load. + * + */ #define CFE_TBL_WARN_PARTIAL_LOAD ((int32)0x4c000022) /** -** The calling Application tried to load a table file whose header -** claimed the load did not start with the first byte and the table -** image had NEVER been loaded before. Partial loads are not allowed -** on uninitialized tables. It should be noted that -** #CFE_TBL_WARN_SHORT_FILE also indicates a partial load. -** -*/ + * @brief Partial Load Error + * + * The calling Application tried to load a table file whose header + * claimed the load did not start with the first byte and the table + * image had NEVER been loaded before. Partial loads are not allowed + * on uninitialized tables. It should be noted that + * #CFE_TBL_WARN_SHORT_FILE also indicates a partial load. + * + */ #define CFE_TBL_ERR_PARTIAL_LOAD ((int32)0xcc000023) /** -** The calling Application should call #CFE_TBL_Manage for the specified table. -** The ground has requested a dump of the Dump-Only table and needs to synchronize -** with the owning application. -** -*/ + * @brief Dump Pending + * + * The calling Application should call #CFE_TBL_Manage for the specified table. + * The ground has requested a dump of the Dump-Only table and needs to synchronize + * with the owning application. + * + */ #define CFE_TBL_INFO_DUMP_PENDING ((int32)0x4c000024) /** -** The calling Application has used an illegal combination of table options. -** A summary of the illegal combinations are as follows: -** \par #CFE_TBL_OPT_USR_DEF_ADDR cannot be combined with any of the following: -** -# #CFE_TBL_OPT_DBL_BUFFER -** -# #CFE_TBL_OPT_LOAD_DUMP -** -# #CFE_TBL_OPT_CRITICAL -** \par #CFE_TBL_OPT_DBL_BUFFER cannot be combined with the following: -** -# #CFE_TBL_OPT_USR_DEF_ADDR -** -# #CFE_TBL_OPT_DUMP_ONLY -** -*/ + * @brief Invalid Options + * + * The calling Application has used an illegal combination of table options. + * A summary of the illegal combinations are as follows: + * \par #CFE_TBL_OPT_USR_DEF_ADDR cannot be combined with any of the following: + * -# #CFE_TBL_OPT_DBL_BUFFER + * -# #CFE_TBL_OPT_LOAD_DUMP + * -# #CFE_TBL_OPT_CRITICAL + * \par #CFE_TBL_OPT_DBL_BUFFER cannot be combined with the following: + * -# #CFE_TBL_OPT_USR_DEF_ADDR + * -# #CFE_TBL_OPT_DUMP_ONLY + * + */ #define CFE_TBL_ERR_INVALID_OPTIONS ((int32)0xcc000025) /** -** The calling Application attempted to register a table as "Critical". -** Table Services failed to create an appropriate Critical Data Store -** (See System Log for reason) to save the table contents. The table -** will be treated as a normal table from now on. -** -*/ + * @brief Not Critical Warning + * + * The calling Application attempted to register a table as "Critical". + * Table Services failed to create an appropriate Critical Data Store + * (See System Log for reason) to save the table contents. The table + * will be treated as a normal table from now on. + * + */ #define CFE_TBL_WARN_NOT_CRITICAL ((int32)0x4c000026) /** -** The calling Application registered a critical table whose previous -** contents were discovered in the Critical Data Store. The discovered -** contents were copied back into the newly registered table as the -** table's initial contents. -** \b NOTE: In this situation, the contents of the table are \b NOT -** validated using the table's validation function. -** -*/ + * @brief Recovered Table + * + * The calling Application registered a critical table whose previous + * contents were discovered in the Critical Data Store. The discovered + * contents were copied back into the newly registered table as the + * table's initial contents. + * \b NOTE: In this situation, the contents of the table are \b NOT + * validated using the table's validation function. + * + */ #define CFE_TBL_INFO_RECOVERED_TBL ((int32)0x4c000027) /** -** The selected table file failed validation for Spacecraft ID. -** The platform configuration file has verification of table files -** enabled for Spacecraft ID and an attempt was made to load a table -** with an invalid Spacecraft ID in the table file header. -** -*/ + * @brief Bad Spacecraft ID + * + * The selected table file failed validation for Spacecraft ID. + * The platform configuration file has verification of table files + * enabled for Spacecraft ID and an attempt was made to load a table + * with an invalid Spacecraft ID in the table file header. + * + */ #define CFE_TBL_ERR_BAD_SPACECRAFT_ID ((int32)0xcc000028) /** -** The selected table file failed validation for Processor ID. -** The platform configuration file has verification of table files -** enabled for Processor ID and an attempt was made to load a table -** with an invalid Processor ID in the table file header. -** -*/ + * @brief Bad Processor ID + * + * The selected table file failed validation for Processor ID. + * The platform configuration file has verification of table files + * enabled for Processor ID and an attempt was made to load a table + * with an invalid Processor ID in the table file header. + * + */ #define CFE_TBL_ERR_BAD_PROCESSOR_ID ((int32)0xcc000029) /** -** Error code indicating that the TBL command was not processed -** successfully and that the error counter should be incremented. -*/ + * @brief Message Error + * + * Error code indicating that the TBL command was not processed + * successfully and that the error counter should be incremented. + */ #define CFE_TBL_MESSAGE_ERROR ((int32)0xcc00002a) /** -** Current version of cFE does not have the function or the feature -** of the function implemented. This could be due to either an early -** build of the cFE for this platform or the platform does not support -** the specified feature. -** -*/ + * @brief Not Implemented + * + * Current version of cFE does not have the function or the feature + * of the function implemented. This could be due to either an early + * build of the cFE for this platform or the platform does not support + * the specified feature. + * + */ #define CFE_TBL_NOT_IMPLEMENTED ((int32)0xcc00ffff) @@ -1302,52 +1432,63 @@ */ /** -** Current version of cFE does not have the function or the feature -** of the function implemented. This could be due to either an early -** build of the cFE for this platform or the platform does not support -** the specified feature. -** -*/ + * @brief Not Implemented + * + * Current version of cFE does not have the function or the feature + * of the function implemented. This could be due to either an early + * build of the cFE for this platform or the platform does not support + * the specified feature. + * + */ #define CFE_TIME_NOT_IMPLEMENTED ((int32)0xce00ffff) /** -** One of the TIME Services API functions to set the time with data -** from an external time source has been called, but TIME Services -** has been commanded to not accept external time data. However, -** the command is still a signal for the Time Server to generate -** a "time at the tone" command packet using internal data. -** -*/ + * @brief Internal Only + * + * One of the TIME Services API functions to set the time with data + * from an external time source has been called, but TIME Services + * has been commanded to not accept external time data. However, + * the command is still a signal for the Time Server to generate + * a "time at the tone" command packet using internal data. + * + */ #define CFE_TIME_INTERNAL_ONLY ((int32)0xce000001) /** -** One of the TIME Services API functions to set the time with data -** from an external time source has been called, but TIME Services -** has determined that the new time data is invalid. However, -** the command is still a signal for the Time Server to generate -** a "time at the tone" command packet using internal data. -** -** Note that the test for invalid time update data only occurs if TIME -** Services has previously been commanded to set the clock state -** to "valid". -*/ + * @brief Out Of Range + * + * One of the TIME Services API functions to set the time with data + * from an external time source has been called, but TIME Services + * has determined that the new time data is invalid. However, + * the command is still a signal for the Time Server to generate + * a "time at the tone" command packet using internal data. + * + * Note that the test for invalid time update data only occurs if TIME + * Services has previously been commanded to set the clock state + * to "valid". + */ #define CFE_TIME_OUT_OF_RANGE ((int32)0xce000002) /** -** An attempt to register too many cFE Time Services Synchronization -** callbacks has been made. Only one callback function is allowed per -** application. It is expected that the application itself will -** distribute the single callback to child threads as needed. -** -*/ + * @brief Too Many Sync Callbacks + * + * An attempt to register too many cFE Time Services Synchronization + * callbacks has been made. Only one callback function is allowed per + * application. It is expected that the application itself will + * distribute the single callback to child threads as needed. + * + */ #define CFE_TIME_TOO_MANY_SYNCH_CALLBACKS ((int32)0xce000003) /** -** An attempt to unregister a cFE Time Services Synchronization -** callback has failed because the specified callback function was not -** located in the Synchronization Callback Registry. -** -*/ + * @brief Callback Not Registered + * + * An attempt to unregister a cFE Time Services Synchronization + * callback has failed because the specified callback function was not + * located in the Synchronization Callback Registry. + * + */ #define CFE_TIME_CALLBACK_NOT_REGISTERED ((int32)0xce000004) +/**@}*/ #endif /* _cfe_error_ */ diff --git a/fsw/cfe-core/src/inc/cfe_es.h b/fsw/cfe-core/src/inc/cfe_es.h index e7f357a37..4f81babbd 100644 --- a/fsw/cfe-core/src/inc/cfe_es.h +++ b/fsw/cfe-core/src/inc/cfe_es.h @@ -190,18 +190,20 @@ ** Type Definitions */ -/* -** Memory Handle type -*/ -typedef cpuaddr CFE_ES_MemHandle_t; /**< \brief Data type used to hold Handles of Memory Pools created via CFE_ES_PoolCreate and CFE_ES_PoolCreateNoSem */ +/** + * \brief Memory Handle type + * + * Data type used to hold Handles of Memory Pools + * created via CFE_ES_PoolCreate and CFE_ES_PoolCreateNoSem + */ +typedef cpuaddr CFE_ES_MemHandle_t; -/* -** -** CFE_ES_AppInfo_t is a structure that is used to provide -** information about an app. It is primarily used for the QueryOne and -** QueryAll Commands. -** -*/ +/** + * \brief Application Information + * + * Structure that is used to provide information about an app. + * It is primarily used for the QueryOne and QueryAll Commands. + */ typedef struct { uint32 AppId; /**< \cfetlmmnemonic \ES_APP_ID @@ -252,22 +254,22 @@ typedef struct } CFE_ES_AppInfo_t; -/* -** Task Info Type -*/ +/** + * \brief Task Info + */ typedef struct { uint32 TaskId; /**< \brief Task Id */ - uint32 ExecutionCounter; /**K \brief Task Execution Counter */ + uint32 ExecutionCounter; /**< \brief Task Execution Counter */ uint8 TaskName[OS_MAX_API_NAME]; /**< \brief Task Name */ uint32 AppId; /**< \brief Parent Application ID */ uint8 AppName[OS_MAX_API_NAME]; /**< \brief Parent Application Name */ } CFE_ES_TaskInfo_t; -/* -** Memory Pool Statistics data type -*/ +/** + * \brief Block statistics + */ typedef struct { uint32 BlockSize; /**< \brief Number of bytes in each of these blocks */ @@ -275,6 +277,9 @@ typedef struct uint32 NumFree; /**< \brief Number of Memory Blocks of this size that are free */ } CFE_ES_BlockStats_t; +/** + * \brief Memory Pool Statistics + */ typedef struct { uint32 PoolSize; /**< \cfetlmmnemonic \ES_POOLSIZE @@ -289,11 +294,16 @@ typedef struct \brief Contains stats on each block size */ } CFE_ES_MemPoolStats_t; -/* -** CDS Handle type -*/ -typedef cpuaddr CFE_ES_CDSHandle_t; /**< \brief Data type used to hold Handles of Critical Data Stores. See CFE_ES_RegisterCDS */ +/** + * \brief CDS Handle type + * + * Data type used to hold Handles of Critical Data Stores. See #CFE_ES_RegisterCDS + */ +typedef cpuaddr CFE_ES_CDSHandle_t; +/** + * \brief CDS Register Dump Record + */ typedef struct { CFE_ES_CDSHandle_t Handle; /**< \brief Handle of CDS */ @@ -310,19 +320,23 @@ typedef void (*CFE_ES_ChildTaskMainFuncPtr_t)(void); /**< \brief Required Protot typedef int32 (*CFE_ES_LibraryEntryFuncPtr_t)(uint32 LibId); /**< \brief Required Prototype of Library Initialization Functions */ /** + * \brief Pool Alignement + * * Union that can be used for minimum memory alignment of ES memory pools on the target. * It contains the longest native data types such that the alignment of this structure * should reflect the largest possible alignment requirements for any data on this processor. */ typedef union { - void *Ptr; + void *Ptr; /**< \brief Aligned pointer */ /* note -- native types (int/double) are intentional here */ - long long int LongInt; - long double LongDouble; + long long int LongInt; /**< \brief Aligned Long Integer */ + long double LongDouble; /**< \brief Aligned Long Double */ } CFE_ES_PoolAlign_t; /** + * \brief Static Pool Type + * * A macro to help instantiate static memory pools that are correctly aligned. * This resolves to a union type that contains a member called "Data" that will * be correctly aligned to be a memory pool and sized according to the argument. @@ -336,6 +350,9 @@ typedef union /*****************************************************************************/ +/** @defgroup CFEAPIESEntryExit cFE Entry/Exit APIs + * @{ + */ /*****************************************************************************/ /** @@ -362,35 +379,6 @@ typedef union ******************************************************************************/ void CFE_ES_Main(uint32 StartType, uint32 StartSubtype, uint32 ModeId , const char *StartFilePath ); -/*****************************************************************************/ -/** -** \brief Return the most recent Reset Type -** -** \par Description -** Provides the caller with codes that identifies the type of Reset -** the processor most recently underwent. The caller can also obtain -** information on what caused the reset by supplying a pointer to a -** variable that will be filled with the Reset Sub-Type. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \param[in] ResetSubtypePtr Pointer to \c uint32 type variable in which the Reset Sub-Type will be stored. -** The caller can set this pointer to NULL if the Sub-Type is of no interest. -** -** \param[out] *ResetSubtypePtr If the provided pointer was not \c NULL, the Reset Sub-Type is stored at the given address. -** For a list of possible Sub-Type values, see \link #CFE_PSP_RST_SUBTYPE_POWER_CYCLE "Reset Sub-Types" \endlink. -** -** \returns -** \retcode #CFE_PSP_RST_TYPE_POWERON \retdesc \copydoc CFE_PSP_RST_TYPE_POWERON \endcode -** \retcode #CFE_PSP_RST_TYPE_PROCESSOR \retdesc \copydoc CFE_PSP_RST_TYPE_PROCESSOR \endcode -** \endreturns -** -** \sa #CFE_ES_GetAppID, #CFE_ES_GetAppIDByName, #CFE_ES_GetAppName, #CFE_ES_GetTaskInfo -** -******************************************************************************/ -int32 CFE_ES_GetResetType(uint32 *ResetSubtypePtr); - /*****************************************************************************/ /** ** \brief Reset the cFE Core and all cFE Applications @@ -407,15 +395,20 @@ int32 CFE_ES_GetResetType(uint32 *ResetSubtypePtr); ** \arg #CFE_PSP_RST_TYPE_POWERON - Causes all memory to be cleared ** \arg #CFE_PSP_RST_TYPE_PROCESSOR - Attempts to retain volatile disk, critical data store and user reserved memory. ** -** \returns -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \retcode #CFE_ES_NOT_IMPLEMENTED \retdesc \copydoc CFE_ES_NOT_IMPLEMENTED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_NOT_IMPLEMENTED \copybrief CFE_ES_NOT_IMPLEMENTED ** ** \sa #CFE_ES_Main ** ******************************************************************************/ int32 CFE_ES_ResetCFE(uint32 ResetType); +/**@}*/ + +/** @defgroup CFEAPIESAppControl cFE Application Control APIs + * @{ + */ /*****************************************************************************/ /** @@ -429,9 +422,7 @@ int32 CFE_ES_ResetCFE(uint32 ResetType); ** ** \param[in] AppID Identifies the application to be reset. ** -** \returns -** \retcode #CFE_ES_NOT_IMPLEMENTED \retdesc \copydoc CFE_ES_NOT_IMPLEMENTED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes ** ** \sa #CFE_ES_ReloadApp, #CFE_ES_DeleteApp ** @@ -458,9 +449,7 @@ int32 CFE_ES_RestartApp(uint32 AppID); ** ** \param[in] AppFileName Identifies the new file to start. ** -** \returns -** \retcode #CFE_ES_NOT_IMPLEMENTED \retdesc \copydoc CFE_ES_NOT_IMPLEMENTED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes ** ** \sa #CFE_ES_RestartApp, #CFE_ES_DeleteApp, #CFE_ES_START_APP_CC ** @@ -479,14 +468,17 @@ int32 CFE_ES_ReloadApp(uint32 AppID, const char *AppFileName); ** ** \param[in] AppID Identifies the application to be reset. ** -** \returns -** \retcode #CFE_ES_NOT_IMPLEMENTED \retdesc \copydoc CFE_ES_NOT_IMPLEMENTED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes ** ** \sa #CFE_ES_RestartApp, #CFE_ES_ReloadApp ** ******************************************************************************/ int32 CFE_ES_DeleteApp(uint32 AppID); +/**@}*/ + +/** @defgroup CFEAPIESAppBehavior cFE Application Behavior APIs + * @{ + */ /*****************************************************************************/ /** @@ -500,9 +492,7 @@ int32 CFE_ES_DeleteApp(uint32 AppID); ** ** \param[in] ExitStatus . ** -** \returns -** \retcode #CFE_ES_NOT_IMPLEMENTED \retdesc \copydoc CFE_ES_NOT_IMPLEMENTED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes ** ** \sa #CFE_ES_RunLoop, #CFE_ES_RegisterApp ** @@ -523,14 +513,13 @@ void CFE_ES_ExitApp(uint32 ExitStatus); ** ** \param[in] ExitStatus A pointer to a variable containing the Application's ** desired run status. Acceptable values are: -** \arg #CFE_ES_RunStatus_APP_RUN - \copydoc CFE_ES_RunStatus_APP_RUN -** \arg #CFE_ES_RunStatus_APP_EXIT - \copydoc CFE_ES_RunStatus_APP_EXIT -** \arg #CFE_ES_RunStatus_APP_ERROR - \copydoc CFE_ES_RunStatus_APP_ERROR +** \arg #CFE_ES_RunStatus_APP_RUN - \copybrief CFE_ES_RunStatus_APP_RUN +** \arg #CFE_ES_RunStatus_APP_EXIT - \copybrief CFE_ES_RunStatus_APP_EXIT +** \arg #CFE_ES_RunStatus_APP_ERROR - \copybrief CFE_ES_RunStatus_APP_ERROR ** -** \returns -** \retcode true \retdesc The application should continue executing \endcode -** \retcode false \retdesc The application should terminate itself \endcode -** \endreturns +** \return Boolean indicating application should continue running +** \retval true Application should continue running +** \retval false Application should not continue running ** ** \sa #CFE_ES_ExitApp, #CFE_ES_RegisterApp ** @@ -545,7 +534,7 @@ bool CFE_ES_RunLoop(uint32 *ExitStatus); ** This is the API that allows an app to wait for the rest of the apps ** to complete a given stage of initialization before continuing. ** -** This gives finer grained control than the "CFE_ES_WaitForStartupSync()" call. +** This gives finer grained control than #CFE_ES_WaitForStartupSync ** ** \par Assumptions, External Events, and Notes: ** This API assumes that the caller has also been initialized sufficiently @@ -560,10 +549,9 @@ bool CFE_ES_RunLoop(uint32 *ExitStatus); ** ** \param[in] MinSystemState Determine the state of the App ** -** \returns -** \retcode #CFE_SUCCESS \retdesc State successfully achieved \endcode -** \retcode #CFE_ES_OPERATION_TIMED_OUT \retdesc Timeout was reached \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS State successfully achieved +** \retval #CFE_ES_OPERATION_TIMED_OUT Timeout was reached ** ** \sa #CFE_ES_RunLoop ** @@ -581,7 +569,7 @@ int32 CFE_ES_WaitForSystemState(uint32 MinSystemState, uint32 TimeOutMillisecond ** to wait until applications exist and are running before sending out ** packets to them. ** -** This is a specialized wrapper for CFE_ES_WaitForSystemState() for compatibility +** This is a specialized wrapper for CFE_ES_WaitForSystemState for compatibility ** with applications using this API. ** ** \par Assumptions, External Events, and Notes: @@ -602,11 +590,6 @@ int32 CFE_ES_WaitForSystemState(uint32 MinSystemState, uint32 TimeOutMillisecond ******************************************************************************/ void CFE_ES_WaitForStartupSync(uint32 TimeOutMilliseconds); - -/* -** Application Management functions -*/ - /*****************************************************************************/ /** ** \brief Registers a cFE Application with the Executive Services @@ -617,17 +600,66 @@ void CFE_ES_WaitForStartupSync(uint32 TimeOutMilliseconds); ** \par Assumptions, External Events, and Notes: ** NOTE: This function \b MUST be called before any other cFE API functions are called. ** -** \returns -** \retstmt Return codes from #OS_TaskRegister \endcode -** \retstmt Return codes from #OS_BinSemTake \endcode -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes ** ** \sa #CFE_ES_ExitApp, #CFE_ES_RunLoop ** ******************************************************************************/ int32 CFE_ES_RegisterApp(void); +/*****************************************************************************/ +/** +** \ingroup CFEAPIESAppBehavior +** \brief Increments the execution counter for the calling task +** +** \par Description +** This routine increments the execution counter that is stored for +** the calling task. It can be called from cFE Application main tasks, child +** tasks, or cFE Core application main tasks. Normally, the call is not +** necessary from a cFE Application, since the CFE_ES_RunLoop call increments +** the counter for the Application. +** +** \par Assumptions, External Events, and Notes: +** NOTE: This API is not needed for Appplications that call the CFE_ES_RunLoop call. +** +** \sa #CFE_ES_RunLoop +** +******************************************************************************/ +void CFE_ES_IncrementTaskCounter(void); +/**@}*/ + +/** @defgroup CFEAPIESInfo cFE Information APIs + * @{ + */ + +/*****************************************************************************/ +/** +** \brief Return the most recent Reset Type +** +** \par Description +** Provides the caller with codes that identifies the type of Reset +** the processor most recently underwent. The caller can also obtain +** information on what caused the reset by supplying a pointer to a +** variable that will be filled with the Reset Sub-Type. +** +** \par Assumptions, External Events, and Notes: +** None +** +** \param[in] ResetSubtypePtr Pointer to \c uint32 type variable in which the Reset Sub-Type will be stored. +** The caller can set this pointer to NULL if the Sub-Type is of no interest. +** +** \param[out] *ResetSubtypePtr If the provided pointer was not \c NULL, the Reset Sub-Type is stored at the given address. +** For a list of possible Sub-Type values, see \link #CFE_PSP_RST_SUBTYPE_POWER_CYCLE "Reset Sub-Types" \endlink. +** +** \return Processor reset type +** \retval #CFE_PSP_RST_TYPE_POWERON \copybrief CFE_PSP_RST_TYPE_POWERON +** \retval #CFE_PSP_RST_TYPE_PROCESSOR \copybrief CFE_PSP_RST_TYPE_PROCESSOR +** +** \sa #CFE_ES_GetAppID, #CFE_ES_GetAppIDByName, #CFE_ES_GetAppName, #CFE_ES_GetTaskInfo +** +******************************************************************************/ +int32 CFE_ES_GetResetType(uint32 *ResetSubtypePtr); + /*****************************************************************************/ /** ** \brief Get an Application ID for the calling Application @@ -642,11 +674,10 @@ int32 CFE_ES_RegisterApp(void); ** ** \param[out] *AppIdPtr Application ID of the calling Application. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_APPID \retdesc \copydoc CFE_ES_ERR_APPID \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_APPID \copybrief CFE_ES_ERR_APPID +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_ES_GetResetType, #CFE_ES_GetAppIDByName, #CFE_ES_GetAppName, #CFE_ES_GetTaskInfo ** @@ -670,11 +701,10 @@ int32 CFE_ES_GetAppID(uint32 *AppIdPtr); ** ** \param[out] *AppIdPtr Application ID of the calling Application. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_ES_GetResetType, #CFE_ES_GetAppID, #CFE_ES_GetAppName, #CFE_ES_GetTaskInfo ** @@ -705,10 +735,9 @@ int32 CFE_ES_GetAppIDByName(uint32 *AppIdPtr, const char *AppName); ** \param[out] *AppName Null terminated Application name of the Application associated with the ** specified Application ID. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_APPID \retdesc \copydoc CFE_ES_ERR_APPID \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_APPID \copybrief CFE_ES_ERR_APPID ** ** \sa #CFE_ES_GetResetType, #CFE_ES_GetAppID, #CFE_ES_GetAppIDByName, #CFE_ES_GetTaskInfo ** @@ -735,11 +764,10 @@ int32 CFE_ES_GetAppName(char *AppName, uint32 AppId, uint32 BufferLength); ** \param[out] *AppInfo Filled out \c CFE_ES_AppInfo_t structure containing the ** App Name, and application memory addresses among other fields. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_APPID \retdesc \copydoc CFE_ES_ERR_APPID \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_APPID \copybrief CFE_ES_ERR_APPID +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_ES_GetResetType, #CFE_ES_GetAppID, #CFE_ES_GetAppIDByName, #CFE_ES_GetAppName ** @@ -766,20 +794,21 @@ int32 CFE_ES_GetAppInfo(CFE_ES_AppInfo_t *AppInfo, uint32 AppId); ** \param[out] *TaskInfo Filled out \c CFE_ES_TaskInfo_t structure containing the ** Task Name, Parent App Name, Parent App ID among other fields. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_TASKID \retdesc \copydoc CFE_ES_ERR_TASKID \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_TASKID \copybrief CFE_ES_ERR_TASKID +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_ES_GetResetType, #CFE_ES_GetAppID, #CFE_ES_GetAppIDByName, #CFE_ES_GetAppName ** ******************************************************************************/ int32 CFE_ES_GetTaskInfo(CFE_ES_TaskInfo_t *TaskInfo, uint32 TaskId); +/**@}*/ + +/** @defgroup CFEAPIESChildTask cFE Child Task APIs + * @{ + */ -/* -** Task management functions -*/ /*****************************************************************************/ /** ** \brief Registers a cFE Child task associated with a cFE Application @@ -791,10 +820,9 @@ int32 CFE_ES_GetTaskInfo(CFE_ES_TaskInfo_t *TaskInfo, uint32 TaskId); ** \par Assumptions, External Events, and Notes: ** NOTE: This API \b MUST be called by the Child Task before any other cFE API calls are made. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_CHILD_TASK_REGISTER \retdesc \copydoc CFE_ES_ERR_CHILD_TASK_REGISTER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_CHILD_TASK_REGISTER \copybrief CFE_ES_ERR_CHILD_TASK_REGISTER ** ** \sa #CFE_ES_CreateChildTask, #CFE_ES_DeleteChildTask, #CFE_ES_ExitChildTask ** @@ -833,10 +861,9 @@ int32 CFE_ES_RegisterChildTask(void); ** ** \param[out] *TaskIdPtr The Task ID of the newly created child task. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_CHILD_TASK_CREATE \retdesc \copydoc CFE_ES_ERR_CHILD_TASK_CREATE \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_CHILD_TASK_CREATE \copybrief CFE_ES_ERR_CHILD_TASK_CREATE ** ** \sa #CFE_ES_RegisterChildTask, #CFE_ES_DeleteChildTask, #CFE_ES_ExitChildTask ** @@ -862,9 +889,9 @@ int32 CFE_ES_CreateChildTask(uint32 *TaskIdPtr, ** ** \param[in] TaskId The task ID previously obtained when the Child Task was created with the #CFE_ES_CreateChildTask API. ** -** \returns -** \retcode #CFE_ES_NOT_IMPLEMENTED \retdesc \copydoc CFE_ES_NOT_IMPLEMENTED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_NOT_IMPLEMENTED \copybrief CFE_ES_NOT_IMPLEMENTED ** ** \sa #CFE_ES_RegisterChildTask, #CFE_ES_CreateChildTask, #CFE_ES_ExitChildTask ** @@ -882,45 +909,19 @@ int32 CFE_ES_DeleteChildTask(uint32 TaskId); ** \par Assumptions, External Events, and Notes: ** This function cannot be called from an Application's Main Task. ** -** \returns -** \retstmt -** This function does not return a value, but if it does return +** \return This function does not return a value, but if it does return ** at all, it is assumed that the Task was either unregistered or -** this function was called from a cFE Application's main task. \endcode -** \endreturns +** this function was called from a cFE Application's main task. ** ** \sa #CFE_ES_RegisterChildTask, #CFE_ES_CreateChildTask, #CFE_ES_DeleteChildTask ** ******************************************************************************/ void CFE_ES_ExitChildTask(void); +/**@}*/ -/*****************************************************************************/ -/** -** \brief Increments the execution counter for the calling task -** -** \par Description -** This routine increments the execution counter that is stored for -** the calling task. It can be called from cFE Application main tasks, child -** tasks, or cFE Core application main tasks. Normally, the call is not -** necessary from a cFE Application, since the CFE_ES_RunLoop call increments -** the counter for the Application. -** -** \par Assumptions, External Events, and Notes: -** NOTE: This API is not needed for Appplications that call the CFE_ES_RunLoop call. -** -** \returns -** \retstmt -** This function does not return a value. \endcode -** \endreturns -** -** \sa #CFE_ES_RunLoop -** -******************************************************************************/ -void CFE_ES_IncrementTaskCounter(void); - -/* -** Log management functions -*/ +/** @defgroup CFEAPIESMisc cFE Miscellaneous APIs + * @{ + */ /*****************************************************************************/ /** @@ -939,12 +940,9 @@ void CFE_ES_IncrementTaskCounter(void); ** \param[in] SpecStringPtr The format string for the log message. ** This is similar to the format string for a printf() call. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_SYS_LOG_FULL \retdesc \copydoc CFE_ES_ERR_SYS_LOG_FULL \endcode -** \endreturns -** -** \sa +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_SYS_LOG_FULL \copybrief CFE_ES_ERR_SYS_LOG_FULL ** ******************************************************************************/ int32 CFE_ES_WriteToSysLog(const char *SpecStringPtr, ...) OS_PRINTF(1,2); @@ -973,16 +971,35 @@ int32 CFE_ES_WriteToSysLog(const char *SpecStringPtr, ...) OS_PRINTF(1,2); ** \arg \c CFE_MISSION_ES_CRC_16 - a CRC-16 algorithm ** \arg \c CFE_MISSION_ES_CRC_32 - (not currently implemented) ** -** \returns -** \retstmt The result of the CRC calculation on the specified memory block. \endcode -** \endreturns +** \return The result of the CRC calculation on the specified memory block, or error code \ref CFEReturnCodes ** ******************************************************************************/ uint32 CFE_ES_CalculateCRC(const void *DataPtr, uint32 DataLength, uint32 InputCRC, uint32 TypeCRC); -/* -** Critical Data Store API -*/ +/*****************************************************************************/ +/** +** \ingroup CFEAPIESMisc +** \brief Process an exception detected by the underlying OS/PSP +** +** \par Description +** This hook routine is called from the PSP when an exception occurs +** +** \par Assumptions, External Events, and Notes: +** None. +** +** \param[in] HostTaskId The OS (not OSAL) task ID +** \param[in] ReasonString Identifier from PSP +** \param[in] ContextPointer Context data from PSP +** \param[in] ContextSize Size of context data from PSP +** +******************************************************************************/ +void CFE_ES_ProcessCoreException(uint32 HostTaskId, const char *ReasonString, + const uint32 *ContextPointer, uint32 ContextSize); +/**@}*/ + +/** @defgroup CFEAPIESCritData cFE Critical Data Store APIs + * @{ + */ /*****************************************************************************/ /** @@ -1005,14 +1022,13 @@ uint32 CFE_ES_CalculateCRC(const void *DataPtr, uint32 DataLength, uint32 InputC ** \param[out] *HandlePtr The handle of the CDS block that can be used in ** #CFE_ES_CopyToCDS and #CFE_ES_RestoreFromCDS. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc The memory block was successfully created in the CDS. \endcode -** \retcode #CFE_ES_NOT_IMPLEMENTED \retdesc The processor does not support a Critical Data Store. \endcode -** \retcode #CFE_ES_CDS_ALREADY_EXISTS \retdesc \copydoc CFE_ES_CDS_ALREADY_EXISTS \endcode -** \retcode #CFE_ES_CDS_INVALID_SIZE \retdesc \copydoc CFE_ES_CDS_INVALID_SIZE \endcode -** \retcode #CFE_ES_CDS_INVALID_NAME \retdesc \copydoc CFE_ES_CDS_INVALID_NAME \endcode -** \retcode #CFE_ES_CDS_REGISTRY_FULL \retdesc \copydoc CFE_ES_CDS_REGISTRY_FULL \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS The memory block was successfully created in the CDS. +** \retval #CFE_ES_NOT_IMPLEMENTED The processor does not support a Critical Data Store. +** \retval #CFE_ES_CDS_ALREADY_EXISTS \copybrief CFE_ES_CDS_ALREADY_EXISTS +** \retval #CFE_ES_CDS_INVALID_SIZE \copybrief CFE_ES_CDS_INVALID_SIZE +** \retval #CFE_ES_CDS_INVALID_NAME \copybrief CFE_ES_CDS_INVALID_NAME +** \retval #CFE_ES_CDS_REGISTRY_FULL \copybrief CFE_ES_CDS_REGISTRY_FULL ** ** \sa #CFE_ES_CopyToCDS, #CFE_ES_RestoreFromCDS ** @@ -1035,11 +1051,10 @@ int32 CFE_ES_RegisterCDS(CFE_ES_CDSHandle_t *HandlePtr, int32 BlockSize, const c ** ** \param[in] DataToCopy A Pointer to the block of memory to be copied into the CDS. ** -** \returns -** \retcode #OS_SUCCESS \retdesc \copydoc OS_SUCCESS \endcode -** \retcode #CFE_ES_ERR_MEM_HANDLE \retdesc \copydoc CFE_ES_ERR_MEM_HANDLE \endcode -** \retcode #OS_ERROR \retdesc Problem with handle or a size mismatch \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #OS_SUCCESS \copybrief OS_SUCCESS +** \retval #CFE_ES_ERR_MEM_HANDLE \copybrief CFE_ES_ERR_MEM_HANDLE +** \retval #OS_ERROR Problem with handle or a size mismatch ** ** \sa #CFE_ES_RegisterCDS, #CFE_ES_RestoreFromCDS ** @@ -1067,20 +1082,20 @@ int32 CFE_ES_CopyToCDS(CFE_ES_CDSHandle_t Handle, void *DataToCopy); ** ** \param[out] *RestoreToMemory The contents of the specified CDS. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_CDS_BLOCK_CRC_ERR \retdesc \copydoc CFE_ES_CDS_BLOCK_CRC_ERR \endcode -** \retcode #OS_ERROR \retdesc Problem with handle or a size mismatch \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_CDS_BLOCK_CRC_ERR \copybrief CFE_ES_CDS_BLOCK_CRC_ERR +** \retval #OS_ERROR Problem with handle or a size mismatch ** ** \sa #CFE_ES_RegisterCDS, #CFE_ES_CopyToCDS ** */ int32 CFE_ES_RestoreFromCDS(void *RestoreToMemory, CFE_ES_CDSHandle_t Handle); +/**@}*/ -/* -** Memory Allocation/Deallocation API -*/ +/** @defgroup CFEAPIESMemManage cFE Memory Manager APIs + * @{ + */ /*****************************************************************************/ /** @@ -1104,10 +1119,9 @@ int32 CFE_ES_RestoreFromCDS(void *RestoreToMemory, CFE_ES_CDSHandle_t Handle); ** ** \param[out] *HandlePtr The memory pool handle. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateEx, #CFE_ES_GetPoolBuf, #CFE_ES_PutPoolBuf, #CFE_ES_GetMemPoolStats ** @@ -1136,10 +1150,9 @@ int32 CFE_ES_PoolCreateNoSem(CFE_ES_MemHandle_t *HandlePtr, uint8 *MemPtr, uint3 ** ** \param[out] *HandlePtr The memory pool handle. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_PoolCreateNoSem, #CFE_ES_PoolCreateEx, #CFE_ES_GetPoolBuf, #CFE_ES_PutPoolBuf, #CFE_ES_GetMemPoolStats ** @@ -1177,10 +1190,9 @@ int32 CFE_ES_PoolCreate(CFE_ES_MemHandle_t *HandlePtr, uint8 *MemPtr, uint32 Siz ** ** \param[out] *HandlePtr The memory pool handle. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateNoSem, #CFE_ES_GetPoolBuf, #CFE_ES_PutPoolBuf, #CFE_ES_GetMemPoolStats ** @@ -1205,12 +1217,9 @@ int32 CFE_ES_PoolCreateEx(CFE_ES_MemHandle_t *HandlePtr, uint8 *MemPtr, uint32 S ** ** \param[out] *BufPtr The address of the requested buffer. ** -** \returns -** \retstmt When successful, the return value is a positive number and is the number of bytes -** actually allocated for the buffer. \endcode -** \retcode #CFE_ES_ERR_MEM_HANDLE \retdesc \copydoc CFE_ES_ERR_MEM_HANDLE \endcode -** \retcode #CFE_ES_ERR_MEM_BLOCK_SIZE \retdesc \copydoc CFE_ES_ERR_MEM_BLOCK_SIZE \endcode -** \endreturns +** \return Bytes Allocated, or error code \ref CFEReturnCodes +** \retval #CFE_ES_ERR_MEM_HANDLE \copybrief CFE_ES_ERR_MEM_HANDLE +** \retval #CFE_ES_ERR_MEM_BLOCK_SIZE \copybrief CFE_ES_ERR_MEM_BLOCK_SIZE ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateNoSem, #CFE_ES_PoolCreateEx, #CFE_ES_PutPoolBuf, #CFE_ES_GetMemPoolStats, #CFE_ES_GetPoolBufInfo ** @@ -1231,11 +1240,10 @@ int32 CFE_ES_GetPoolBuf(uint32 **BufPtr, CFE_ES_MemHandle_t HandlePtr, uint32 Si ** ** \param[in] BufPtr A pointer to the memory buffer to provide status for. ** -** \returns -** \retstmt When successful, the return value is a positive number and is the number of bytes actually allocated. \endcode -** \retcode #CFE_ES_ERR_MEM_HANDLE \retdesc \copydoc CFE_ES_ERR_MEM_HANDLE \endcode -** \retcode #CFE_ES_BUFFER_NOT_IN_POOL \retdesc \copydoc CFE_ES_BUFFER_NOT_IN_POOL \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_MEM_HANDLE \copybrief CFE_ES_ERR_MEM_HANDLE +** \retval #CFE_ES_BUFFER_NOT_IN_POOL \copybrief CFE_ES_BUFFER_NOT_IN_POOL ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateNoSem, #CFE_ES_PoolCreateEx, #CFE_ES_GetPoolBuf, #CFE_ES_GetMemPoolStats, #CFE_ES_PutPoolBuf ** @@ -1256,10 +1264,8 @@ int32 CFE_ES_GetPoolBufInfo(CFE_ES_MemHandle_t HandlePtr, uint32 *BufPtr); ** ** \param[in] BufPtr A pointer to the memory buffer to be released. ** -** \returns -** \retstmt When successful, the return value is a positive number and is the number of bytes actually released. \endcode -** \retcode #CFE_ES_ERR_MEM_HANDLE \retdesc \copydoc CFE_ES_ERR_MEM_HANDLE \endcode -** \endreturns +** \return Bytes released, or error code \ref CFEReturnCodes +** \retval #CFE_ES_ERR_MEM_HANDLE \copybrief CFE_ES_ERR_MEM_HANDLE ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateNoSem, #CFE_ES_PoolCreateEx, #CFE_ES_GetPoolBuf, #CFE_ES_GetMemPoolStats, #CFE_ES_GetPoolBufInfo ** @@ -1285,19 +1291,19 @@ int32 CFE_ES_PutPoolBuf(CFE_ES_MemHandle_t HandlePtr, uint32 *BufPtr); ** ** \param[out] *BufPtr Memory Pool Statistics stored in given data structure. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_ERR_MEM_HANDLE \retdesc \copydoc CFE_ES_ERR_MEM_HANDLE \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_MEM_HANDLE \copybrief CFE_ES_ERR_MEM_HANDLE ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateNoSem, #CFE_ES_PoolCreateEx, #CFE_ES_GetPoolBuf, #CFE_ES_PutPoolBuf ** ******************************************************************************/ int32 CFE_ES_GetMemPoolStats(CFE_ES_MemPoolStats_t *BufPtr, CFE_ES_MemHandle_t Handle); +/**@}*/ -/* -** Performance Log API -*/ +/** @defgroup CFEAPIESPerfMon cFE Performance Monitor APIs + * @{ + */ /*****************************************************************************/ /** @@ -1340,7 +1346,7 @@ int32 CFE_ES_GetMemPoolStats(CFE_ES_MemPoolStats_t *BufPtr, CFE_ES_MemHandle_t /*****************************************************************************/ /** -** \brief Function called by CFE_ES_PerfLogEntry and CFE_ES_PerfLogExit macros +** \brief Function called by #CFE_ES_PerfLogEntry and #CFE_ES_PerfLogExit macros ** ** \par Description ** This function logs the entry and exit marker for the specified @@ -1357,10 +1363,11 @@ int32 CFE_ES_GetMemPoolStats(CFE_ES_MemPoolStats_t *BufPtr, CFE_ES_MemHandle_t ** ******************************************************************************/ void CFE_ES_PerfLogAdd(uint32 Marker, uint32 EntryExit); +/**@}*/ -/* -** Generic Counter API -*/ +/** @defgroup CFEAPIESGenCount cFE Generic Counter APIs + * @{ + */ /*****************************************************************************/ /** @@ -1376,10 +1383,9 @@ void CFE_ES_PerfLogAdd(uint32 Marker, uint32 EntryExit); ** ** \param[out] *CounterIdPtr The Counter Id of the newly created counter. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_IncrementGenCounter, #CFE_ES_DeleteGenCounter, #CFE_ES_SetGenCount, #CFE_ES_GetGenCount, #CFE_ES_GetGenCounterIDByName ** @@ -1398,10 +1404,9 @@ int32 CFE_ES_RegisterGenCounter(uint32 *CounterIdPtr, const char *CounterName); ** ** \param[in] CounterId The Counter Id of the newly created counter. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_IncrementGenCounter, #CFE_ES_RegisterGenCounter, #CFE_ES_SetGenCount, #CFE_ES_GetGenCount, #CFE_ES_GetGenCounterIDByName ** @@ -1420,10 +1425,9 @@ int32 CFE_ES_DeleteGenCounter(uint32 CounterId); ** ** \param[in] CounterId The Counter to be incremented. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_RegisterGenCounter, #CFE_ES_DeleteGenCounter, #CFE_ES_SetGenCount, #CFE_ES_GetGenCount, #CFE_ES_GetGenCounterIDByName ** @@ -1444,10 +1448,9 @@ int32 CFE_ES_IncrementGenCounter(uint32 CounterId); ** ** \param[in] Count The new value of the Counter. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_RegisterGenCounter, #CFE_ES_DeleteGenCounter, #CFE_ES_IncrementGenCounter, #CFE_ES_GetGenCount, #CFE_ES_GetGenCounterIDByName ** @@ -1468,10 +1471,9 @@ int32 CFE_ES_SetGenCount(uint32 CounterId, uint32 Count); ** ** \param[in] *Count The value of the Counter. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_RegisterGenCounter, #CFE_ES_DeleteGenCounter, #CFE_ES_SetGenCount, #CFE_ES_IncrementGenCounter, #CFE_ES_GetGenCounterIDByName ** @@ -1493,34 +1495,13 @@ int32 CFE_ES_GetGenCount(uint32 CounterId, uint32 *Count); ** ** \param[out] *CounterIdPtr The Counter Id for the given name. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_ES_BAD_ARGUMENT \retdesc \copydoc CFE_ES_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT ** ** \sa #CFE_ES_RegisterGenCounter, #CFE_ES_DeleteGenCounter, #CFE_ES_SetGenCount, #CFE_ES_IncrementGenCounter, #CFE_ES_GetGenCount ******************************************************************************/ int32 CFE_ES_GetGenCounterIDByName(uint32 *CounterIdPtr, const char *CounterName); - -/*****************************************************************************/ -/** -** \brief Process an exception detected by the underlying OS/PSP -** -** \par Description -** This hook routine is called from the PSP when an exception occurs -** -** \par Assumptions, External Events, and Notes: -** None. -** -** \param[in] HostTaskId The OS (not OSAL) task ID -** \param[in] ReasonString Identifier from PSP -** \param[in] ContextPointer Context data from PSP -** \param[in] ContextSize Size of context data from PSP -** -******************************************************************************/ -void CFE_ES_ProcessCoreException(uint32 HostTaskId, const char *ReasonString, - const uint32 *ContextPointer, uint32 ContextSize); - - +/**@}*/ #endif /* _cfe_es_ */ diff --git a/fsw/cfe-core/src/inc/cfe_es_events.h b/fsw/cfe-core/src/inc/cfe_es_events.h index 3ba4c8528..848ebf33b 100644 --- a/fsw/cfe-core/src/inc/cfe_es_events.h +++ b/fsw/cfe-core/src/inc/cfe_es_events.h @@ -959,8 +959,7 @@ ** This event message is generated in response to receiving an Executive Services ** \link #CFE_ES_START_PERF_DATA_CC Start Performance Analyzer Data Collection Command \endlink ** -** The \c 'd' field identifies the requested trigger mode. Valid values are \link #CFE_ES_PerfMode_t CFE_ES_PERF_TRIGGER_START (0) \endlink, -** \link #CFE_ES_PerfMode_t CFE_ES_PERF_TRIGGER_CENTER (1) \endlink, and \link #CFE_ES_PerfMode_t CFE_ES_PERF_TRIGGER_END (2) \endlink +** The \c 'd' field identifies the requested trigger mode as defined by CFE_ES_PerfMode_t. **/ #define CFE_ES_PERF_STARTCMD_EID 57 @@ -988,10 +987,8 @@ ** Start Performance Analyzer Data Collection Command \endlink command is received with a bad ** value for the requested trigger mode. ** -** The first \c 'd' field identifies the received trigger mode value. -** The second and third \c 'd' fields specify the valid range of values for the trigger mode. Valid values -** are #CFE_ES_PerfMode_t CFE_ES_PERF_TRIGGER_START (0), #CFE_ES_PerfMode_t CFE_ES_PERF_TRIGGER_CENTER (1), and -** #CFE_ES_PerfMode_t CFE_ES_PERF_TRIGGER_END (2). +** The first \c 'd' field identifies the received trigger mode value as defined by CFE_ES_PerfMode_t. +** The second and third \c 'd' fields specify the valid range of values for the trigger mode. **/ #define CFE_ES_PERF_STARTCMD_TRIG_ERR_EID 59 diff --git a/fsw/cfe-core/src/inc/cfe_es_extern_typedefs.h b/fsw/cfe-core/src/inc/cfe_es_extern_typedefs.h index 85b662cb4..b84f3a143 100644 --- a/fsw/cfe-core/src/inc/cfe_es_extern_typedefs.h +++ b/fsw/cfe-core/src/inc/cfe_es_extern_typedefs.h @@ -218,7 +218,7 @@ enum CFE_ES_SystemState * @brief The overall cFE System State * * - * These values are used with the CFE_ES_WaitForSystemState() API call to synchronize application startup. + * These values are used with the #CFE_ES_WaitForSystemState API call to synchronize application startup. * * @note These are defined in order so that relational comparisons e.g. if (STATEA < STATEB) are possible * diff --git a/fsw/cfe-core/src/inc/cfe_evs.h b/fsw/cfe-core/src/inc/cfe_evs.h index e2664bf3c..20f889e9d 100644 --- a/fsw/cfe-core/src/inc/cfe_evs.h +++ b/fsw/cfe-core/src/inc/cfe_evs.h @@ -107,7 +107,7 @@ /****************** Structure Definitions *********************/ -/** Event message filter defintion structure */ +/** \brief Event message filter defintion structure */ typedef struct { uint16 EventID; /**< \brief Numerical event identifier */ uint16 Mask; /**< \brief Binary filter mask value */ @@ -119,6 +119,10 @@ typedef struct { /****************** Function Prototypes **********************/ +/** @defgroup CFEAPIEVSReg cFE Registration APIs + * @{ + */ + /** ** \brief Register an application for receiving event services ** @@ -157,13 +161,11 @@ typedef struct { ** \param[in] FilterScheme The event filtering scheme that this application will use. For the first implementation of ** the event services, only filter type #CFE_EVS_EventFilter_BINARY will be supported. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_EVS_APP_FILTER_OVERLOAD \retdesc \copydoc CFE_EVS_APP_FILTER_OVERLOAD \endcode -** \retcode #CFE_EVS_UNKNOWN_FILTER \retdesc \copydoc CFE_EVS_UNKNOWN_FILTER \endcode -** \retcode #CFE_EVS_APP_ILLEGAL_APP_ID \retdesc \copydoc CFE_EVS_APP_ILLEGAL_APP_ID \endcode -** \retstmt Any of the error codes from #CFE_ES_GetAppID \endstmt -** \endreturns +** \return Execution status below or from #CFE_ES_GetAppID, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_EVS_APP_FILTER_OVERLOAD \copybrief CFE_EVS_APP_FILTER_OVERLOAD +** \retval #CFE_EVS_UNKNOWN_FILTER \copybrief CFE_EVS_UNKNOWN_FILTER +** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID ** ** \sa #CFE_EVS_Unregister ** @@ -184,18 +186,20 @@ int32 CFE_EVS_Register (void *Filters, /* Pointer to a ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_EVS_APP_NOT_REGISTERED \retdesc \copydoc CFE_EVS_APP_NOT_REGISTERED \endcode -** \retcode #CFE_EVS_APP_ILLEGAL_APP_ID \retdesc \copydoc CFE_EVS_APP_ILLEGAL_APP_ID \endcode -** \retstmt Any of the error codes from #CFE_ES_GetAppID \endstmt -** \retstmt Any of the error codes from #CFE_ES_PutPoolBuf \endstmt -** \endreturns +** \return Execution status below or from #CFE_ES_GetAppID/#CFE_ES_PutPoolBuf, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED +** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID ** ** \sa #CFE_EVS_Register ** **/ int32 CFE_EVS_Unregister( void ); +/**@}*/ + +/** @defgroup CFEAPIEVSSend cFE Send Event APIs + * @{ + */ /** ** \brief Generate a software event. @@ -228,13 +232,10 @@ int32 CFE_EVS_Unregister( void ); ** in the format string; they will mess up the formatting when the events are ** displayed on the ground system. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_EVS_APP_NOT_REGISTERED \retdesc \copydoc CFE_EVS_APP_NOT_REGISTERED \endcode -** \retcode #CFE_EVS_APP_ILLEGAL_APP_ID \retdesc \copydoc CFE_EVS_APP_ILLEGAL_APP_ID \endcode -** \retstmt Any of the error codes from #CFE_ES_GetAppID \endstmt -** \retstmt Any of the error codes from #CFE_SB_SendMsg \endstmt -** \endreturns +** \return Execution status below or from #CFE_ES_GetAppID/#CFE_SB_SendMsg, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED +** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID ** ** \sa #CFE_EVS_SendEventWithAppID, #CFE_EVS_SendTimedEvent ** @@ -279,13 +280,10 @@ int32 CFE_EVS_SendEvent (uint16 EventID, ** in the format string; they will mess up the formatting when the events are ** displayed on the ground system. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_EVS_APP_NOT_REGISTERED \retdesc \copydoc CFE_EVS_APP_NOT_REGISTERED \endcode -** \retcode #CFE_EVS_APP_ILLEGAL_APP_ID \retdesc \copydoc CFE_EVS_APP_ILLEGAL_APP_ID \endcode -** \retstmt Any of the error codes from #CFE_ES_GetAppID \endstmt -** \retstmt Any of the error codes from #CFE_SB_SendMsg \endstmt -** \endreturns +** \return Execution status below or from #CFE_ES_GetAppID/#CFE_SB_SendMsg, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED +** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID ** ** \sa #CFE_EVS_SendEvent, #CFE_EVS_SendTimedEvent ** @@ -309,7 +307,7 @@ int32 CFE_EVS_SendEventWithAppID (uint16 EventID, ** None ** ** \param[in] Time The time to include in the event. This will usually be a time returned -** by the function #CFE_TIME_GetTime(). +** by the function #CFE_TIME_GetTime. ** ** \param[in] EventID A numeric literal used to uniquely identify an application event. ** The \c EventID is defined and supplied by the application sending the event. @@ -331,13 +329,10 @@ int32 CFE_EVS_SendEventWithAppID (uint16 EventID, ** in the format string; they will mess up the formatting when the events are ** displayed on the ground system. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_EVS_APP_NOT_REGISTERED \retdesc \copydoc CFE_EVS_APP_NOT_REGISTERED \endcode -** \retcode #CFE_EVS_APP_ILLEGAL_APP_ID \retdesc \copydoc CFE_EVS_APP_ILLEGAL_APP_ID \endcode -** \retstmt Any of the error codes from #CFE_ES_GetAppID \endstmt -** \retstmt Any of the error codes from #CFE_SB_SendMsg \endstmt -** \endreturns +** \return Execution status below or from #CFE_ES_GetAppID/#CFE_SB_SendMsg, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED +** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID ** ** \sa #CFE_EVS_SendEvent, #CFE_EVS_SendEventWithAppID ** @@ -346,7 +341,11 @@ int32 CFE_EVS_SendTimedEvent (CFE_TIME_SysTime_t Time, uint16 EventID, uint16 EventType, const char *Spec, ... ) OS_PRINTF(4,5); +/**@}*/ +/** @defgroup CFEAPIEVSResetFilter cFE Reset Event Filter APIs + * @{ + */ /** ** \brief Resets the calling application's event filter for a single event ID. @@ -361,12 +360,10 @@ int32 CFE_EVS_SendTimedEvent (CFE_TIME_SysTime_t Time, ** \param[in] EventID A numeric literal used to uniquely identify an application event. ** The \c EventID is defined and supplied by the application sending the event. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_EVS_APP_NOT_REGISTERED \retdesc \copydoc CFE_EVS_APP_NOT_REGISTERED \endcode -** \retcode #CFE_EVS_APP_ILLEGAL_APP_ID \retdesc \copydoc CFE_EVS_APP_ILLEGAL_APP_ID \endcode -** \retstmt Any of the error codes from #CFE_ES_GetAppID \endstmt -** \endreturns +** \return Execution status below or from #CFE_ES_GetAppID, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED +** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID ** ** \sa #CFE_EVS_ResetAllFilters ** @@ -384,18 +381,16 @@ int32 CFE_EVS_ResetFilter (int16 EventID); ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_EVS_APP_NOT_REGISTERED \retdesc \copydoc CFE_EVS_APP_NOT_REGISTERED \endcode -** \retcode #CFE_EVS_APP_ILLEGAL_APP_ID \retdesc \copydoc CFE_EVS_APP_ILLEGAL_APP_ID \endcode -** \retstmt Any of the error codes from #CFE_ES_GetAppID \endstmt -** \endreturns +** \return Execution status below or from #CFE_ES_GetAppID, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED +** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID ** ** \sa #CFE_EVS_ResetFilter ** **/ int32 CFE_EVS_ResetAllFilters ( void ); - +/**@}*/ #endif /* _cfe_evs_ */ diff --git a/fsw/cfe-core/src/inc/cfe_evs_events.h b/fsw/cfe-core/src/inc/cfe_evs_events.h index fd99d7c2c..b51e33c8b 100644 --- a/fsw/cfe-core/src/inc/cfe_evs_events.h +++ b/fsw/cfe-core/src/inc/cfe_evs_events.h @@ -236,7 +236,7 @@ ** ** The message text identifies the registry filename and specifies the return value, in hex, ** from the system function call. The expected return value is the number of bytes written, -** which in this case should be equal to the size of a #CFE_EVS_AppDataFile_t structure. Error +** which in this case should be equal to the size of a CFE_EVS_AppDataFile_t structure. Error ** codes are negative. **/ #define CFE_EVS_ERR_WRDATFILE_EID 12 @@ -659,7 +659,7 @@ ** ** \par Cause: ** -** This event message is generated when the filtering count for a specific App and Event ID reaches #CFE_EVS_MAX_FILTER_COUNT +** This event message is generated when the filtering count for a specific App and Event ID reaches CFE_EVS_MAX_FILTER_COUNT ** The filtered event will no longer be received until the reset counter is reset via a ** \link #CFE_EVS_RESET_FILTER_CC "Reset an Event Filter for an Application" \endlink or a ** \link #CFE_EVS_RESET_ALL_FILTERS_CC "Reset All Event Filters for an Application" \endlink diff --git a/fsw/cfe-core/src/inc/cfe_fs.h b/fsw/cfe-core/src/inc/cfe_fs.h index 3d213a570..dde2169db 100644 --- a/fsw/cfe-core/src/inc/cfe_fs.h +++ b/fsw/cfe-core/src/inc/cfe_fs.h @@ -71,9 +71,9 @@ #endif /* CFE_OMIT_DEPRECATED_6_6 */ -/* -** File header access functions... -*/ +/** @defgroup CFEAPIFSHeader cFE File Header Management APIs + * @{ + */ /*****************************************************************************/ /** @@ -96,9 +96,7 @@ ** ** \param[out] *Hdr Contents of the Standard cFE File Header for the specified file. ** -** \returns -** \retstmt Any of the return codes specified for #OS_lseek or #OS_read \endstmt -** \endreturns +** \return Execution status, see \ref CFEReturnCodes ** ** \sa #CFE_FS_WriteHeader ** @@ -158,9 +156,7 @@ void CFE_FS_InitHeader(CFE_FS_Header_t *Hdr, const char *Description, uint32 Sub ** ** \param[out] *Hdr Contents of the Standard cFE File Header for the specified file. ** -** \returns -** \retstmt Any of the return codes specified for #OS_lseek or #OS_write \endstmt -** \endreturns +** \return Execution status, see \ref CFEReturnCodes ** ** \sa #CFE_FS_ReadHeader ** @@ -187,15 +183,15 @@ int32 CFE_FS_WriteHeader(int32 FileDes, CFE_FS_Header_t *Hdr); ** \param[in] NewTimestamp A #CFE_TIME_SysTime_t data structure containing the desired time ** to be put into the file's Standard cFE File Header. ** -** \returns -** \retstmt Any of the return codes specified for #OS_lseek or #OS_write \endstmt -** \endreturns -** -** \sa +** \return Execution status, see \ref CFEReturnCodes ** ******************************************************************************/ int32 CFE_FS_SetTimestamp(int32 FileDes, CFE_TIME_SysTime_t NewTimestamp); +/**@}*/ +/** @defgroup CFEAPIFSCompress cFE Compressed File Management APIs + * @{ + */ /*****************************************************************************/ /** @@ -211,41 +207,13 @@ int32 CFE_FS_SetTimestamp(int32 FileDes, CFE_TIME_SysTime_t NewTimestamp); ** ** \param[in] FileName The name of the file. ** -** \returns -** \retstmt true if the file has the ".gz" extention and false otherwise. \endstmt -** \endreturns -** -** \sa +** \return Boolean for file has ".gz" extension +** \retval true File has ".gz" extension +** \retval false File does not have ".gz" extension ** ******************************************************************************/ bool CFE_FS_IsGzFile(const char *FileName); -/*****************************************************************************/ -/** -** \brief Extracts the filename from a unix style path and filename string. -** -** \par Description -** This API will take the original unix path/filename combination and -** extract the base filename. Example: Given the path/filename : "/cf/apps/myapp.o.gz" -** this function will return the filename: "myapp.o.gz". -** -** \par Assumptions, External Events, and Notes: -** -# The paths and filenames used here are the standard unix style -** filenames separated by "/" characters. -** -# The extracted filename is no longer than #OS_MAX_PATH_LEN -** -** \param[in] OriginalPath The original path. -** \param[out] FileNameOnly The filename that is extracted from the path. -** -** \returns -** \retstmt CFE_SUCCESS if the filename was extracted from the path \endstmt -** \endreturns -** -** \sa -** -******************************************************************************/ -int32 CFE_FS_ExtractFilenameFromPath(const char *OriginalPath, char *FileNameOnly); - /*****************************************************************************/ /** ** \brief Decompresses the source file to the destination file. @@ -257,6 +225,9 @@ int32 CFE_FS_ExtractFilenameFromPath(const char *OriginalPath, char *FileNameOnl ** Cygwin, and MinGW for Windows. More information can be found at ** http://www.gzip.org/ ** +** Uses a global state buffer but protects the global by a mutex, +** so it may block if more than one thread tries to do this at any given time. +** ** \par Assumptions, External Events, and Notes: ** -# The paths and filenames used here are cfe compliant file names. ** -# The source file is compressed with the "gzip" utility. @@ -266,11 +237,7 @@ int32 CFE_FS_ExtractFilenameFromPath(const char *OriginalPath, char *FileNameOnl ** \param[out] DestinationFile The path/filename to write the decompressed or ** "gunzipped" file to. ** -** \returns -** \retstmt CFE_SUCCESS if the file was decompressed sucessfully. \endstmt -** \endreturns -** -** \sa +** \return Execution status, see \ref CFEReturnCodes ** ******************************************************************************/ int32 CFE_FS_Decompress( const char * SourceFile, const char * DestinationFile ); @@ -281,14 +248,14 @@ int32 CFE_FS_Decompress( const char * SourceFile, const char * DestinationFile ) ** \brief Decompresses the source file to a temporary file created in the temp dir ** ** \par Description -** This is a wrapper around the CFE_FS_Decompress() function that +** This is a wrapper around the #CFE_FS_Decompress function that ** formulates a temporary file name based on the gzip file name, saving ** the caller from needing to do this. The temporary file name is ** created in the given temp directory. ** ** \par Assumptions, External Events, and Notes: ** The name passed in as "GzipFileName" is not checked again, it is assumed to -** have passed the criteria in CFE_FS_IsGzFile(). If this is not true then +** have passed the criteria in #CFE_FS_IsGzFile. If this is not true then ** the conversion to a temporary file name may produce incorrect results. ** ** \param[in] OutputNameBuffer A caller-supplied buffer for storing the temp file name @@ -296,15 +263,39 @@ int32 CFE_FS_Decompress( const char * SourceFile, const char * DestinationFile ) ** \param[in] GzipFileName The "gzipped" file to decompress. ** \param[in] TempDir The directory in which the temporary file should be created ** -** \returns -** \retstmt CFE_SUCCESS if the file was decompressed sucessfully. \endstmt -** \endreturns -** -** \sa +** \return Execution status, see \ref CFEReturnCodes ** ******************************************************************************/ int32 CFE_FS_GetUncompressedFile(char *OutputNameBuffer, uint32 OutputNameBufferSize, const char *GzipFileName, const char *TempDir); +/**@}*/ + +/** @defgroup CFEAPIFSUtil cFE File Utility APIs + * @{ + */ + +/*****************************************************************************/ +/** +** \brief Extracts the filename from a unix style path and filename string. +** +** \par Description +** This API will take the original unix path/filename combination and +** extract the base filename. Example: Given the path/filename : "/cf/apps/myapp.o.gz" +** this function will return the filename: "myapp.o.gz". +** +** \par Assumptions, External Events, and Notes: +** -# The paths and filenames used here are the standard unix style +** filenames separated by "/" characters. +** -# The extracted filename is no longer than #OS_MAX_PATH_LEN +** +** \param[in] OriginalPath The original path. +** \param[out] FileNameOnly The filename that is extracted from the path. +** +** \return Execution status, see \ref CFEReturnCodes +** +******************************************************************************/ +int32 CFE_FS_ExtractFilenameFromPath(const char *OriginalPath, char *FileNameOnly); +/**@}*/ #endif /* _cfe_fs_ */ diff --git a/fsw/cfe-core/src/inc/cfe_sb.h b/fsw/cfe-core/src/inc/cfe_sb.h index 19080860f..2166d4265 100644 --- a/fsw/cfe-core/src/inc/cfe_sb.h +++ b/fsw/cfe-core/src/inc/cfe_sb.h @@ -53,7 +53,7 @@ #define CFE_SB_SUBSCRIPTION 0 /**< \brief Subtype specifier used in #CFE_SB_SingleSubscriptionTlm_t by SBN App */ #define CFE_SB_UNSUBSCRIPTION 1 /**< \brief Subtype specified used in #CFE_SB_SingleSubscriptionTlm_t by SBN App */ -#define CFE_SB_INVALID_MSG_ID 0xFFFF /**< \brief Initializer for CFE_SB_MsgId_t values that will not match any real MsgId */ +#define CFE_SB_INVALID_MSG_ID 0xFFFF /**< \brief Initializer for #CFE_SB_MsgId_t values that will not match any real MsgId */ /* ** Macro Definitions @@ -64,6 +64,8 @@ #define CFE_TST(i,x) (((i) & CFE_BIT(x)) != 0)/**< \brief true(non zero) if bit x of i is set */ /** + * \brief Set memory address within SB Message + * * Macro that should be used to set memory addresses within software bus messages. * For now this does a straight copy, but in a future revision this may translate the * raw memory address into a "safe" integer value. This is particularly important if @@ -72,6 +74,8 @@ #define CFE_SB_SET_MEMADDR(msgdst,src) msgdst = (cpuaddr)src /** + * \brief Get memory address from SB Message + * * Macro that should be used to get memory addresses from software bus messages. * This is the inverse operation of CFE_SB_SET_MEMADDR. */ @@ -87,7 +91,7 @@ */ #ifdef MESSAGE_FORMAT_IS_CCSDS - /**< \brief Generic Software Bus Message Type Definition */ + /** \brief Generic Software Bus Message Type Definition */ typedef union { CCSDS_PriHdr_t Hdr; /**< \brief CCSDS Primary Header #CCSDS_PriHdr_t */ CCSDS_SpacePacket_t SpacePacket; @@ -106,7 +110,7 @@ #endif /* MESSAGE_FORMAT_IS_CCSDS */ -/**< \brief CFE_SB_TimeOut_t to primitive type definition +/** \brief CFE_SB_TimeOut_t to primitive type definition ** ** Internally used by SB in the #CFE_SB_RcvMsg API. Translated from the ** input parmater named TimeOut which specifies the maximum time in @@ -114,25 +118,25 @@ */ typedef uint32 CFE_SB_TimeOut_t; -/**< \brief CFE_SB_PipeId_t to primitive type definition +/** \brief CFE_SB_PipeId_t to primitive type definition ** ** Software Bus pipe identifier used in many SB APIs */ typedef uint8 CFE_SB_PipeId_t; -/**< \brief CFE_SB_MsgPtr_t defined as a pointer to an SB Message */ +/** \brief CFE_SB_MsgPtr_t defined as a pointer to an SB Message */ typedef CFE_SB_Msg_t *CFE_SB_MsgPtr_t; -/**< \brief CFE_SB_MsgPayloadPtr_t defined as an opaque pointer to a message Payload portion */ +/** \brief CFE_SB_MsgPayloadPtr_t defined as an opaque pointer to a message Payload portion */ typedef uint8 *CFE_SB_MsgPayloadPtr_t; -/**< \brief CFE_SB_ZeroCopyId_t to primitive type definition +/** \brief CFE_SB_ZeroCopyHandle_t to primitive type definition ** ** Software Zero Copy handle used in many SB APIs */ typedef cpuaddr CFE_SB_ZeroCopyHandle_t; -/**< \brief Quality Of Service Type Definition +/** \brief Quality Of Service Type Definition ** ** Currently an unused parameter in #CFE_SB_SubscribeEx ** Intended to be used for interprocessor communication only @@ -145,7 +149,7 @@ typedef struct { extern CFE_SB_Qos_t CFE_SB_Default_Qos;/**< \brief Defines a default priority and reliabilty for off-board routing */ -/**< \brief Message Sender Identification Type Definition +/** \brief Message Sender Identification Type Definition ** ** Parameter used in #CFE_SB_GetLastSenderId API which allows the receiver of a message ** to validate the sender of the message. @@ -155,9 +159,11 @@ typedef struct { char AppName[OS_MAX_API_NAME];/**< \brief Application that sent the message */ } CFE_SB_SenderId_t; -/* -** cFE SB Application Programmer Interface's (API's) -*/ +/****************** Function Prototypes **********************/ + +/** @defgroup CFEAPISBPipe cFE Pipe Management APIs + * @{ + */ /*****************************************************************************/ /** @@ -167,7 +173,7 @@ typedef struct { ** This routine creates and initializes an input pipe that the calling ** application can use to receive software bus messages. By default, no ** messages are routed to the new pipe. So, the application must use -** #CFE_SB_Subscribe() to specify which messages it wants to receive on +** #CFE_SB_Subscribe to specify which messages it wants to receive on ** this pipe. ** ** \par Assumptions, External Events, and Notes: @@ -186,12 +192,11 @@ typedef struct { ** ** \param[out] *PipeIdPtr The identifier for the created pipe. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_MAX_PIPES_MET \retdesc \copydoc CFE_SB_MAX_PIPES_MET \endcode -** \retcode #CFE_SB_PIPE_CR_ERR \retdesc \copydoc CFE_SB_PIPE_CR_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_MAX_PIPES_MET \copybrief CFE_SB_MAX_PIPES_MET +** \retval #CFE_SB_PIPE_CR_ERR \copybrief CFE_SB_PIPE_CR_ERR ** ** \sa #CFE_SB_DeletePipe #CFE_SB_GetPipeOpts #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName **/ @@ -220,10 +225,9 @@ int32 CFE_SB_CreatePipe(CFE_SB_PipeId_t *PipeIdPtr, ** \param[in] PipeId The pipe ID (obtained previously from #CFE_SB_CreatePipe) ** of the pipe to be deleted. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT ** ** \sa #CFE_SB_CreatePipe #CFE_SB_GetPipeOpts #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName **/ @@ -241,10 +245,9 @@ int32 CFE_SB_DeletePipe(CFE_SB_PipeId_t PipeId); ** ** \param[in] Opts A bit field of options. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT ** ** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_GetPipeOpts #CFE_SB_GetPipeIdByName #CFE_SB_PIPEOPTS_IGNOREMINE **/ @@ -262,10 +265,9 @@ int32 CFE_SB_SetPipeOpts(CFE_SB_PipeId_t PipeId, ** ** \param[out] *OptPtr A bit field of options. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT ** ** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName #CFE_SB_PIPEOPTS_IGNOREMINE **/ @@ -285,11 +287,9 @@ int32 CFE_SB_GetPipeOpts(CFE_SB_PipeId_t PipeId, ** ** \param[in] PipeId The PipeId for that name. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_INVALID_PIPE \retdesc \copydoc CFE_SB_INVALID_PIPE \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT ** ** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName **/ @@ -306,15 +306,18 @@ int32 CFE_SB_GetPipeName(char *PipeNameBuf, size_t PipeNameSize, CFE_SB_PipeId_t ** ** \param[out] PipeIdPtr The PipeId for that name. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_INVALID_PIPE \retdesc \copydoc CFE_SB_INVALID_PIPE \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT ** ** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_SetPipeOpts #CFE_SB_PIPEOPTS_IGNOREMINE **/ int32 CFE_SB_GetPipeIdByName(CFE_SB_PipeId_t *PipeIdPtr, const char *PipeName); +/**@}*/ + +/** @defgroup CFEAPISBSubscription cFE Message Subscription Control APIs + * @{ + */ /*****************************************************************************/ /** @@ -345,13 +348,12 @@ int32 CFE_SB_GetPipeIdByName(CFE_SB_PipeId_t *PipeIdPtr, const char *PipeName); ** \param[in] MsgLim The maximum number of messages with this Message ID to ** allow in this pipe at the same time. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_MAX_MSGS_MET \retdesc \copydoc CFE_SB_MAX_MSGS_MET \endcode -** \retcode #CFE_SB_MAX_DESTS_MET \retdesc \copydoc CFE_SB_MAX_DESTS_MET \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_BUF_ALOC_ERR \retdesc \copydoc CFE_SB_BUF_ALOC_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_MAX_MSGS_MET \copybrief CFE_SB_MAX_MSGS_MET +** \retval #CFE_SB_MAX_DESTS_MET \copybrief CFE_SB_MAX_DESTS_MET +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR ** ** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeLocal, #CFE_SB_Unsubscribe, #CFE_SB_UnsubscribeLocal **/ @@ -384,13 +386,12 @@ int32 CFE_SB_SubscribeEx(CFE_SB_MsgId_t MsgId, ** \param[in] PipeId The pipe ID of the pipe the subscribed message ** should be sent to. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_MAX_MSGS_MET \retdesc \copydoc CFE_SB_MAX_MSGS_MET \endcode -** \retcode #CFE_SB_MAX_DESTS_MET \retdesc \copydoc CFE_SB_MAX_DESTS_MET \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_BUF_ALOC_ERR \retdesc \copydoc CFE_SB_BUF_ALOC_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_MAX_MSGS_MET \copybrief CFE_SB_MAX_MSGS_MET +** \retval #CFE_SB_MAX_DESTS_MET \copybrief CFE_SB_MAX_DESTS_MET +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR ** ** \sa #CFE_SB_SubscribeEx, #CFE_SB_SubscribeLocal, #CFE_SB_Unsubscribe, #CFE_SB_UnsubscribeLocal **/ @@ -419,13 +420,12 @@ int32 CFE_SB_Subscribe(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId); ** \param[in] MsgLim The maximum number of messages with this Message ID to ** allow in this pipe at the same time. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_MAX_MSGS_MET \retdesc \copydoc CFE_SB_MAX_MSGS_MET \endcode -** \retcode #CFE_SB_MAX_DESTS_MET \retdesc \copydoc CFE_SB_MAX_DESTS_MET \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_BUF_ALOC_ERR \retdesc \copydoc CFE_SB_BUF_ALOC_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_MAX_MSGS_MET \copybrief CFE_SB_MAX_MSGS_MET +** \retval #CFE_SB_MAX_DESTS_MET \copybrief CFE_SB_MAX_DESTS_MET +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR ** ** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeEx, #CFE_SB_Unsubscribe, #CFE_SB_UnsubscribeLocal **/ @@ -449,11 +449,10 @@ int32 CFE_SB_SubscribeLocal(CFE_SB_MsgId_t MsgId, ** \param[in] PipeId The pipe ID of the pipe the subscribed message ** should no longer be sent to. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_NO_SUBSCRIBERS \retdesc \copydoc CFE_SB_NO_SUBSCRIBERS \endcode -** \retcode #CFE_SB_INTERNAL_ERR \retdesc \copydoc CFE_SB_INTERNAL_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_NO_SUBSCRIBERS \copybrief CFE_SB_NO_SUBSCRIBERS +** \retval #CFE_SB_INTERNAL_ERR \copybrief CFE_SB_INTERNAL_ERR ** ** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeEx, #CFE_SB_SubscribeLocal, #CFE_SB_UnsubscribeLocal **/ @@ -475,15 +474,19 @@ int32 CFE_SB_Unsubscribe(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId); ** \param[in] PipeId The pipe ID of the pipe the subscribed message ** should no longer be sent to. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_NO_SUBSCRIBERS \retdesc \copydoc CFE_SB_NO_SUBSCRIBERS \endcode -** \retcode #CFE_SB_INTERNAL_ERR \retdesc \copydoc CFE_SB_INTERNAL_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_NO_SUBSCRIBERS \copybrief CFE_SB_NO_SUBSCRIBERS +** \retval #CFE_SB_INTERNAL_ERR \copybrief CFE_SB_INTERNAL_ERR ** ** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeEx, #CFE_SB_SubscribeLocal, #CFE_SB_Unsubscribe **/ int32 CFE_SB_UnsubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId); +/**@}*/ + +/** @defgroup CFEAPISBMessage cFE Send/Receive Message APIs + * @{ + */ /*****************************************************************************/ /** @@ -507,12 +510,11 @@ int32 CFE_SB_UnsubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId); ** to the first byte of the software bus message header ** (#CFE_SB_Msg_t). ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_MSG_TOO_BIG \retdesc \copydoc CFE_SB_MSG_TOO_BIG \endcode -** \retcode #CFE_SB_BUF_ALOC_ERR \retdesc \copydoc CFE_SB_BUF_ALOC_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG +** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR ** ** \sa #CFE_SB_RcvMsg, #CFE_SB_ZeroCopySend, #CFE_SB_PassMsg **/ @@ -541,12 +543,11 @@ int32 CFE_SB_SendMsg(CFE_SB_Msg_t *MsgPtr); ** to the first byte of the software bus message header ** (#CFE_SB_Msg_t). ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_MSG_TOO_BIG \retdesc \copydoc CFE_SB_MSG_TOO_BIG \endcode -** \retcode #CFE_SB_BUF_ALOC_ERR \retdesc \copydoc CFE_SB_BUF_ALOC_ERR \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG +** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR ** ** \sa #CFE_SB_RcvMsg, #CFE_SB_ZeroCopySend, #CFE_SB_SendMsg **/ @@ -587,54 +588,23 @@ int32 CFE_SB_PassMsg(CFE_SB_Msg_t *MsgPtr); ** \param[out] *BufPtr A pointer to the message obtained from the pipe. Valid ** only until the next call to CFE_SB_RcvMsg for the same pipe. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_TIME_OUT \retdesc \copydoc CFE_SB_TIME_OUT \endcode -** \retcode #CFE_SB_PIPE_RD_ERR \retdesc \copydoc CFE_SB_PIPE_RD_ERR \endcode -** \retcode #CFE_SB_NO_MESSAGE \retdesc \copydoc CFE_SB_NO_MESSAGE \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_TIME_OUT \copybrief CFE_SB_TIME_OUT +** \retval #CFE_SB_PIPE_RD_ERR \copybrief CFE_SB_PIPE_RD_ERR +** \retval #CFE_SB_NO_MESSAGE \copybrief CFE_SB_NO_MESSAGE ** ** \sa #CFE_SB_SendMsg, #CFE_SB_ZeroCopySend **/ int32 CFE_SB_RcvMsg(CFE_SB_MsgPtr_t *BufPtr, CFE_SB_PipeId_t PipeId, int32 TimeOut); +/**@}*/ -/*****************************************************************************/ -/** -** \brief Retrieve the application Info of the sender for the last message. -** -** \par Description -** This routine can be used after a successful #CFE_SB_RcvMsg call -** to find out which application sent the message that was received. -** -** \par Assumptions, External Events, and Notes: -** Note - If an error occurs in this API, the *Ptr value may be NULL or -** random. Therefore, it is recommended that the return code be tested -** for CFE_SUCCESS before reading the sender information. -** -** \param[in] Ptr A pointer to a local variable of type #CFE_SB_SenderId_t. -** Typically a caller declares a ptr of type CFE_SB_SenderId_t -** (i.e. CFE_SB_SenderId_t *Ptr) then gives the address of that -** pointer (&Ptr) for this parameter. After a successful call -** to this API, *Ptr will point to the first byte of the -** CFE_SB_SenderId_t structure containing the sender information -** for the last message received on the given pipe. This should -** be used as a read-only pointer (in systems with an MMU, writes -** to this pointer may cause a memory protection fault). The *Ptr -** is valid only until the next call to CFE_SB_RcvMsg for the -** same pipe. -** -** \param[in] PipeId The pipe ID of the pipe the message was taken from. -** -** \returns -** \retcode The sender's application ID \retdesc \endcode -** \endreturns -** -** \sa -**/ -uint32 CFE_SB_GetLastSenderId(CFE_SB_SenderId_t **Ptr,CFE_SB_PipeId_t PipeId); +/** @defgroup CFEAPISBZeroCopy cFE Zero Copy Message APIs + * @{ + */ /*****************************************************************************/ /** @@ -665,10 +635,8 @@ uint32 CFE_SB_GetLastSenderId(CFE_SB_SenderId_t **Ptr,CFE_SB_PipeId_t PipeId); ** \param[out] BufferHandle A handle that must be supplied when sending or releasing ** in zero copy mode. ** -** \returns -** \retstmt A pointer to a memory buffer that can be used to build one SB message -** for use with #CFE_SB_ZeroCopySend. \endstmt -** \endreturns +** \return A pointer to a memory buffer that can be used to build one SB message +** for use with #CFE_SB_ZeroCopySend. ** ** \sa #CFE_SB_ZeroCopyReleasePtr, #CFE_SB_ZeroCopySend **/ @@ -696,10 +664,9 @@ CFE_SB_Msg_t *CFE_SB_ZeroCopyGetPtr(uint16 MsgSize, ** \param[in] BufferHandle This must be the handle supplied with the pointer ** when #CFE_SB_ZeroCopyGetPtr was called. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BUFFER_INVALID \retdesc \copydoc CFE_SB_BUFFER_INVALID \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID ** ** \sa #CFE_SB_ZeroCopyGetPtr, #CFE_SB_ZeroCopySend **/ @@ -735,13 +702,12 @@ int32 CFE_SB_ZeroCopyReleasePtr(CFE_SB_Msg_t *Ptr2Release, ** ** \param[in] BufferHandle The handle supplied with the #CFE_SB_ZeroCopyGetPtr call. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_MSG_TOO_BIG \retdesc \copydoc CFE_SB_MSG_TOO_BIG \endcode -** \retcode #CFE_SB_BUF_ALOC_ERR \retdesc \copydoc CFE_SB_BUF_ALOC_ERR \endcode -** \retcode #CFE_SB_BUFFER_INVALID \retdesc \copydoc CFE_SB_BUFFER_INVALID \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG +** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR +** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID ** ** \sa #CFE_SB_SendMsg, #CFE_SB_RcvMsg, #CFE_SB_ZeroCopyReleasePtr, #CFE_SB_ZeroCopyGetPtr **/ @@ -779,19 +745,22 @@ int32 CFE_SB_ZeroCopySend(CFE_SB_Msg_t *MsgPtr, ** ** \param[in] BufferHandle The handle supplied with the #CFE_SB_ZeroCopyGetPtr call. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_BAD_ARGUMENT \retdesc \copydoc CFE_SB_BAD_ARGUMENT \endcode -** \retcode #CFE_SB_MSG_TOO_BIG \retdesc \copydoc CFE_SB_MSG_TOO_BIG \endcode -** \retcode #CFE_SB_BUF_ALOC_ERR \retdesc \copydoc CFE_SB_BUF_ALOC_ERR \endcode -** \retcode #CFE_SB_BUFFER_INVALID \retdesc \copydoc CFE_SB_BUFFER_INVALID \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT +** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG +** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR +** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID ** ** \sa #CFE_SB_PassMsg, #CFE_SB_ZeroCopySend, #CFE_SB_ZeroCopyReleasePtr, #CFE_SB_ZeroCopyGetPtr **/ int32 CFE_SB_ZeroCopyPass(CFE_SB_Msg_t *MsgPtr, CFE_SB_ZeroCopyHandle_t BufferHandle); +/**@}*/ +/** @defgroup CFEAPISBSetMessage cFE Setting Message Characteristics APIs + * @{ + */ /*****************************************************************************/ /** @@ -827,301 +796,401 @@ void CFE_SB_InitMsg(void *MsgPtr, bool Clear ); /*****************************************************************************/ -/** -** \brief Get a pointer to the user data portion of a software bus message. +/** +** \brief Sets the message ID of a software bus message. ** ** \par Description -** This routine returns a pointer to the user data portion of a software -** bus message. SB message header formats can be different for each -** deployment of the cFE. So, applications should use this function and -** avoid hard coding offsets into their SB message buffers. +** This routine sets the Message ID in a software bus message header. ** ** \par Assumptions, External Events, and Notes: -** None +** None ** ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** This must point to the first byte of the message header. ** -** \returns -** \retstmt A pointer to the first byte of user data within the software bus message. \endstmt -** \endreturns +** \param[in] MsgId The message ID to put into the message header. ** -** \sa #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, -** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum, #CFE_SB_MsgHdrSize +** \return The software bus Message ID from the message header. +** +** \sa #CFE_SB_GetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, +** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg **/ -void *CFE_SB_GetUserData(CFE_SB_MsgPtr_t MsgPtr); +void CFE_SB_SetMsgId(CFE_SB_MsgPtr_t MsgPtr, + CFE_SB_MsgId_t MsgId); /*****************************************************************************/ -/** -** \brief Get the message ID of a software bus message. +/** +** \brief Sets the length of user data in a software bus message. ** ** \par Description -** This routine returns the message ID from a software bus message. +** This routine sets the field in the SB message header that determines +** the size of the user data in a software bus message. SB message header +** formats can be different for each deployment of the cFE. So, applications +** should use this function rather than trying to poke a length value directly +** into their SB message buffers. ** ** \par Assumptions, External Events, and Notes: -** None +** - You must set a valid message ID in the SB message header before +** calling this function. ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** This must point to the first byte of the message header. ** -** \returns -** \retstmt The software bus Message ID from the message header. \endstmt -** \endreturns +** \param[in] DataLength The length to set (size of the user data, in bytes). ** -** \sa #CFE_SB_GetUserData, #CFE_SB_SetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, -** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum, #CFE_SB_MsgHdrSize +** \sa #CFE_SB_SetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_SetTotalMsgLength, +** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg **/ -CFE_SB_MsgId_t CFE_SB_GetMsgId(const CFE_SB_Msg_t *MsgPtr); +void CFE_SB_SetUserDataLength(CFE_SB_MsgPtr_t MsgPtr,uint16 DataLength); /*****************************************************************************/ -/** -** \brief Sets the message ID of a software bus message. +/** +** \brief Sets the total length of a software bus message. ** ** \par Description -** This routine sets the Message ID in a software bus message header. +** This routine sets the field in the SB message header that determines +** the total length of the message. SB message header formats can be +** different for each deployment of the cFE. So, applications should +** use this function rather than trying to poke a length value directly +** into their SB message buffers. ** ** \par Assumptions, External Events, and Notes: -** None -** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. -** This must point to the first byte of the message header. +** None ** -** \param[in] MsgId The message ID to put into the message header. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** This must point to the first byte of the message header. ** -** \returns -** \retstmt The software bus Message ID from the message header. \endstmt -** \endreturns +** \param[in] TotalLength The length to set (total size of the message, in bytes, +** including headers). ** -** \sa #CFE_SB_GetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, -** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg +** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_GetTotalMsgLength, +** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg **/ -void CFE_SB_SetMsgId(CFE_SB_MsgPtr_t MsgPtr, - CFE_SB_MsgId_t MsgId); +void CFE_SB_SetTotalMsgLength(CFE_SB_MsgPtr_t MsgPtr,uint16 TotalLength); /*****************************************************************************/ -/** -** \brief Gets the length of user data in a software bus message. +/** +** \brief Sets the time field in a software bus message. ** ** \par Description -** This routine returns the size of the user data in a software bus message. +** This routine sets the time of a software bus message. Most applications +** will want to use #CFE_SB_TimeStampMsg instead of this function. But, +** when needed, #CFE_SB_SetMsgTime can be used to send a group of SB messages +** with identical time stamps. ** ** \par Assumptions, External Events, and Notes: -** None +** - If the underlying implementation of software bus messages does not include +** a time field, then this routine will do nothing to the message contents +** and will return #CFE_SB_WRONG_MSG_TYPE. ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. -** This must point to the first byte of the message header. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** This must point to the first byte of the message header. ** -** \returns -** \retstmt The size (in bytes) of the user data in the software bus message. \endstmt -** \endreturns +** \param[in] Time The time to include in the message. This will usually be a time +** returned by the function #CFE_TIME_GetTime. ** -** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_GetTotalMsgLength, -** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum, #CFE_SB_MsgHdrSize +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_WRONG_MSG_TYPE \copybrief CFE_SB_WRONG_MSG_TYPE +** +** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, +** #CFE_SB_GetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg **/ -uint16 CFE_SB_GetUserDataLength(const CFE_SB_Msg_t *MsgPtr); +int32 CFE_SB_SetMsgTime(CFE_SB_MsgPtr_t MsgPtr, + CFE_TIME_SysTime_t Time); /*****************************************************************************/ -/** -** \brief Sets the length of user data in a software bus message. +/** +** \brief Sets the time field in a software bus message with the current spacecraft time. ** ** \par Description -** This routine sets the field in the SB message header that determines -** the size of the user data in a software bus message. SB message header -** formats can be different for each deployment of the cFE. So, applications -** should use this function rather than trying to poke a length value directly -** into their SB message buffers. +** This routine sets the time of a software bus message with the current +** spacecraft time. This will be the same time that is returned by the +** function #CFE_TIME_GetTime. ** ** \par Assumptions, External Events, and Notes: -** - You must set a valid message ID in the SB message header before -** calling this function. +** - If the underlying implementation of software bus messages does not +** include a time field, then this routine will do nothing. ** ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. ** This must point to the first byte of the message header. ** -** \param[in] DataLength The length to set (size of the user data, in bytes). -** -** -** \sa #CFE_SB_SetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_SetTotalMsgLength, -** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg +** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, +** #CFE_SB_SetMsgTime, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg **/ -void CFE_SB_SetUserDataLength(CFE_SB_MsgPtr_t MsgPtr,uint16 DataLength); +void CFE_SB_TimeStampMsg(CFE_SB_MsgPtr_t MsgPtr); /*****************************************************************************/ -/** -** \brief Gets the total length of a software bus message. +/** +** \brief Sets the command code field in a software bus message. ** ** \par Description -** This routine returns the total size of the software bus message. +** This routine sets the command code of a software bus message (if SB +** messages are implemented as CCSDS packets, this will be the function code). ** ** \par Assumptions, External Events, and Notes: -** - For the CCSDS implementation of this API, the size is derived from -** the message header. +** - If the underlying implementation of software bus messages does not +** include a command code field, then this routine will do nothing to +** the message contents and will return #CFE_SB_WRONG_MSG_TYPE. ** ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. ** This must point to the first byte of the message header. ** -** \returns -** \retstmt The total size (in bytes) of the software bus message, including headers. \endstmt -** \endreturns +** \param[in] CmdCode The command code to include in the message. ** -** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_SetTotalMsgLength, -** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum, #CFE_SB_MsgHdrSize +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_SB_WRONG_MSG_TYPE \copybrief CFE_SB_WRONG_MSG_TYPE +** +** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, +** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_GetCmdCode, #CFE_SB_InitMsg **/ -uint16 CFE_SB_GetTotalMsgLength(const CFE_SB_Msg_t *MsgPtr); +int32 CFE_SB_SetCmdCode(CFE_SB_MsgPtr_t MsgPtr, + uint16 CmdCode); + +/******************************************************************************/ +/** +** \brief Copies a string into a software bus message +** +** \par Description +** Strings within software bus messages have a defined/fixed maximum length, and +** may not necessarily be null terminated within the message. This presents a possible +** issue when using the C library functions to copy strings out of a message. +** +** This performs a very similar function to "strncpy()" except that the sizes +** of _both_ buffers are passed in. Neither buffer is required to be null-terminated, +** but copying will stop after the first termination character is encountered. +** +** If the destination buffer is not completely filled by the source data (such as if +** the supplied string was shorter than the allotted length) the destination buffer +** will be padded with NUL characters up to the size of the buffer, similar to what +** strncpy() does. This ensures that the entire destination buffer is set. +** +** \note +** If the source string buffer is already guaranteed to be null terminated, +** then there is no difference between the C library "strncpy()" function and this +** implementation. It is only necessary to use this when termination of the source +** buffer is not guaranteed. +** +** \param[out] DestStringPtr Pointer to destination buffer (component of SB message definition) +** \param[in] SourceStringPtr Pointer to source buffer +** \param[in] DestMaxSize Size of destination buffer as defined by the message definition +** \param[in] SourceMaxSize Size of source buffer +** +** \return Number of characters copied or error code, see \ref CFEReturnCodes +** +*/ +int32 CFE_SB_MessageStringSet(char *DestStringPtr, const char *SourceStringPtr, uint32 DestMaxSize, uint32 SourceMaxSize); +/**@}*/ + +/** @defgroup CFEAPIGetMessage cFE Getting Message Characteristics APIs + * @{ + */ /*****************************************************************************/ /** -** \brief Sets the total length of a software bus message. +** \brief Get a pointer to the user data portion of a software bus message. ** ** \par Description -** This routine sets the field in the SB message header that determines -** the total length of the message. SB message header formats can be -** different for each deployment of the cFE. So, applications should -** use this function rather than trying to poke a length value directly -** into their SB message buffers. +** This routine returns a pointer to the user data portion of a software +** bus message. SB message header formats can be different for each +** deployment of the cFE. So, applications should use this function and +** avoid hard coding offsets into their SB message buffers. ** ** \par Assumptions, External Events, and Notes: -** None +** None ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. -** This must point to the first byte of the message header. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. ** -** \param[in] TotalLength The length to set (total size of the message, in bytes, -** including headers). +** \return A pointer to the first byte of user data within the software bus message. ** -** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_GetTotalMsgLength, -** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg +** \sa #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, +** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum **/ -void CFE_SB_SetTotalMsgLength(CFE_SB_MsgPtr_t MsgPtr,uint16 TotalLength); +void *CFE_SB_GetUserData(CFE_SB_MsgPtr_t MsgPtr); /*****************************************************************************/ /** -** \brief Gets the time field from a software bus message. +** \brief Get the message ID of a software bus message. ** ** \par Description -** This routine gets the time from a software bus message. +** This routine returns the message ID from a software bus message. ** ** \par Assumptions, External Events, and Notes: -** - If the underlying implementation of software bus messages does not -** include a time field, then this routine will return a zero time. +** None ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. -** This must point to the first byte of the message header. -** \returns -** \retstmt The system time included in the software bus message header (if present), -** otherwise, returns a time value of zero. \endstmt -** \endreturns +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. ** -** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, -** #CFE_SB_SetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum, #CFE_SB_MsgHdrSize +** \return The software bus Message ID from the message header. +** +** \sa #CFE_SB_GetUserData, #CFE_SB_SetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, +** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum **/ -CFE_TIME_SysTime_t CFE_SB_GetMsgTime(CFE_SB_MsgPtr_t MsgPtr); +CFE_SB_MsgId_t CFE_SB_GetMsgId(const CFE_SB_Msg_t *MsgPtr); /*****************************************************************************/ /** -** \brief Sets the time field in a software bus message. +** \brief Gets the length of user data in a software bus message. ** ** \par Description -** This routine sets the time of a software bus message. Most applications -** will want to use #CFE_SB_TimeStampMsg instead of this function. But, -** when needed, #CFE_SB_SetMsgTime can be used to send a group of SB messages -** with identical time stamps. +** This routine returns the size of the user data in a software bus message. ** ** \par Assumptions, External Events, and Notes: -** - If the underlying implementation of software bus messages does not include -** a time field, then this routine will do nothing to the message contents -** and will return #CFE_SB_WRONG_MSG_TYPE. -** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. -** This must point to the first byte of the message header. +** None ** -** \param[in] Time The time to include in the message. This will usually be a time -** returned by the function #CFE_TIME_GetTime(). +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** This must point to the first byte of the message header. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_WRONG_MSG_TYPE \retdesc \copydoc CFE_SB_WRONG_MSG_TYPE \endcode -** \endreturns +** \return The size (in bytes) of the user data in the software bus message. ** -** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, -** #CFE_SB_GetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg +** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_GetTotalMsgLength, +** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum **/ -int32 CFE_SB_SetMsgTime(CFE_SB_MsgPtr_t MsgPtr, - CFE_TIME_SysTime_t Time); +uint16 CFE_SB_GetUserDataLength(const CFE_SB_Msg_t *MsgPtr); /*****************************************************************************/ /** -** \brief Sets the time field in a software bus message with the current spacecraft time. +** \brief Gets the total length of a software bus message. ** ** \par Description -** This routine sets the time of a software bus message with the current -** spacecraft time. This will be the same time that is returned by the -** function #CFE_TIME_GetTime. +** This routine returns the total size of the software bus message. ** ** \par Assumptions, External Events, and Notes: -** - If the underlying implementation of software bus messages does not -** include a time field, then this routine will do nothing. +** - For the CCSDS implementation of this API, the size is derived from +** the message header. ** ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. -** This must point to the first byte of the message header. +** This must point to the first byte of the message header. ** -** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, -** #CFE_SB_SetMsgTime, #CFE_SB_SetCmdCode, #CFE_SB_InitMsg +** \return The total size (in bytes) of the software bus message, including headers. +** +** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_SetTotalMsgLength, +** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum **/ -void CFE_SB_TimeStampMsg(CFE_SB_MsgPtr_t MsgPtr); +uint16 CFE_SB_GetTotalMsgLength(const CFE_SB_Msg_t *MsgPtr); /*****************************************************************************/ -/** +/** ** \brief Gets the command code field from a software bus message. ** ** \par Description -** This routine gets the command code from a software bus message (if -** SB messages are implemented as CCSDS packets, this will be the function -** code). +** This routine gets the command code from a software bus message (if +** SB messages are implemented as CCSDS packets, this will be the function +** code). ** ** \par Assumptions, External Events, and Notes: -** - If the underlying implementation of software bus messages does not -** include a command code field, then this routine will return a zero. +** - If the underlying implementation of software bus messages does not +** include a command code field, then this routine will return a zero. ** ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. ** This must point to the first byte of the message header. ** -** \returns -** \retstmt The command code included in the software bus message header (if present). -** Otherwise, returns a command code value of zero. \endstmt -** \endreturns +** \return The command code included in the software bus message header (if present). +** Otherwise, returns a command code value of zero. ** ** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, -** #CFE_SB_GetMsgTime, #CFE_SB_SetCmdCode, #CFE_SB_GetChecksum, #CFE_SB_MsgHdrSize +** #CFE_SB_GetMsgTime, #CFE_SB_SetCmdCode, #CFE_SB_GetChecksum **/ uint16 CFE_SB_GetCmdCode(CFE_SB_MsgPtr_t MsgPtr); /*****************************************************************************/ /** -** \brief Sets the command code field in a software bus message. +** \brief Gets the time field from a software bus message. ** ** \par Description -** This routine sets the command code of a software bus message (if SB -** messages are implemented as CCSDS packets, this will be the function code). +** This routine gets the time from a software bus message. ** ** \par Assumptions, External Events, and Notes: ** - If the underlying implementation of software bus messages does not -** include a command code field, then this routine will do nothing to -** the message contents and will return #CFE_SB_WRONG_MSG_TYPE. +** include a time field, then this routine will return a zero time. ** ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. -** This must point to the first byte of the message header. +** This must point to the first byte of the message header. ** -** \param[in] CmdCode The command code to include in the message. +** \return The system time included in the software bus message header (if present), +** otherwise, returns a time value of zero. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_SB_WRONG_MSG_TYPE \retdesc \copydoc CFE_SB_WRONG_MSG_TYPE \endcode -** \endreturns +** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, +** #CFE_SB_SetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum +**/ +CFE_TIME_SysTime_t CFE_SB_GetMsgTime(CFE_SB_MsgPtr_t MsgPtr); + +/*****************************************************************************/ +/** +** \brief Retrieve the application Info of the sender for the last message. ** -** \sa #CFE_SB_SetMsgId, #CFE_SB_SetUserDataLength, #CFE_SB_SetTotalMsgLength, -** #CFE_SB_SetMsgTime, #CFE_SB_TimeStampMsg, #CFE_SB_GetCmdCode, #CFE_SB_InitMsg +** \par Description +** This routine can be used after a successful #CFE_SB_RcvMsg call +** to find out which application sent the message that was received. +** +** \par Assumptions, External Events, and Notes: +** Note - If an error occurs in this API, the *Ptr value may be NULL or +** random. Therefore, it is recommended that the return code be tested +** for CFE_SUCCESS before reading the sender information. +** +** \param[in] Ptr A pointer to a local variable of type #CFE_SB_SenderId_t. +** Typically a caller declares a ptr of type CFE_SB_SenderId_t +** (i.e. CFE_SB_SenderId_t *Ptr) then gives the address of that +** pointer (&Ptr) for this parameter. After a successful call +** to this API, *Ptr will point to the first byte of the +** CFE_SB_SenderId_t structure containing the sender information +** for the last message received on the given pipe. This should +** be used as a read-only pointer (in systems with an MMU, writes +** to this pointer may cause a memory protection fault). The *Ptr +** is valid only until the next call to CFE_SB_RcvMsg for the +** same pipe. +** +** \param[in] PipeId The pipe ID of the pipe the message was taken from. +** +** \return The last sender's application ID **/ -int32 CFE_SB_SetCmdCode(CFE_SB_MsgPtr_t MsgPtr, - uint16 CmdCode); +uint32 CFE_SB_GetLastSenderId(CFE_SB_SenderId_t **Ptr,CFE_SB_PipeId_t PipeId); + +/******************************************************************************/ +/** +** \brief Copies a string out of a software bus message +** +** \par Description +** Strings within software bus messages have a defined/fixed maximum length, and +** may not necessarily be null terminated within the message. This presents a possible +** issue when using the C library functions to copy strings out of a message. +** +** This function should replace use of C library functions such as strcpy/strncpy +** when copying strings out of software bus messages to local storage buffers. +** +** Up to [SourceMaxSize] or [DestMaxSize-1] (whichever is smaller) characters will be +** coped from the source buffer to the destination buffer, and a NUL termination +** character will be written to the destination buffer as the last character. +** +** If the DefaultString pointer is non-NULL, it will be used in place of the source +** string if the source is an empty string. This is typically a string constant that +** comes from the platform configuration, allowing default values to be assumed for +** fields that are unspecified. +** +** IMPORTANT - the default string, if specified, must be null terminated. This will +** be the case if a string literal is passed in (the typical/expected use case). +** +** If the default is NULL, then only the source string will be copied, and the result +** will be an empty string if the source was empty. +** +** If the destination buffer is too small to store the entire string, it will be +** truncated, but it will still be null terminated. +** +** \param[out] DestStringPtr Pointer to destination buffer +** \param[in] SourceStringPtr Pointer to source buffer (component of SB message definition) +** \param[in] DefaultString Default string to use if source is empty +** \param[in] DestMaxSize Size of destination storage buffer (must be at least 2) +** \param[in] SourceMaxSize Size of source buffer as defined by the message definition +** +** \return Number of characters copied or error code, see \ref CFEReturnCodes +** +*/ +int32 CFE_SB_MessageStringGet(char *DestStringPtr, const char *SourceStringPtr, const char *DefaultString, uint32 DestMaxSize, uint32 SourceMaxSize); +/**@}*/ + +/** @defgroup CFEAPISBChecksum cFE Checksum Control APIs + * @{ + */ /*****************************************************************************/ /** @@ -1142,13 +1211,11 @@ int32 CFE_SB_SetCmdCode(CFE_SB_MsgPtr_t MsgPtr, ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. ** This must point to the first byte of the message header. ** -** \returns -** \retstmt The checksum included in the software bus message header (if present), otherwise, -** returns a checksum value of zero. \endstmt -** \endreturns +** \return The checksum included in the software bus message header (if present), otherwise, +** returns a checksum value of zero. ** ** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength, -** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum, #CFE_SB_MsgHdrSize, +** #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum ** #CFE_SB_ValidateChecksum, #CFE_SB_GenerateChecksum **/ uint16 CFE_SB_GetChecksum(CFE_SB_MsgPtr_t MsgPtr); @@ -1193,111 +1260,36 @@ void CFE_SB_GenerateChecksum(CFE_SB_MsgPtr_t MsgPtr); ** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. ** This must point to the first byte of the message header. ** -** \returns -** \retcode true \retdesc The checksum field in the packet is valid. \endcode -** \retcode false \retdesc The checksum field in the packet is not valid or the message type is wrong. \endcode -** \endreturns +** \return Boolean checksum result +** \retval true The checksum field in the packet is valid. +** \retval false The checksum field in the packet is not valid or the message type is wrong. ** ** \sa #CFE_SB_GenerateChecksum, #CFE_SB_GetChecksum **/ bool CFE_SB_ValidateChecksum(CFE_SB_MsgPtr_t MsgPtr); +/**@}*/ -/****************************************************************************** -** Function: CFE_SB_MessageStringGet() -** -** Purpose: -** Copies a string out of a software bus message -** -** Strings within software bus messages have a defined/fixed maximum length, and -** may not necessarily be null terminated within the message. This presents a possible -** issue when using the C library functions to copy strings out of a message. -** -** This function should replace use of C library functions such as strcpy/strncpy -** when copying strings out of software bus messages to local storage buffers. -** -** Up to [SourceMaxSize] or [DestMaxSize-1] (whichever is smaller) characters will be -** coped from the source buffer to the destination buffer, and a NUL termination -** character will be written to the destination buffer as the last character. -** -** If the DefaultString pointer is non-NULL, it will be used in place of the source -** string if the source is an empty string. This is typically a string constant that -** comes from the platform configuration, allowing default values to be assumed for -** fields that are unspecified. -** -** IMPORTANT - the default string, if specified, must be null terminated. This will -** be the case if a string literal is passed in (the typical/expected use case). -** -** If the default is NULL, then only the source string will be copied, and the result -** will be an empty string if the source was empty. -** -** If the destination buffer is too small to store the entire string, it will be -** truncated, but it will still be null terminated. -** -** Arguments: -** DestStringPtr - pointer to destination buffer -** SourceStringPtr - pointer to source buffer (component of SB message definition) -** DefaultString - alternative string to use if the source is an empty string -** DestMaxSize - size of the destination storage buffer (must be at least 2) -** SourceMaxSize - size of the source buffer as defined by the message definition -** -** Returns: -** Length of result - number of characters copied, not including the terminating NUL. -** This should match the value that would be returned by "strlen(DestStringPtr)" -** -*/ -int32 CFE_SB_MessageStringGet(char *DestStringPtr, const char *SourceStringPtr, const char *DefaultString, uint32 DestMaxSize, uint32 SourceMaxSize); - -/****************************************************************************** -** Function: CFE_SB_MessageStringSet() -** -** Purpose: -** Copies a string into a software bus message -** -** Strings within software bus messages have a defined/fixed maximum length, and -** may not necessarily be null terminated within the message. This presents a possible -** issue when using the C library functions to copy strings out of a message. -** -** This performs a very similar function to "strncpy()" except that the sizes -** of _both_ buffers are passed in. Neither buffer is required to be null-terminated, -** but copying will stop after the first termination character is encountered. -** -** If the destination buffer is not completely filled by the source data (such as if -** the supplied string was shorter than the allotted length) the destination buffer -** will be padded with NUL characters up to the size of the buffer, similar to what -** strncpy() does. This ensures that the entire destination buffer is set. -** -** NOTE - if the source string buffer is already guaranteed to be null terminated, -** then there is no difference between the C library "strncpy()" function and this -** implementation. It is only necessary to use this when termination of the source -** buffer is not guaranteed. -** -** Arguments: -** DestStringPtr - pointer to destination buffer -** SourceStringPtr - pointer to source buffer (component of SB message definition) -** DestMaxSize - size of the destination storage buffer (must be at least 2) -** SourceMaxSize - size of the source buffer as defined by the message definition -** -** Returns: -** Length of result - number of actual data characters copied -** This should match the value that would be returned by "strlen(DestStringPtr)" -** -*/ -int32 CFE_SB_MessageStringSet(char *DestStringPtr, const char *SourceStringPtr, uint32 DestMaxSize, uint32 SourceMaxSize); +/** @defgroup CFEAPISBMessageID cFE Message ID APIs + * @{ + */ +/*****************************************************************************/ /** - * @brief Identifies whether a two CFE_SB_MsgId_t values are equal + * \brief Identifies whether a two #CFE_SB_MsgId_t values are equal * - * @par Description - * In cases where the CFE_SB_MsgId_t type is not a simple integer + * \par Description + * In cases where the #CFE_SB_MsgId_t type is not a simple integer * type, it may not be possible to do a direct equality check. * This inline function provides an abstraction for the equality - * check between two CFE_SB_MsgId_t values. + * check between two #CFE_SB_MsgId_t values. * * Applications should transition to using this function to compare * MsgId values for equality to remain compatible with future versions * of cFE. * - * @return true if equality checks passed, false otherwise. + * \return Boolean message ID equality indicator + * \retval true Message IDs are Equal + * \retval false Message IDs are not Equal */ static inline bool CFE_SB_MsgId_Equal(CFE_SB_MsgId_t MsgId1, CFE_SB_MsgId_t MsgId2) { @@ -1306,29 +1298,29 @@ static inline bool CFE_SB_MsgId_Equal(CFE_SB_MsgId_t MsgId1, CFE_SB_MsgId_t MsgI /*****************************************************************************/ /** - * @brief Converts a CFE_SB_MsgId_t to a normal integer + * \brief Converts a #CFE_SB_MsgId_t to a normal integer * - * @par Description - * In cases where the CFE_SB_MsgId_t type is not a simple integer + * \par Description + * In cases where the #CFE_SB_MsgId_t type is not a simple integer * type, it is not possible to directly display the value in a * printf-style statement, use it in a switch() statement, or other * similar use cases. * - * This inline function provides the ability to map a CFE_SB_MsgId_t + * This inline function provides the ability to map a #CFE_SB_MsgId_t * type back into a simple integer value. * * Applications should transition to using this function wherever a - * CFE_SB_MsgId_t type needs to be used as an integer. + * #CFE_SB_MsgId_t type needs to be used as an integer. * - * @par Assumptions and Notes: + * \par Assumptions and Notes: * This negates the type safety that was gained by using a non- - * integer type for the CFE_SB_MsgId_t value. This should only be used + * integer type for the #CFE_SB_MsgId_t value. This should only be used * in specific cases such as UI display (printf, events, etc) where the * value is being sent externally. Any internal API calls should be - * updated to use the CFE_SB_MsgId_t type directly, rather than an + * updated to use the #CFE_SB_MsgId_t type directly, rather than an * integer type. * - * @return Integer representation of the CFE_SB_MsgId_t + * \return Integer representation of the #CFE_SB_MsgId_t */ static inline CFE_SB_MsgId_Atom_t CFE_SB_MsgIdToValue(CFE_SB_MsgId_t MsgId) { @@ -1337,33 +1329,33 @@ static inline CFE_SB_MsgId_Atom_t CFE_SB_MsgIdToValue(CFE_SB_MsgId_t MsgId) /*****************************************************************************/ /** - * @brief Converts a normal integer into a CFE_SB_MsgId_t + * \brief Converts a normal integer into a #CFE_SB_MsgId_t * - * @par Description: - * In cases where the CFE_SB_MsgId_t type is not a simple integer + * \par Description + * In cases where the #CFE_SB_MsgId_t type is not a simple integer * type, it is not possible to directly use an integer value * supplied via a define or similar method. * * This inline function provides the ability to map an integer value - * into a corresponding CFE_SB_MsgId_t value. + * into a corresponding #CFE_SB_MsgId_t value. * * Applications should transition to using this function wherever an - * integer needs to be used for a CFE_SB_MsgId_t. + * integer needs to be used for a #CFE_SB_MsgId_t. * - * @par Assumptions and Notes: + * \par Assumptions and Notes: * This negates the type safety that was gained by using a non- - * integer type for the CFE_SB_MsgId_t value. This should only be + * integer type for the #CFE_SB_MsgId_t value. This should only be * used in specific cases where the value is coming from an external * source. Any internal API calls should be updated to return the - * CFE_SB_MsgId_t type directly, rather than an integer type. + * #CFE_SB_MsgId_t type directly, rather than an integer type. * - * @return CFE_SB_MsgId_t representation of the integer + * \return #CFE_SB_MsgId_t representation of the integer */ static inline CFE_SB_MsgId_t CFE_SB_ValueToMsgId(CFE_SB_MsgId_Atom_t MsgIdValue) { return MsgIdValue; } +/**@}*/ - -#endif /* _cfesb_ */ +#endif /* _cfe_sb_ */ /*****************************************************************************/ diff --git a/fsw/cfe-core/src/inc/cfe_sb_events.h b/fsw/cfe-core/src/inc/cfe_sb_events.h index f688332fa..190df22dc 100644 --- a/fsw/cfe-core/src/inc/cfe_sb_events.h +++ b/fsw/cfe-core/src/inc/cfe_sb_events.h @@ -234,8 +234,8 @@ ** ** \par Cause: ** -** This error event message is issued when the #CFE_SB_GetMsgIdByName API receives an -** invalid (possibly NULL) ptr as an argument. +** This error event message is issued when the #CFE_SB_GetPipeIdByName API receives a +** NULL ptr as an argument. **/ #define CFE_SB_GETPIPEIDBYNAME_NULL_ERR_EID 66 @@ -246,7 +246,7 @@ ** ** \par Cause: ** -** This error event message is issued when the #CFE_SB_GetMsgIdByName API receives an +** This error event message is issued when the #CFE_SB_GetPipeIdByName API receives an ** invalid name. **/ #define CFE_SB_GETPIPEIDBYNAME_NAME_ERR_EID 67 @@ -782,10 +782,8 @@ ** ** \par Cause: ** -** This error event message is issued from one of SB's subscribe API's when the -** function #CFE_SB_GetRoutingTblIdx returns an index that is out of range. This -** error is not expected and is an indication that the SB internal memory has been -** corrupted. +** This error event message is issued from CFE_SB_DeletePipeFull when an +** invalid pipe ID is passed in **/ #define CFE_SB_DEL_PIPE_ERR1_EID 46 diff --git a/fsw/cfe-core/src/inc/cfe_tbl.h b/fsw/cfe-core/src/inc/cfe_tbl.h index f963871d1..4c293f87c 100644 --- a/fsw/cfe-core/src/inc/cfe_tbl.h +++ b/fsw/cfe-core/src/inc/cfe_tbl.h @@ -46,31 +46,40 @@ #include "osconfig.h" /******************* Macro Definitions ***********************/ -#define CFE_TBL_OPT_BUFFER_MSK (0x0001) -#define CFE_TBL_OPT_SNGL_BUFFER (0x0000) -#define CFE_TBL_OPT_DBL_BUFFER (0x0001) -#define CFE_TBL_OPT_LD_DMP_MSK (0x0002) -#define CFE_TBL_OPT_LOAD_DUMP (0x0000) -#define CFE_TBL_OPT_DUMP_ONLY (0x0002) +/** @defgroup CFETBLTypeOptions cFE Table Type Defines + * @{ + */ +#define CFE_TBL_OPT_BUFFER_MSK (0x0001) /**< \brief Table buffer mask */ +#define CFE_TBL_OPT_SNGL_BUFFER (0x0000) /**< \brief Single buffer table */ +#define CFE_TBL_OPT_DBL_BUFFER (0x0001) /**< \brief Double buffer table */ + +#define CFE_TBL_OPT_LD_DMP_MSK (0x0002) /**< \brief Table load/dump mask */ +#define CFE_TBL_OPT_LOAD_DUMP (0x0000) /**< \brief Load/Dump table */ +#define CFE_TBL_OPT_DUMP_ONLY (0x0002) /**< \brief Dump only table */ -#define CFE_TBL_OPT_USR_DEF_MSK (0x0004) -#define CFE_TBL_OPT_NOT_USR_DEF (0x0000) -#define CFE_TBL_OPT_USR_DEF_ADDR (0x0006) /**< \brief NOTE: Automatically includes #CFE_TBL_OPT_DUMP_ONLY option */ +#define CFE_TBL_OPT_USR_DEF_MSK (0x0004) /**< \brief Table user defined mask */ +#define CFE_TBL_OPT_NOT_USR_DEF (0x0000) /**< \brief Not user defined table */ +#define CFE_TBL_OPT_USR_DEF_ADDR (0x0006) /**< \brief User Defined table, @note Automatically includes #CFE_TBL_OPT_DUMP_ONLY option */ -#define CFE_TBL_OPT_CRITICAL_MSK (0x0008) -#define CFE_TBL_OPT_NOT_CRITICAL (0x0000) -#define CFE_TBL_OPT_CRITICAL (0x0008) +#define CFE_TBL_OPT_CRITICAL_MSK (0x0008) /**< \brief Table critical mask */ +#define CFE_TBL_OPT_NOT_CRITICAL (0x0000) /**< \brief Not critical table */ +#define CFE_TBL_OPT_CRITICAL (0x0008) /**< \brief Critical table */ +/** @brief Default table options */ #define CFE_TBL_OPT_DEFAULT (CFE_TBL_OPT_SNGL_BUFFER | CFE_TBL_OPT_LOAD_DUMP) +/**@}*/ -/* +/** + * \brief Table maximum full name length + * * The full length of table names is defined at the mission scope. * This is defined here to support applications that depend on cfe_tbl.h * providing this value. */ #define CFE_TBL_MAX_FULL_NAME_LEN (CFE_MISSION_TBL_MAX_FULL_NAME_LEN) +/** \brief Bad table handle */ #define CFE_TBL_BAD_TABLE_HANDLE (CFE_TBL_Handle_t) 0xFFFF @@ -94,18 +103,23 @@ /****************** Data Type Definitions *********************/ +/** \brief Table Callback Function */ typedef int32 (*CFE_TBL_CallbackFuncPtr_t)(void *TblPtr); +/** \brief Table Handle primitive */ typedef int16 CFE_TBL_Handle_t; +/** \brief Table Source */ typedef enum { - CFE_TBL_SRC_FILE = 0, /**< When this option is selected, the \c SrcDataPtr + CFE_TBL_SRC_FILE = 0, /**< \brief File source + When this option is selected, the \c SrcDataPtr will be interpreted as a pointer to a null terminated character string. The string should specify the full path and filename of the file containing the initial data contents of the table. */ - CFE_TBL_SRC_ADDRESS /**< When this option is selected, the \c SrcDataPtr will + CFE_TBL_SRC_ADDRESS /**< \brief Address source + When this option is selected, the \c SrcDataPtr will be interpreted as a pointer to a memory location that is the beginning of the initialization data for loading the table OR, in the case of a "user defined" @@ -114,6 +128,7 @@ typedef enum specified in the #CFE_TBL_Register function Size parameter. */ } CFE_TBL_SrcEnum_t; +/** \brief Table Info */ typedef struct { uint32 Size; /**< \brief Size, in bytes, of Table */ @@ -131,6 +146,12 @@ typedef struct } CFE_TBL_Info_t; /*************************** Function Prototypes ******************************/ + +/** \defgroup CFEAPITBLRegistration cFE Registration APIs + * @{ + */ + +/*****************************************************************************/ /** ** \brief Register a table with cFE to obtain Table Management Services ** @@ -246,20 +267,18 @@ typedef struct ** \param[out] *TblHandlePtr Handle used to identify table to cFE when performing Table operations. ** This value is returned at the address specified by TblHandlePtr. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_RECOVERED_TBL \retdesc \copydoc CFE_TBL_INFO_RECOVERED_TBL \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_DUPLICATE_DIFF_SIZE \retdesc \copydoc CFE_TBL_ERR_DUPLICATE_DIFF_SIZE \endcode -** \retcode #CFE_TBL_ERR_DUPLICATE_NOT_OWNED \retdesc \copydoc CFE_TBL_ERR_DUPLICATE_NOT_OWNED \endcode -** \retcode #CFE_TBL_ERR_REGISTRY_FULL \retdesc \copydoc CFE_TBL_ERR_REGISTRY_FULL \endcode -** \retcode #CFE_TBL_ERR_HANDLES_FULL \retdesc \copydoc CFE_TBL_ERR_HANDLES_FULL \endcode -** \retcode #CFE_TBL_ERR_INVALID_SIZE \retdesc \copydoc CFE_TBL_ERR_INVALID_SIZE \endcode -** \retcode #CFE_TBL_ERR_INVALID_NAME \retdesc \copydoc CFE_TBL_ERR_INVALID_NAME \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_RECOVERED_TBL \copybrief CFE_TBL_INFO_RECOVERED_TBL +** \retval #CFE_TBL_ERR_DUPLICATE_DIFF_SIZE \copybrief CFE_TBL_ERR_DUPLICATE_DIFF_SIZE +** \retval #CFE_TBL_ERR_DUPLICATE_NOT_OWNED \copybrief CFE_TBL_ERR_DUPLICATE_NOT_OWNED +** \retval #CFE_TBL_ERR_REGISTRY_FULL \copybrief CFE_TBL_ERR_REGISTRY_FULL +** \retval #CFE_TBL_ERR_HANDLES_FULL \copybrief CFE_TBL_ERR_HANDLES_FULL +** \retval #CFE_TBL_ERR_INVALID_SIZE \copybrief CFE_TBL_ERR_INVALID_SIZE +** \retval #CFE_TBL_ERR_INVALID_NAME \copybrief CFE_TBL_ERR_INVALID_NAME +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_TBL_Unregister, #CFE_TBL_Share **/ @@ -298,15 +317,13 @@ int32 CFE_TBL_Register( CFE_TBL_Handle_t *TblHandlePtr, /* Ret ** \param[out] *TblHandlePtr Handle used to identify table to cFE when performing Table operations. ** This value is returned at the address specified by TblHandlePtr. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_HANDLES_FULL \retdesc \copydoc CFE_TBL_ERR_HANDLES_FULL \endcode -** \retcode #CFE_TBL_ERR_INVALID_NAME \retdesc \copydoc CFE_TBL_ERR_INVALID_NAME \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_ERR_HANDLES_FULL \copybrief CFE_TBL_ERR_HANDLES_FULL +** \retval #CFE_TBL_ERR_INVALID_NAME \copybrief CFE_TBL_ERR_INVALID_NAME +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_TBL_Unregister, #CFE_TBL_Register ** @@ -331,20 +348,23 @@ int32 CFE_TBL_Share( CFE_TBL_Handle_t *TblHandlePtr, /* Returned Handle */ ** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, ** that identifies the Table to be unregistered. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_TBL_Share, #CFE_TBL_Register ** ******************************************************************************/ int32 CFE_TBL_Unregister ( CFE_TBL_Handle_t TblHandle ); +/**@}*/ + +/** @defgroup CFEAPITBLManage cFE Manage Table Content APIs + * @{ + */ /*****************************************************************************/ /** @@ -367,33 +387,31 @@ int32 CFE_TBL_Unregister ( CFE_TBL_Handle_t TblHandle ); ** ** \param[in] SrcType Flag indicating the nature of the given \c SrcDataPtr below. ** This value can be any one of the following: -** \arg #CFE_TBL_SRC_FILE - \copydoc CFE_TBL_SRC_FILE -** \arg #CFE_TBL_SRC_ADDRESS - \copydoc CFE_TBL_SRC_ADDRESS +** \arg #CFE_TBL_SRC_FILE - \copybrief CFE_TBL_SRC_FILE +** \arg #CFE_TBL_SRC_ADDRESS - \copybrief CFE_TBL_SRC_ADDRESS ** ** \param[in] SrcDataPtr Pointer to either a character string specifying a filename or ** a memory address of a block of binary data to be loaded into a table or, ** if the table was registered with the #CFE_TBL_OPT_USR_DEF_ADDR option, ** the address of the active table buffer. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_WARN_SHORT_FILE \retdesc \copydoc CFE_TBL_WARN_SHORT_FILE \endcode -** \retcode #CFE_TBL_WARN_PARTIAL_LOAD \retdesc \copydoc CFE_TBL_WARN_PARTIAL_LOAD \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_DUMP_ONLY \retdesc \copydoc CFE_TBL_ERR_DUMP_ONLY \endcode -** \retcode #CFE_TBL_ERR_ILLEGAL_SRC_TYPE \retdesc \copydoc CFE_TBL_ERR_ILLEGAL_SRC_TYPE \endcode -** \retcode #CFE_TBL_ERR_LOAD_IN_PROGRESS \retdesc \copydoc CFE_TBL_ERR_LOAD_IN_PROGRESS \endcode -** \retcode #CFE_TBL_ERR_NO_BUFFER_AVAIL \retdesc \copydoc CFE_TBL_ERR_NO_BUFFER_AVAIL \endcode -** \retcode #CFE_TBL_ERR_FILE_NOT_FOUND \retdesc \copydoc CFE_TBL_ERR_FILE_NOT_FOUND \endcode -** \retcode #CFE_TBL_ERR_FILE_TOO_LARGE \retdesc \copydoc CFE_TBL_ERR_FILE_TOO_LARGE \endcode -** \retcode #CFE_TBL_ERR_BAD_CONTENT_ID \retdesc \copydoc CFE_TBL_ERR_BAD_CONTENT_ID \endcode -** \retcode #CFE_TBL_ERR_PARTIAL_LOAD \retdesc \copydoc CFE_TBL_ERR_PARTIAL_LOAD \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_WARN_SHORT_FILE \copybrief CFE_TBL_WARN_SHORT_FILE +** \retval #CFE_TBL_WARN_PARTIAL_LOAD \copybrief CFE_TBL_WARN_PARTIAL_LOAD +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_DUMP_ONLY \copybrief CFE_TBL_ERR_DUMP_ONLY +** \retval #CFE_TBL_ERR_ILLEGAL_SRC_TYPE \copybrief CFE_TBL_ERR_ILLEGAL_SRC_TYPE +** \retval #CFE_TBL_ERR_LOAD_IN_PROGRESS \copybrief CFE_TBL_ERR_LOAD_IN_PROGRESS +** \retval #CFE_TBL_ERR_NO_BUFFER_AVAIL \copybrief CFE_TBL_ERR_NO_BUFFER_AVAIL +** \retval #CFE_TBL_ERR_FILE_NOT_FOUND \copybrief CFE_TBL_ERR_FILE_NOT_FOUND +** \retval #CFE_TBL_ERR_FILE_TOO_LARGE \copybrief CFE_TBL_ERR_FILE_TOO_LARGE +** \retval #CFE_TBL_ERR_BAD_CONTENT_ID \copybrief CFE_TBL_ERR_BAD_CONTENT_ID +** \retval #CFE_TBL_ERR_PARTIAL_LOAD \copybrief CFE_TBL_ERR_PARTIAL_LOAD ** ** \sa #CFE_TBL_Update, #CFE_TBL_Validate, #CFE_TBL_Manage ** @@ -421,22 +439,147 @@ int32 CFE_TBL_Load( CFE_TBL_Handle_t TblHandle, ** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, that ** identifies the Table to be updated. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_NO_UPDATE_PENDING \retdesc \copydoc CFE_TBL_INFO_NO_UPDATE_PENDING \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_NO_UPDATE_PENDING \copybrief CFE_TBL_INFO_NO_UPDATE_PENDING +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER ** ** \sa #CFE_TBL_Load, #CFE_TBL_Validate, #CFE_TBL_Manage ** ******************************************************************************/ int32 CFE_TBL_Update( CFE_TBL_Handle_t TblHandle ); +/*****************************************************************************/ +/** +** \brief Perform steps to validate the contents of a table image. +** +** \par Description +** An application is \b required to perform a periodic check for an update +** or a validation request for all the tables that it creates. Typically, +** the application that created the table would call this function at the +** start or conclusion of any routine processing cycle. To determine whether +** a validation request is pending prior to making this call, the Application +** can use the #CFE_TBL_GetStatus API first. If a table validation is pending, +** the Application would call this function to perform the necessary actions. +** +** \par Assumptions, External Events, and Notes: +** None +** +** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, that +** identifies the Table to be managed. +** +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_NO_VALIDATION_PENDING \copybrief CFE_TBL_INFO_NO_VALIDATION_PENDING +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** +** \sa #CFE_TBL_Update, #CFE_TBL_Manage, #CFE_TBL_Load +** +******************************************************************************/ +int32 CFE_TBL_Validate( CFE_TBL_Handle_t TblHandle ); + +/*****************************************************************************/ +/** +** \brief Perform standard operations to maintain a table. +** +** \par Description +** An application is \b required to perform a periodic check for an update +** or a validation request for all the tables that it creates. Typically, +** the application that created the table would call this function at the +** start or conclusion of any routine processing cycle. If a table update +** or validation request is pending, this function would perform either or +** both before returning. +** +** \par Assumptions, External Events, and Notes: +** None +** +** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, that +** identifies the Table to be managed. +** +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_UPDATED \copybrief CFE_TBL_INFO_UPDATED +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** +** \sa #CFE_TBL_Update, #CFE_TBL_Validate, #CFE_TBL_Load, #CFE_TBL_DumpToBuffer +** +******************************************************************************/ +int32 CFE_TBL_Manage( CFE_TBL_Handle_t TblHandle ); + +/*****************************************************************************/ +/** +** \brief Copies the contents of a Dump Only Table to a shared buffer +** +** \par Description +** Copies contents of a Dump Only table to a shared buffer so that it +** can be written to a file by the Table Services routine. This function +** is called by the Application that owns the table in response to a #CFE_TBL_INFO_DUMP_PENDING +** status obtained via #CFE_TBL_GetStatus. +** +** \par Assumptions, External Events, and Notes: +** -# If the table does not have a dump pending status, nothing will occur (no error, no dump) +** -# Applications may wish to use this function in lieu of #CFE_TBL_Manage for their Dump Only tables +** +** \param[in] TblHandle Handle of Table to be dumped. +** +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** +** \sa #CFE_TBL_Manage +** +******************************************************************************/ +int32 CFE_TBL_DumpToBuffer( CFE_TBL_Handle_t TblHandle ); + +/*****************************************************************************/ +/** +** \brief Notify cFE Table Services that table contents have been modified by the Application +** +** \par Description +** This API notifies Table Services that the contents of the specified table has been +** modified by the Application. This notification is important when a table has been +** registered as "Critical" because Table Services can then update the contents of the +** table kept in the Critical Data Store. +** +** \par Assumptions, External Events, and Notes: +** None +** +** \param[in] TblHandle Handle of Table that was modified. +** +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** +** \sa #CFE_TBL_Manage +** +******************************************************************************/ +int32 CFE_TBL_Modified( CFE_TBL_Handle_t TblHandle ); +/**@}*/ + +/** @defgroup CFEAPITBLAccess cFE Access Table Content APIs + * @{ + */ + /*****************************************************************************/ /** ** \brief Obtain the current address of the contents of the specified table @@ -468,18 +611,16 @@ int32 CFE_TBL_Update( CFE_TBL_Handle_t TblHandle ); ** ** \param[out] *TblPtr Address of the first byte of data associated with the specified table. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_UPDATED \retdesc \copydoc CFE_TBL_INFO_UPDATED \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_UNREGISTERED \retdesc \copydoc CFE_TBL_ERR_UNREGISTERED \endcode -** \retcode #CFE_TBL_ERR_NEVER_LOADED \retdesc \copydoc CFE_TBL_ERR_NEVER_LOADED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_UPDATED \copybrief CFE_TBL_INFO_UPDATED +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_UNREGISTERED \copybrief CFE_TBL_ERR_UNREGISTERED +** \retval #CFE_TBL_ERR_NEVER_LOADED \copybrief CFE_TBL_ERR_NEVER_LOADED ** ** \sa #CFE_TBL_ReleaseAddress, #CFE_TBL_GetAddresses, #CFE_TBL_ReleaseAddresses ** @@ -504,17 +645,15 @@ int32 CFE_TBL_GetAddress( void **TblPtr, ** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, that ** identifies the Table whose address is to be released. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_UPDATED \retdesc \copydoc CFE_TBL_INFO_UPDATED \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_NEVER_LOADED \retdesc \copydoc CFE_TBL_ERR_NEVER_LOADED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_UPDATED \copybrief CFE_TBL_INFO_UPDATED +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_NEVER_LOADED \copybrief CFE_TBL_ERR_NEVER_LOADED ** ** \sa #CFE_TBL_GetAddress, #CFE_TBL_GetAddresses, #CFE_TBL_ReleaseAddresses ** @@ -554,18 +693,16 @@ int32 CFE_TBL_ReleaseAddress( CFE_TBL_Handle_t TblHandle ); ** \param[out] *TblPtrs Array of addresses of the first byte of data associated with the ** specified tables. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_UPDATED \retdesc \copydoc CFE_TBL_INFO_UPDATED \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_UNREGISTERED \retdesc \copydoc CFE_TBL_ERR_UNREGISTERED \endcode -** \retcode #CFE_TBL_ERR_NEVER_LOADED \retdesc \copydoc CFE_TBL_ERR_NEVER_LOADED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_UPDATED \copybrief CFE_TBL_INFO_UPDATED +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_UNREGISTERED \copybrief CFE_TBL_ERR_UNREGISTERED +** \retval #CFE_TBL_ERR_NEVER_LOADED \copybrief CFE_TBL_ERR_NEVER_LOADED ** ** \sa #CFE_TBL_GetAddress, #CFE_TBL_ReleaseAddress, #CFE_TBL_ReleaseAddresses ** @@ -593,92 +730,26 @@ int32 CFE_TBL_GetAddresses( void **TblPtrs[], ** \param[in] TblHandles Array of Table Handles, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, ** of those tables whose start addresses are to be released. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_UPDATED \retdesc \copydoc CFE_TBL_INFO_UPDATED \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_NEVER_LOADED \retdesc \copydoc CFE_TBL_ERR_NEVER_LOADED \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_UPDATED \copybrief CFE_TBL_INFO_UPDATED +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_NEVER_LOADED \copybrief CFE_TBL_ERR_NEVER_LOADED ** ** \sa #CFE_TBL_GetAddress, #CFE_TBL_ReleaseAddress, #CFE_TBL_GetAddresses ** ******************************************************************************/ int32 CFE_TBL_ReleaseAddresses( uint16 NumTables, const CFE_TBL_Handle_t TblHandles[] ); +/**@}*/ -/*****************************************************************************/ -/** -** \brief Perform steps to validate the contents of a table image. -** -** \par Description -** An application is \b required to perform a periodic check for an update -** or a validation request for all the tables that it creates. Typically, -** the application that created the table would call this function at the -** start or conclusion of any routine processing cycle. To determine whether -** a validation request is pending prior to making this call, the Application -** can use the #CFE_TBL_GetStatus API first. If a table validation is pending, -** the Application would call this function to perform the necessary actions. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, that -** identifies the Table to be managed. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_NO_VALIDATION_PENDING \retdesc \copydoc CFE_TBL_INFO_NO_VALIDATION_PENDING \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \endreturns -** -** \sa #CFE_TBL_Update, #CFE_TBL_Manage, #CFE_TBL_Load -** -******************************************************************************/ -int32 CFE_TBL_Validate( CFE_TBL_Handle_t TblHandle ); - -/*****************************************************************************/ -/** -** \brief Perform standard operations to maintain a table. -** -** \par Description -** An application is \b required to perform a periodic check for an update -** or a validation request for all the tables that it creates. Typically, -** the application that created the table would call this function at the -** start or conclusion of any routine processing cycle. If a table update -** or validation request is pending, this function would perform either or -** both before returning. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, that -** identifies the Table to be managed. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_UPDATED \retdesc \copydoc CFE_TBL_INFO_UPDATED \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \endreturns -** -** \sa #CFE_TBL_Update, #CFE_TBL_Validate, #CFE_TBL_Load, #CFE_TBL_DumpToBuffer -** -******************************************************************************/ -int32 CFE_TBL_Manage( CFE_TBL_Handle_t TblHandle ); +/** @defgroup CFEAPITBLInfo cFE Get Table Information APIs + * @{ + */ /*****************************************************************************/ /** @@ -698,25 +769,22 @@ int32 CFE_TBL_Manage( CFE_TBL_Handle_t TblHandle ); ** \param[in] TblHandle Handle, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, that ** identifies the Table to be managed. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TBL_INFO_UPDATE_PENDING \retdesc \copydoc CFE_TBL_INFO_UPDATE_PENDING \endcode -** \retcode #CFE_TBL_INFO_VALIDATION_PENDING \retdesc \copydoc CFE_TBL_INFO_VALIDATION_PENDING \endcode -** \retcode #CFE_TBL_INFO_DUMP_PENDING \retdesc \copydoc CFE_TBL_INFO_DUMP_PENDING \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_UPDATE_PENDING \copybrief CFE_TBL_INFO_UPDATE_PENDING +** \retval #CFE_TBL_INFO_VALIDATION_PENDING \copybrief CFE_TBL_INFO_VALIDATION_PENDING +** \retval #CFE_TBL_INFO_DUMP_PENDING \copybrief CFE_TBL_INFO_DUMP_PENDING +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE ** ** \sa #CFE_TBL_Manage, #CFE_TBL_Update, #CFE_TBL_Validate, #CFE_TBL_GetInfo ** ******************************************************************************/ int32 CFE_TBL_GetStatus( CFE_TBL_Handle_t TblHandle ); - /*****************************************************************************/ /** ** \brief Obtain characteristics/information of/about a specified table. @@ -743,79 +811,15 @@ int32 CFE_TBL_GetStatus( CFE_TBL_Handle_t TblHandle ); ** \param[out] *TblInfoPtr Description of the tables characteristics and registry information stored in ** the #CFE_TBL_Info_t data structure format. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_TBL_ERR_INVALID_NAME \retdesc \copydoc CFE_TBL_ERR_INVALID_NAME \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_ERR_INVALID_NAME \copybrief CFE_TBL_ERR_INVALID_NAME ** ** \sa #CFE_TBL_GetStatus ** ******************************************************************************/ int32 CFE_TBL_GetInfo( CFE_TBL_Info_t *TblInfoPtr, const char *TblName ); -/*****************************************************************************/ -/** -** \brief Copies the contents of a Dump Only Table to a shared buffer -** -** \par Description -** Copies contents of a Dump Only table to a shared buffer so that it -** can be written to a file by the Table Services routine. This function -** is called by the Application that owns the table in response to a #CFE_TBL_INFO_DUMP_PENDING -** status obtained via #CFE_TBL_GetStatus. -** -** \par Assumptions, External Events, and Notes: -** -# If the table does not have a dump pending status, nothing will occur (no error, no dump) -** -# Applications may wish to use this function in lieu of #CFE_TBL_Manage for their Dump Only tables -** -** \param[in] TblHandle Handle of Table to be dumped. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \endreturns -** -** \sa #CFE_TBL_Manage -** -******************************************************************************/ -int32 CFE_TBL_DumpToBuffer( CFE_TBL_Handle_t TblHandle ); - -/*****************************************************************************/ -/** -** \brief Notify cFE Table Services that table contents have been modified by the Application -** -** \par Description -** This API notifies Table Services that the contents of the specified table has been -** modified by the Application. This notification is important when a table has been -** registered as "Critical" because Table Services can then update the contents of the -** table kept in the Critical Data Store. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \param[in] TblHandle Handle of Table that was modified. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \endreturns -** -** \sa #CFE_TBL_Manage -** -******************************************************************************/ -int32 CFE_TBL_Modified( CFE_TBL_Handle_t TblHandle ); - - /*****************************************************************************/ /** ** \brief Instruct cFE Table Services to notify Application via message when table requires management @@ -843,19 +847,18 @@ int32 CFE_TBL_Modified( CFE_TBL_Handle_t TblHandle ); ** table index that allows the same MsgId and Command Code to be used for ** all table management notifications. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode \retdesc \endcode -** \retcode #CFE_ES_ERR_APPNAME \retdesc \copydoc CFE_ES_ERR_APPNAME \endcode -** \retcode #CFE_ES_ERR_BUFFER \retdesc \copydoc CFE_ES_ERR_BUFFER \endcode -** \retcode #CFE_TBL_ERR_BAD_APP_ID \retdesc \copydoc CFE_TBL_ERR_BAD_APP_ID \endcode -** \retcode #CFE_TBL_ERR_NO_ACCESS \retdesc \copydoc CFE_TBL_ERR_NO_ACCESS \endcode -** \retcode #CFE_TBL_ERR_INVALID_HANDLE \retdesc \copydoc CFE_TBL_ERR_INVALID_HANDLE \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_APPNAME \copybrief CFE_ES_ERR_APPNAME +** \retval #CFE_ES_ERR_BUFFER \copybrief CFE_ES_ERR_BUFFER +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE ** ** \sa #CFE_TBL_Register ** ******************************************************************************/ int32 CFE_TBL_NotifyByMessage(CFE_TBL_Handle_t TblHandle, CFE_SB_MsgId_t MsgId, uint16 CommandCode, uint32 Parameter); +/**@}*/ #endif /* _cfe_tbl_ */ diff --git a/fsw/cfe-core/src/inc/cfe_time.h b/fsw/cfe-core/src/inc/cfe_time.h index c7b777bc8..fa4049d7e 100644 --- a/fsw/cfe-core/src/inc/cfe_time.h +++ b/fsw/cfe-core/src/inc/cfe_time.h @@ -37,17 +37,17 @@ /* -** Required header files... +** Includes */ #include "cfe_time_extern_typedefs.h" #include "common_types.h" - +/*****************************************************************************/ /* -** Defines +** Macro Definitions */ -#define CFE_TIME_PRINTED_STRING_SIZE 24 /**< \brief Required size of buffer to be passed into #CFE_TIME_Print (includes null terminator) */ +#define CFE_TIME_PRINTED_STRING_SIZE 24 /**< \brief Required size of buffer to be passed into #CFE_TIME_Print (includes null terminator) */ /* * To preserve source-code compatibility with existing code, @@ -96,10 +96,11 @@ #endif /* CFE_OMIT_DEPRECATED_6_6 */ - +/*****************************************************************************/ /* -** Type definition (system time)... +** Type Definitions */ + /** ** \brief Data structure used to hold system time values ** @@ -117,16 +118,15 @@ typedef struct uint32 Subseconds; /**< \brief Number of subseconds since epoch (LSB = 2^(-32) seconds) */ } CFE_TIME_SysTime_t; -/* +/** +** \brief Time Copy +** ** Macro to copy systime into another systime. ** Preferred to use this macro as it does not require the two arguments to be exactly the same type, ** it will work with any two structures that define "Seconds" and "Subseconds" members. */ #define CFE_TIME_Copy(m,t) { (m)->Seconds = (t)->Seconds; (m)->Subseconds = (t)->Subseconds; } -/* -** Type definition (time comparison results)... -*/ /** ** \brief Enumerated types identifying the relative relationships of two times ** @@ -142,9 +142,6 @@ typedef enum CFE_TIME_A_GT_B = 1 /**< \brief The first specified time is considered to be after the second specified time */ } CFE_TIME_Compare_t; -/* -** Type definition (time portion the ES Reset data structure) -*/ /** ** \brief Time related variables that are maintained through a Processor Reset ** @@ -174,9 +171,15 @@ typedef struct */ typedef int32 (*CFE_TIME_SynchCallbackPtr_t)(void); +/*****************************************************************************/ /* -** Function prototypes (get time)... +** Exported Functions */ + +/** @defgroup CFEAPITIMEGetCurrent cFE Get Current Time APIs + * @{ + */ + /*****************************************************************************/ /** ** \brief Get the current spacecraft time @@ -192,28 +195,26 @@ typedef int32 (*CFE_TIME_SynchCallbackPtr_t)(void); ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retcode #CFE_TIME_SysTime_t \retdesc The current spacecraft time \endcode -** \endreturns +** \return The current spacecraft time in default format ** ** \sa #CFE_TIME_GetTAI, #CFE_TIME_GetUTC, #CFE_TIME_GetMET, ** #CFE_TIME_GetMETseconds, #CFE_TIME_GetMETsubsecs ** ******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_GetTime(void); /* returns default time (see default time selection above) */ +CFE_TIME_SysTime_t CFE_TIME_GetTime(void); /*****************************************************************************/ /** -** \brief Get the current TAI time +** \brief Get the current TAI (MET + SCTF) time ** ** \par Description ** This routine returns the current TAI time to the caller. TAI is an ** international time standard that does not include leap seconds. ** This routine should only be used in situations where TAI is absolutely -** required. Applications that call #CFE_TIME_GetTAI() may not be portable +** required. Applications that call #CFE_TIME_GetTAI may not be portable ** to all missions. Maintenance of correct TAI in flight is not guaranteed ** under all mission operations scenarios. To maintain re-usability across -** missions, most applications should be using #CFE_TIME_GetTime(), rather +** missions, most applications should be using #CFE_TIME_GetTime, rather ** than the specific routines for getting UTC/TAI directly. ** ** \par Assumptions, External Events, and Notes: @@ -224,165 +225,128 @@ CFE_TIME_SysTime_t CFE_TIME_GetTime(void); /* returns default time (see defau ** spacecraft clock is set or adjusted by operators. Applications using ** this function must be able to handle these time discontinuities gracefully. ** -** \returns -** \retcode #CFE_TIME_SysTime_t \retdesc The current TAI time \endcode -** \endreturns +** \return The current spacecraft time in TAI ** ** \sa #CFE_TIME_GetTime, #CFE_TIME_GetUTC, #CFE_TIME_GetMET, ** #CFE_TIME_GetMETseconds, #CFE_TIME_GetMETsubsecs ** ******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_GetTAI(void); /* returns time computed as TAI (MET + STCF) */ +CFE_TIME_SysTime_t CFE_TIME_GetTAI(void); /*****************************************************************************/ /** -** \brief Get the current UTC time +** \brief Get the current UTC (MET + SCTF - Leap Seconds) time ** ** \par Description ** This routine returns the current UTC time to the caller. This routine ** should only be used in situations where UTC is absolutely required. -** Applications that call #CFE_TIME_GetUTC() may not be portable to all +** Applications that call #CFE_TIME_GetUTC may not be portable to all ** missions. Maintenance of correct UTC in flight is not guaranteed under ** all mission operations scenarios. If UTC is maintained in flight, it will ** jump backwards occasionally due to leap second adjustments. To maintain ** re-usability across missions, most applications should be using -** #CFE_TIME_GetTime(), rather than the specific routines for getting +** #CFE_TIME_GetTime, rather than the specific routines for getting ** UTC/TAI directly. ** ** \par Assumptions, External Events, and Notes: ** Note: The "UTC" time returned is referenced to the mission-defined time epoch, ** which may or may not be the same as the standard UTC epoch. ** -** \returns -** \retcode #CFE_TIME_SysTime_t \retdesc The current UTC time \endcode -** \endreturns +** \return The current spacecraft time in UTC ** ** \sa #CFE_TIME_GetTime, #CFE_TIME_GetTAI, #CFE_TIME_GetMET, ** #CFE_TIME_GetMETseconds, #CFE_TIME_GetMETsubsecs ** ******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_GetUTC(void); /* returns time computed as UTC (MET + STCF - Leap Seconds) */ +CFE_TIME_SysTime_t CFE_TIME_GetUTC(void); /*****************************************************************************/ /** -** \brief Convert specified MET into Spacecraft Time +** \brief Get the current value of the Mission Elapsed Time (MET). ** ** \par Description -** This function returns Spacecraft Time given MET. Note that Spacecraft -** Time is returned as either UTC or TAI depeneding on whether the mission -** configuration parameter #CFE_MISSION_TIME_CFG_DEFAULT_UTC or #CFE_MISSION_TIME_CFG_DEFAULT_TAI -** was set to true at compile time. +** This routine returns the current mission-elapsed time (MET). MET is +** usually derived from a hardware-based clock that is not adjusted +** during normal operations. Callers of this routine should not assume +** that the MET return value has any specific relationship to any +** ground-based time standard. ** ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in] METTime The MET to be converted. -** -** \returns -** \retcode #CFE_TIME_SysTime_t \retdesc Spacecraft Time (UTC or TAI) corresponding to the specified MET \endcode -** \endreturns -** -** \sa #CFE_TIME_GetMET, #CFE_TIME_GetMETseconds, #CFE_TIME_GetMETsubsecs, -** #CFE_TIME_Sub2MicroSecs, #CFE_TIME_Micro2SubSecs, #CFE_TIME_CFE2FSSeconds, #CFE_TIME_FS2CFESeconds -** -******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_MET2SCTime (CFE_TIME_SysTime_t METTime); /* returns given MET time as the default spacecraft time */ - -/* -** Function prototypes (get parts of time)... -*/ - -/*****************************************************************************/ -/** -** \brief Get the current value of the spacecraft time correction factor (STCF). -** -** \par Description -** This routine returns the current value of the spacecraft time correction -** factor. This is the delta time between the MET and the TAI time. -** Applications cannot set or adjust the STCF; that can only be done -** through ground commands. However, science applications may want to -** include the STCF in their data products to aid in time correlation -** during downstream science data processing. -** -** \par Assumptions, External Events, and Notes: -** None +** \return The current MET ** -** \returns -** \retcode #CFE_TIME_SysTime_t \retdesc The current STCF \endcode -** \endreturns +** \sa #CFE_TIME_GetTime, #CFE_TIME_GetTAI, #CFE_TIME_GetUTC, +** #CFE_TIME_GetMETseconds, #CFE_TIME_GetMETsubsecs, #CFE_TIME_MET2SCTime ** -** \sa #CFE_TIME_GetLeapSeconds, #CFE_TIME_GetClockState, #CFE_TIME_GetClockInfo -** ******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_GetSTCF(void); /* returns STCF (does not include leap seconds calculation) */ +CFE_TIME_SysTime_t CFE_TIME_GetMET(void); /*****************************************************************************/ /** -** \brief Get the current value of the Mission Elapsed Time (MET). +** \brief Get the current seconds count of the mission-elapsed time. ** ** \par Description -** This routine returns the current mission-elapsed time (MET). MET is -** usually derived from a hardware-based clock that is not adjusted -** during normal operations. Callers of this routine should not assume -** that the MET return value has any specific relationship to any -** ground-based time standard. +** This routine is the same as #CFE_TIME_GetMET, except that it +** returns only the integer seconds portion of the MET time. ** ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retcode #CFE_TIME_SysTime_t \retdesc The current MET \endcode -** \endreturns +** \return The current MET seconds ** -** \sa #CFE_TIME_GetTime, #CFE_TIME_GetTAI, #CFE_TIME_GetUTC, -** #CFE_TIME_GetMETseconds, #CFE_TIME_GetMETsubsecs, #CFE_TIME_MET2SCTime +** \sa #CFE_TIME_GetTime, #CFE_TIME_GetTAI, #CFE_TIME_GetUTC, #CFE_TIME_GetMET, +** #CFE_TIME_GetMETsubsecs, #CFE_TIME_MET2SCTime ** ******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_GetMET(void); /* returns MET (both seconds and sub-seconds) */ - +uint32 CFE_TIME_GetMETseconds(void); /*****************************************************************************/ /** -** \brief Get the current seconds count of the mission-elapsed time. +** \brief Get the current sub-seconds count of the mission-elapsed time. ** ** \par Description -** This routine is the same as #CFE_TIME_GetMET(), except that it -** returns only the integer seconds portion of the MET time. +** This routine is the same as #CFE_TIME_GetMET, except that it +** returns only the integer sub-seconds portion of the MET time. +** Each count is equal to 2^(-32) seconds. ** ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retstmt The current MET seconds \endstmt -** \endreturns +** \return The current MET sub-seconds ** -** \sa #CFE_TIME_GetTime, #CFE_TIME_GetTAI, #CFE_TIME_GetUTC, #CFE_TIME_GetMET, -** #CFE_TIME_GetMETsubsecs, #CFE_TIME_MET2SCTime +** \sa #CFE_TIME_GetTime, #CFE_TIME_GetTAI, #CFE_TIME_GetUTC, #CFE_TIME_GetMET, +** #CFE_TIME_GetMETseconds, #CFE_TIME_MET2SCTime ** ******************************************************************************/ -uint32 CFE_TIME_GetMETseconds(void); /* returns MET "seconds" portion of current time */ +uint32 CFE_TIME_GetMETsubsecs(void); +/**@}*/ + +/** @defgroup CFEAPITIMEGetInfo cFE Get Time Information APIs + * @{ + */ /*****************************************************************************/ /** -** \brief Get the current sub-seconds count of the mission-elapsed time. +** \brief Get the current value of the spacecraft time correction factor (STCF). ** ** \par Description -** This routine is the same as #CFE_TIME_GetMET(), except that it -** returns only the integer sub-seconds portion of the MET time. -** Each count is equal to 2^(-32) seconds. +** This routine returns the current value of the spacecraft time correction +** factor. This is the delta time between the MET and the TAI time. +** Applications cannot set or adjust the STCF; that can only be done +** through ground commands. However, science applications may want to +** include the STCF in their data products to aid in time correlation +** during downstream science data processing. ** ** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retstmt The current MET sub-seconds \endstmt -** \endreturns +** Does not include leap seconds ** -** \sa #CFE_TIME_GetTime, #CFE_TIME_GetTAI, #CFE_TIME_GetUTC, #CFE_TIME_GetMET, -** #CFE_TIME_GetMETseconds, #CFE_TIME_MET2SCTime +** \return The current SCTF ** +** \sa #CFE_TIME_GetLeapSeconds, #CFE_TIME_GetClockState, #CFE_TIME_GetClockInfo +** ******************************************************************************/ -uint32 CFE_TIME_GetMETsubsecs(void); /* returns MET "sub-seconds" portion of current time */ +CFE_TIME_SysTime_t CFE_TIME_GetSTCF(void); /*****************************************************************************/ /** @@ -403,18 +367,12 @@ uint32 CFE_TIME_GetMETsubsecs(void); /* returns MET "sub-seconds" porti ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retstmt The current leap seconds. \endstmt -** \endreturns +** \returns The current spacecraft leap seconds. ** ** \sa #CFE_TIME_GetSTCF, #CFE_TIME_GetClockState, #CFE_TIME_GetClockInfo ** ******************************************************************************/ -int16 CFE_TIME_GetLeapSeconds(void); /* returns Leap Seconds portion of current time */ - -/* -** Function prototypes (get time status)... -*/ +int16 CFE_TIME_GetLeapSeconds(void); /*****************************************************************************/ /** @@ -429,14 +387,12 @@ int16 CFE_TIME_GetLeapSeconds(void); /* returns Leap Seconds portion of ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retcode #CFE_TIME_ClockState_Enum_t \retdesc The current spacecraft clock state \endcode -** \endreturns +** \return The current spacecraft clock state ** ** \sa #CFE_TIME_GetSTCF, #CFE_TIME_GetLeapSeconds, #CFE_TIME_GetClockInfo ** ******************************************************************************/ -CFE_TIME_ClockState_Enum_t CFE_TIME_GetClockState(void); /* returns current spacecraft clock state */ +CFE_TIME_ClockState_Enum_t CFE_TIME_GetClockState(void); /*****************************************************************************/ /** @@ -448,34 +404,21 @@ CFE_TIME_ClockState_Enum_t CFE_TIME_GetClockState(void); /* returns current s ** \par Assumptions, External Events, and Notes: ** None ** -** \returns -** \retstmt Spacecraft clock information. To extract the information from the -** returned value, the following masks can be used as in the following: -** if ((ReturnValue & CFE_TIME_FLAG_xxxxxx) == CFE_TIME_FLAG_xxxxxx) then -** the following definition of the \c CFE_TIME_FLAG_xxxxxx is true. \endstmt -** \retcode #CFE_TIME_FLAG_CLKSET \retdesc \copydoc CFE_TIME_FLAG_CLKSET \endcode -** \retcode #CFE_TIME_FLAG_FLYING \retdesc \copydoc CFE_TIME_FLAG_FLYING \endcode -** \retcode #CFE_TIME_FLAG_SRCINT \retdesc \copydoc CFE_TIME_FLAG_SRCINT \endcode -** \retcode #CFE_TIME_FLAG_SIGPRI \retdesc \copydoc CFE_TIME_FLAG_SIGPRI \endcode -** \retcode #CFE_TIME_FLAG_SRVFLY \retdesc \copydoc CFE_TIME_FLAG_SRVFLY \endcode -** \retcode #CFE_TIME_FLAG_CMDFLY \retdesc \copydoc CFE_TIME_FLAG_CMDFLY \endcode -** \retcode #CFE_TIME_FLAG_ADDADJ \retdesc \copydoc CFE_TIME_FLAG_ADDADJ \endcode -** \retcode #CFE_TIME_FLAG_ADD1HZ \retdesc \copydoc CFE_TIME_FLAG_ADD1HZ \endcode -** \retcode #CFE_TIME_FLAG_ADDTCL \retdesc \copydoc CFE_TIME_FLAG_ADDTCL \endcode -** \retcode #CFE_TIME_FLAG_SERVER \retdesc \copydoc CFE_TIME_FLAG_SERVER \endcode -** \retcode #CFE_TIME_FLAG_GDTONE \retdesc \copydoc CFE_TIME_FLAG_GDTONE \endcode -** \retcode #CFE_TIME_FLAG_UNUSED \retdesc \copydoc CFE_TIME_FLAG_UNUSED \endcode -** \endreturns +** \return Spacecraft clock information, \ref CFETIMEClkStates. +** To extract the information from the +** returned value, the flags can be used as in the following: +** if ((ReturnValue & CFE_TIME_FLAG_xxxxxx) == CFE_TIME_FLAG_xxxxxx) then +** the following definition of the \c CFE_TIME_FLAG_xxxxxx is true. ** ** \sa #CFE_TIME_GetSTCF, #CFE_TIME_GetLeapSeconds, #CFE_TIME_GetClockState ** ******************************************************************************/ -uint16 CFE_TIME_GetClockInfo(void); /* returns clock information */ +uint16 CFE_TIME_GetClockInfo(void); +/**@}*/ - -/* -** Function prototypes (add/subtract/compare time)... -*/ +/** @defgroup CFEAPITIMEArithmetic cFE Time Arithmetic APIs + * @{ + */ /*****************************************************************************/ /** @@ -494,16 +437,14 @@ uint16 CFE_TIME_GetClockInfo(void); /* returns clock information */ ** ** \param[in] Time2 The second time to be added. ** -** \returns -** \retstmt The sum of the two times, in the #CFE_TIME_SysTime_t format described above. -** If the sum is greater than the maximum value that can be stored in a -** #CFE_TIME_SysTime_t, the result will roll over (this is not considered an error). \endstmt -** \endreturns +** \return The sum of the two times. +** If the sum is greater than the maximum value that can be stored in a +** #CFE_TIME_SysTime_t, the result will roll over (this is not considered an error). ** ** \sa #CFE_TIME_Subtract, #CFE_TIME_Compare ** ******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_Add(CFE_TIME_SysTime_t Time1, CFE_TIME_SysTime_t Time2); /* (Time1 + Time2) */ +CFE_TIME_SysTime_t CFE_TIME_Add(CFE_TIME_SysTime_t Time1, CFE_TIME_SysTime_t Time2); /*****************************************************************************/ /** @@ -525,16 +466,14 @@ CFE_TIME_SysTime_t CFE_TIME_Add(CFE_TIME_SysTime_t Time1, CFE_TIME_SysTime_t Ti ** ** \param[in] Time2 The time to be subtracted from the base time. ** -** \returns -** \retstmt The result of subtracting the two times, in the #CFE_TIME_SysTime_t -** format. If the subtraction results in an underflow, the result will -** roll over (this is not considered an error). \endstmt -** \endreturns +** \return The result of subtracting the two times. +** If the subtraction results in an underflow, the result will +** roll over (this is not considered an error). ** ** \sa #CFE_TIME_Add, #CFE_TIME_Compare ** ******************************************************************************/ -CFE_TIME_SysTime_t CFE_TIME_Subtract(CFE_TIME_SysTime_t Time1, CFE_TIME_SysTime_t Time2); /* (Time1 - Time2) */ +CFE_TIME_SysTime_t CFE_TIME_Subtract(CFE_TIME_SysTime_t Time1, CFE_TIME_SysTime_t Time2); /*****************************************************************************/ /** @@ -563,21 +502,43 @@ CFE_TIME_SysTime_t CFE_TIME_Subtract(CFE_TIME_SysTime_t Time1, CFE_TIME_SysTime ** ** \param[in] TimeB The second time to compare. ** -** \returns -** \retstmt The result of comparing the two times, one of: \endstmt -** \retcode #CFE_TIME_EQUAL \retdesc \copydoc CFE_TIME_EQUAL \endcode -** \retcode #CFE_TIME_A_GT_B \retdesc \copydoc CFE_TIME_A_GT_B \endcode -** \retcode #CFE_TIME_A_LT_B \retdesc \copydoc CFE_TIME_A_LT_B \endcode -** \endreturns +** \return The result of comparing the two times. +** \retval #CFE_TIME_EQUAL \copybrief CFE_TIME_EQUAL +** \retval #CFE_TIME_A_GT_B \copybrief CFE_TIME_A_GT_B +** \retval #CFE_TIME_A_LT_B \copybrief CFE_TIME_A_LT_B ** ** \sa #CFE_TIME_Add, #CFE_TIME_Subtract ** ******************************************************************************/ -CFE_TIME_Compare_t CFE_TIME_Compare(CFE_TIME_SysTime_t TimeA, CFE_TIME_SysTime_t TimeB); /* (TimeA <=> TimeB) */ +CFE_TIME_Compare_t CFE_TIME_Compare(CFE_TIME_SysTime_t TimeA, CFE_TIME_SysTime_t TimeB); +/**@}*/ -/* -** Function prototypes (convert sub-seconds)... -*/ +/** @defgroup CFEAPITIMEConvert cFE Time Conversion APIs + * @{ + */ + +/*****************************************************************************/ +/** +** \brief Convert specified MET into Spacecraft Time +** +** \par Description +** This function returns Spacecraft Time given MET. Note that Spacecraft +** Time is returned as either UTC or TAI depeneding on whether the mission +** configuration parameter #CFE_MISSION_TIME_CFG_DEFAULT_UTC or #CFE_MISSION_TIME_CFG_DEFAULT_TAI +** was set to true at compile time. +** +** \par Assumptions, External Events, and Notes: +** None +** +** \param[in] METTime The MET to be converted. +** +** \return Spacecraft Time (UTC or TAI) corresponding to the specified MET +** +** \sa #CFE_TIME_GetMET, #CFE_TIME_GetMETseconds, #CFE_TIME_GetMETsubsecs, +** #CFE_TIME_Sub2MicroSecs, #CFE_TIME_Micro2SubSecs, #CFE_TIME_CFE2FSSeconds, #CFE_TIME_FS2CFESeconds +** +******************************************************************************/ +CFE_TIME_SysTime_t CFE_TIME_MET2SCTime (CFE_TIME_SysTime_t METTime); /*****************************************************************************/ /** @@ -592,15 +553,13 @@ CFE_TIME_Compare_t CFE_TIME_Compare(CFE_TIME_SysTime_t TimeA, CFE_TIME_SysTime_ ** ** \param[in] SubSeconds The sub-seconds count to convert. ** -** \returns -** \retstmt The equivalent number of microseconds. \endstmt -** \endreturns +** \return The equivalent number of microseconds. ** ** \sa #CFE_TIME_MET2SCTime, #CFE_TIME_Micro2SubSecs, ** #CFE_TIME_CFE2FSSeconds, #CFE_TIME_FS2CFESeconds ** ******************************************************************************/ -uint32 CFE_TIME_Sub2MicroSecs(uint32 SubSeconds); /* convert sub-seconds (1/2^32) to micro-seconds (1/1000000) */ +uint32 CFE_TIME_Sub2MicroSecs(uint32 SubSeconds); /*****************************************************************************/ /** @@ -615,21 +574,15 @@ uint32 CFE_TIME_Sub2MicroSecs(uint32 SubSeconds); /* convert sub-seconds (1 ** ** \param[in] MicroSeconds The sub-seconds count to convert. ** -** \returns -** \retstmt The equivalent number of subseconds. If the number of microseconds -** passed in is greater than one second, (i.e. > 999,999), the return -** value is equal to \c 0xffffffff. \endstmt -** \endreturns +** \return The equivalent number of subseconds. If the number of microseconds +** passed in is greater than one second, (i.e. > 999,999), the return +** value is equal to \c 0xffffffff. ** ** \sa #CFE_TIME_MET2SCTime, #CFE_TIME_Sub2MicroSecs, ** #CFE_TIME_CFE2FSSeconds, #CFE_TIME_FS2CFESeconds ** ******************************************************************************/ -uint32 CFE_TIME_Micro2SubSecs(uint32 MicroSeconds); /* convert micro-seconds (1/1000000) to sub-seconds (1/2^32) */ - -/* -** Function prototypes (convert cFE and file system time formats)... -*/ +uint32 CFE_TIME_Micro2SubSecs(uint32 MicroSeconds); /*****************************************************************************/ /** @@ -649,9 +602,7 @@ uint32 CFE_TIME_Micro2SubSecs(uint32 MicroSeconds); /* convert micro-seconds ** ** \param[in] SecondsCFE The spacecraft time, in seconds, to be converted. ** -** \returns -** \retstmt The equivalent time, in seconds, for the file system. \endstmt -** \endreturns +** \return The equivalent time, in seconds, for the file system. ** ** \sa #CFE_TIME_MET2SCTime, #CFE_TIME_Sub2MicroSecs, #CFE_TIME_Micro2SubSecs, ** #CFE_TIME_FS2CFESeconds @@ -677,55 +628,18 @@ uint32 CFE_TIME_CFE2FSSeconds(uint32 SecondsCFE); ** ** \param[in] SecondsFS The file system time, in seconds, to be converted. ** -** \returns -** \retstmt The equivalent time, in seconds, for the spacecraft. \endstmt -** \endreturns +** \return The equivalent time, in seconds, for the spacecraft. ** ** \sa #CFE_TIME_MET2SCTime, #CFE_TIME_Sub2MicroSecs, #CFE_TIME_Micro2SubSecs, ** #CFE_TIME_CFE2FSSeconds ** ******************************************************************************/ uint32 CFE_TIME_FS2CFESeconds(uint32 SecondsFS); +/**@}*/ -/* -** Function prototypes (convert time to string)... -*/ - -/*****************************************************************************/ -/** -** \brief Print a time value as a string -** -** \par Description -** This routine prints the specified time to the specified string buffer -** in the following format: -** \c yyyy-ddd-hh:mm:ss.xxxxx\\0 -** where: -** - \c yyyy = year -** - \c ddd = Julian day of the year -** - \c hh = hour of the day (0 to 23) -** - \c mm = minute (0 to 59) -** - \c ss = second (0 to 59) -** - \c xxxxx = subsecond formatted as a decimal fraction (1/4 second = 0.25000) -** - \c \\0 = trailing null -** -** \par Assumptions, External Events, and Notes: -** None -** -** \param[in] PrintBuffer Pointer to a character array of at least -** #CFE_TIME_PRINTED_STRING_SIZE characters in length -** -** \param[in] TimeToPrint The time to print into the character array. -** -** \param[out] *PrintBuffer The time as a character string as described above. -** -** \sa -** -******************************************************************************/ -void CFE_TIME_Print(char *PrintBuffer, CFE_TIME_SysTime_t TimeToPrint); - -/* -** Function prototypes (1hz tone signal processor)... -*/ +/** @defgroup CFEAPITIMEExternSource cFE External Time Source APIs + * @{ + */ /*****************************************************************************/ /** @@ -746,7 +660,7 @@ void CFE_TIME_Print(char *PrintBuffer, CFE_TIME_SysTime_t TimeToPrint); ** \sa #CFE_TIME_ExternalMET, #CFE_TIME_ExternalGPS, #CFE_TIME_ExternalTime ** ******************************************************************************/ -void CFE_TIME_ExternalTone(void); /* OK to call from ISR */ +void CFE_TIME_ExternalTone(void); /* ** Function prototypes (external time source)... @@ -839,8 +753,6 @@ void CFE_TIME_ExternalMET(CFE_TIME_SysTime_t NewMET); ******************************************************************************/ void CFE_TIME_ExternalGPS(CFE_TIME_SysTime_t NewTime, int16 NewLeaps); - - /*****************************************************************************/ /** ** \brief Provide the time from an external source that measures time relative to a known epoch. @@ -892,11 +804,10 @@ void CFE_TIME_ExternalTime(CFE_TIME_SysTime_t NewTime); ** If an application requires triggering multiple child tasks at 1Hz, it should distribute ** the timing signal internally, rather than registering for multiple callbacks. ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TIME_TOO_MANY_SYNCH_CALLBACKS \retdesc \copydoc CFE_TIME_TOO_MANY_SYNCH_CALLBACKS \endcode -** \retcode #CFE_ES_ERR_APPID \retdesc \copydoc CFE_ES_ERR_APPID \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TIME_TOO_MANY_SYNCH_CALLBACKS \copybrief CFE_TIME_TOO_MANY_SYNCH_CALLBACKS +** \retval #CFE_ES_ERR_APPID \copybrief CFE_ES_ERR_APPID ** ** \sa #CFE_TIME_UnregisterSynchCallback ** @@ -917,17 +828,57 @@ int32 CFE_TIME_RegisterSynchCallback(CFE_TIME_SynchCallbackPtr_t CallbackFuncPt ** Only a single callback per application is supported, and this function should only ** be called from a single thread within each application (typically the apps main thread). ** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESS \endcode -** \retcode #CFE_TIME_CALLBACK_NOT_REGISTERED \retdesc \copydoc CFE_TIME_CALLBACK_NOT_REGISTERED \endcode -** \retcode #CFE_ES_ERR_APPID \retdesc \copydoc CFE_ES_ERR_APPID \endcode -** \endreturns +** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TIME_CALLBACK_NOT_REGISTERED \copybrief CFE_TIME_CALLBACK_NOT_REGISTERED +** \retval #CFE_ES_ERR_APPID \copybrief CFE_ES_ERR_APPID ** ** \sa #CFE_TIME_RegisterSynchCallback ** ******************************************************************************/ int32 CFE_TIME_UnregisterSynchCallback(CFE_TIME_SynchCallbackPtr_t CallbackFuncPtr); +/**@}*/ +/** @defgroup CFEAPITIMEMisc cFE Miscellaneous Time APIs + * @{ + */ + +/*****************************************************************************/ +/** +** \brief Print a time value as a string +** +** \par Description +** This routine prints the specified time to the specified string buffer +** in the following format: +** \c yyyy-ddd-hh:mm:ss.xxxxx\\0 +** where: +** - \c yyyy = year +** - \c ddd = Julian day of the year +** - \c hh = hour of the day (0 to 23) +** - \c mm = minute (0 to 59) +** - \c ss = second (0 to 59) +** - \c xxxxx = subsecond formatted as a decimal fraction (1/4 second = 0.25000) +** - \c \\0 = trailing null +** +** \par Assumptions, External Events, and Notes: +** - The value of the time argument is simply added to the configuration +** definitions for the ground epoch and converted into a fixed length +** string in the buffer provided by the caller. +** - A loss of data during the string conversion will occur if the +** computed year exceeds 9999. However, a year that large would +** require an unrealistic definition for the ground epoch since +** the maximum amount of time represented by a CFE_TIME_SysTime +** structure is approximately 136 years. +** +** \param[in] PrintBuffer Pointer to a character array of at least +** #CFE_TIME_PRINTED_STRING_SIZE characters in length +** +** \param[in] TimeToPrint The time to print into the character array. +** +** \param[out] *PrintBuffer The time as a character string as described above. +** +******************************************************************************/ +void CFE_TIME_Print(char *PrintBuffer, CFE_TIME_SysTime_t TimeToPrint); /*****************************************************************************/ /** @@ -944,7 +895,7 @@ int32 CFE_TIME_UnregisterSynchCallback(CFE_TIME_SynchCallbackPtr_t CallbackFunc ** ******************************************************************************/ void CFE_TIME_Local1HzISR(void); - +/**@}*/ #endif /* _cfe_time_ */ diff --git a/fsw/cfe-core/src/inc/cfe_time_msg.h b/fsw/cfe-core/src/inc/cfe_time_msg.h index 4326ccf62..a7324dc9b 100644 --- a/fsw/cfe-core/src/inc/cfe_time_msg.h +++ b/fsw/cfe-core/src/inc/cfe_time_msg.h @@ -703,11 +703,9 @@ #define CFE_TIME_SET_SIGNAL_CC 15 /* set clock signal (pri vs red) */ /** \} */ -/* -** Clock "state flag" definitions (state data converted to flags)... -*/ -/** \name Clock "state flag" values */ -/** \{ */ +/** \defgroup CFETIMEClkStates cFE Clock State Flag Defines + * \{ + */ #define CFE_TIME_FLAG_CLKSET 0x8000 /**< \brief The spacecraft time has been set */ #define CFE_TIME_FLAG_FLYING 0x4000 /**< \brief This instance of Time Services is flywheeling */ #define CFE_TIME_FLAG_SRCINT 0x2000 /**< \brief The clock source is set to "internal" */ diff --git a/fsw/cfe-core/src/inc/cfe_version.h b/fsw/cfe-core/src/inc/cfe_version.h index 7290d990f..b5c84c5f7 100644 --- a/fsw/cfe-core/src/inc/cfe_version.h +++ b/fsw/cfe-core/src/inc/cfe_version.h @@ -23,41 +23,62 @@ ** ** Purpose: ** Provide version identifiers for the cFE core. -** -** Version Number Semantics: -** -** The version number is a sequence of four numbers, generally separated by dots when written. These are, in order, -** the Major number, the Minor number, the Implementation Revision number, and the Mission Revision number. At -** their option, Missions may modify the Mission Revision information as needed to suit their needs. -** -** The Major number shall be incremented on release to indicate when there is a change to an API -** that may cause existing correctly-written cFS components to stop working. It may also be incremented for a -** release that contains changes deemed to be of similar impact, even if there are no actual changes to the API. -** -** The Minor number shall be incremented on release to indicate the addition of features to the API, -** which do not break the existing code. It may also be incremented for a release that contains changes deemed -** to be of similar impact, even if there are no actual updates to the API. -** -** The Implementation Revision Version number shall be incremented on changes to software in the master branch, -** or other changes that benefit from unique identification. It is used for identifying open source development -** versions. -** -** The Major, Minor, and Implementation Revision numbers are provided in this header file as part of the API -** definition; this macro must expand to a simple integer value, so that it can be used in simple #if directives -** by the macro preprocessor. -** -** The Mission Version number shall be set to zero in all officially released packages, and is entirely reserved -** for the use of the mission. The Mission Version is provided as a simple macro defined in the cfe_platform_cfg.h -** header file. -** -** References: -** Flight Software Branch C Coding Standard Version 1.0a -** cFE Flight Software Application Developers Guide -** -** Notes: -** */ +/** + * \page cfeversion Version Numbers + * + * Version Number Semantics+ * + * The version number is a sequence of four numbers, generally separated by dots when written. These are, in order, + * the Major number, the Minor number, the Implementation Revision number, and the Mission Revision number. At + * their option, Missions may modify the Mission Revision information as needed to suit their needs. + * + * The Major number shall be incremented on release to indicate when there is a change to an API + * that may cause existing correctly-written cFS components to stop working. It may also be incremented for a + * release that contains changes deemed to be of similar impact, even if there are no actual changes to the API. + * + * The Minor number shall be incremented on release to indicate the addition of features to the API, + * which do not break the existing code. It may also be incremented for a release that contains changes deemed + * to be of similar impact, even if there are no actual updates to the API. + * + * The Implementation Revision Version number shall be incremented on changes to software in the master branch, + * or other changes that benefit from unique identification. It is used for identifying open source development + * versions. It is important to note that Major and Minor numbers are only updated upon official releases + * of tagged versions (see the release tab), \b NOT on development version updates in the master branch. + * + * The Major, Minor, and Implementation Revision numbers are provided in this header file as part of the API + * definition; this macro must expand to a simple integer value, so that it can be used in simple if directives + * by the macro preprocessor. + * + * The Mission Version number shall be set to zero in all officially released packages, and is entirely reserved + * for the use of the mission. The Mission Version is provided as a simple macro defined in the cfe_platform_cfg.h + * header file. + * + *Version Number Flexibility+ * + * The major number may increment when there is no breaking change to the API, if the changes are significant enough to + * warrant the same level of attention as a breaking API change. + * + * The minor number may increment when there have been no augmentations to the API, if changes are as significant as + * additions to the public API. + * + * The revision numbers may update in implementations where no actual implementation-specific code has changed, if + * there are other changes within the release with similar significance. + * + *How and Where Defined+ * + * The Major, Minor, and Revision components of the version are provided as simple macros defined in the cfe_version.h + * header file as part of the API definition; these macros must expand to simple integer values, so that they can be used + * in simple if directives by the macro preprocessor. + * + * The Mission Version is provided as a simple macro defined in the cfe_platform_cfg.h header file. As delivered in + * official releases, these macros must expand to simple integer values, so that they can be used in simple macro + * preprocessor conditions, but delivered code should not prevent a mission from, for example, deciding that the Mission + * Version is actually a text string. + * + */ + #ifndef _cfe_version_ #define _cfe_version_ diff --git a/fsw/cfe-core/src/sb/cfe_sb_api.c b/fsw/cfe-core/src/sb/cfe_sb_api.c index 725a7c3f9..5495c1784 100644 --- a/fsw/cfe-core/src/sb/cfe_sb_api.c +++ b/fsw/cfe-core/src/sb/cfe_sb_api.c @@ -74,33 +74,10 @@ * this may or may not be the same as CFE_SB_MSG_MAX_PIPES */ #define CFE_SB_TLM_PIPEDEPTHSTATS_SIZE (sizeof(CFE_SB.StatTlmMsg.Payload.PipeDepthStats) / sizeof(CFE_SB.StatTlmMsg.Payload.PipeDepthStats[0])) -/****************************************************************************** -** Name: CFE_SB_CreatePipe -** -** Purpose: API to create a pipe for receiving messages -** -** Assumptions, External Events, and Notes: -** -** Note: Zero is a valid PipeId -** -** Date Written: -** 04/25/2005 -** -** Inputs: -** PipeIdPtr - Ptr to users empty PipeId variable, to be filled by -** this function. -** Depth - The depth of the pipe, synonymous to the max number -** of messages the pipe can hold at any time. -** PipeName - The name of the pipe displayed in event messages -** -** Outputs: -** PipeId - The handle of the pipe to be used when receiving -** messages. -** -** Return Values: -** Status -** -******************************************************************************/ + +/* + * Function: CFE_SB_CreatePipe - See API and header file for details + */ int32 CFE_SB_CreatePipe(CFE_SB_PipeId_t *PipeIdPtr, uint16 Depth, const char *PipeName) { uint32 AppId = 0xFFFFFFFF; @@ -227,19 +204,9 @@ int32 CFE_SB_CreatePipe(CFE_SB_PipeId_t *PipeIdPtr, uint16 Depth, const char * }/* end CFE_SB_CreatePipe */ -/****************************************************************************** -** Function: CFE_SB_DeletePipe() -** -** Purpose: -** Will unsubscribe to all routes associated with the given pipe id, then remove -** pipe from the pipe table. -** -** Arguments: -** PipeId - The ID of the pipe to delete. -** -** Return: -** CFE_SUCCESS or cFE Error Code -*/ +/* + * Function: CFE_SB_DeletePipe - See API and header file for details + */ int32 CFE_SB_DeletePipe(CFE_SB_PipeId_t PipeId) { uint32 CallerId = 0xFFFFFFFF; @@ -416,20 +383,9 @@ int32 CFE_SB_DeletePipeFull(CFE_SB_PipeId_t PipeId,uint32 AppId) }/* end CFE_SB_DeletePipeFull */ -/****************************************************************************** -** Function: CFE_SB_SetPipeOpts() -** -** Purpose: -** Sets pipe options. Options are a bit field, setting each bit enables the -** option specified. -** -** Arguments: -** PipeId - The ID of the pipe for the options. -** Opts - The options to set on this pipe. -** -** Return: -** CFE_SUCCESS or cFE Error Code -*/ +/* + * Function: CFE_SB_SetPipeOpts - See API and header file for details + */ int32 CFE_SB_SetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 Opts) { uint8 PipeTblIdx = 0; @@ -493,19 +449,9 @@ int32 CFE_SB_SetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 Opts) return CFE_SUCCESS; }/* end CFE_SB_SetPipeOpts */ -/****************************************************************************** -** Function: CFE_SB_GetPipeOpts() -** -** Purpose: -** Gets the current pipe options. -** -** Arguments: -** PipeId - The ID of the pipe for the options. -** OptsPtr - Pointer to receive the opts. -** -** Return: -** CFE_SUCCESS or cFE Error Code -*/ +/* + * Function: CFE_SB_GetPipeOpts - See API and header file for details + */ int32 CFE_SB_GetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 *OptsPtr) { uint8 PipeTblIdx = 0; @@ -550,23 +496,9 @@ int32 CFE_SB_GetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 *OptsPtr) return CFE_SUCCESS; }/* end CFE_SB_GetPipeOpts */ -/****************************************************************************** -** Function: CFE_SB_GetPipeName() -** -** Purpose: -** SB internal function to get the string of the pipe name of the given -** Pipe ID. -** -** Arguments: -** MsgId : ID of the message -** PipeNameBuf : Buffer to receive name, must be OS_MAX_API_NAME bytes long -** -** Return: -** Will return CFE_SUCCESS and populate PipeNameBuf with the name -** of the pipe on success, otherwise PipeNameBuf is filled with NULLs -** and this returns CFE_SB_BAD_ARGUMENT on error. -** -*/ +/* + * Function: CFE_SB_GetPipeName - See API and header file for details + */ int32 CFE_SB_GetPipeName(char *PipeNameBuf, size_t PipeNameSize, CFE_SB_PipeId_t PipeId){ OS_queue_prop_t queue_prop; int32 Status = CFE_SUCCESS; @@ -612,19 +544,9 @@ int32 CFE_SB_GetPipeName(char *PipeNameBuf, size_t PipeNameSize, CFE_SB_PipeId_t return Status; }/* end CFE_SB_GetPipeName */ -/****************************************************************************** -** Function: CFE_SB_GetPipeIdByName() -** -** Purpose: -** Gets the pipe id given its name. -** -** Arguments: -** PipeIdPtr - The ID of the pipe for the name. -** PipeName - The name of the pipe. -** -** Return: -** CFE_SUCCESS or cFE Error Code -*/ +/* + * Function: CFE_SB_GetPipeIdByName - See API and header file for details + */ int32 CFE_SB_GetPipeIdByName(CFE_SB_PipeId_t *PipeIdPtr, const char *PipeName) { uint8 PipeTblIdx = 0; @@ -716,37 +638,9 @@ int32 CFE_SB_GetPipeIdByName(CFE_SB_PipeId_t *PipeIdPtr, const char *PipeName) }/* end CFE_SB_GetPipeIdByName */ -/****************************************************************************** -** Name: CFE_SB_SubscribeEx -** -** Purpose: API to globally subscribe to a message when QOS and MsgLim defaults -** are insufficient. -** -** Assumptions, External Events, and Notes: -** -** Note: Qos default: priority is low, reliability is low -** Note: MsgLim default: 4, see Input Arguments below for more detail -** Note: Qos parameter is currently unused by the fsw. It is recommended -** to give a value of zero for Quality.Priority and Quality.Reliability -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgId - The requesting message -** PipeId - The Pipe ID to send the message to -** Quality - Quality of Service (Qos) - priority and reliability, -** see note above for recommended settings -** MsgLim - Max number of messages, with this MsgId, allowed on the -** pipe at any time. -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_SubscribeEx - See API and header file for details + */ int32 CFE_SB_SubscribeEx(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId, CFE_SB_Qos_t Quality, @@ -759,34 +653,9 @@ int32 CFE_SB_SubscribeEx(CFE_SB_MsgId_t MsgId, -/****************************************************************************** -** Name: CFE_SB_SubscribeLocal -** -** Purpose: CFE Internal API to locally subscribe to a message when QOS and -** MsgLim defaults are insufficient. -** -** Assumptions, External Events, and Notes: -** -** Note: Qos default: priority is low, reliability is low -** MsgLim default: 4 - meaning at most 4 messages of given -** MsgId allowed on the given PipeId. -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgId - The requesting message -** PipeId - The Pipe ID to send the message to -** MsgLim - Max number of messages, with this MsgId, allowed on the -** pipe at any time. -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_SubscribeLocal - See API and header file for details + */ int32 CFE_SB_SubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId, uint16 MsgLim) @@ -796,35 +665,9 @@ int32 CFE_SB_SubscribeLocal(CFE_SB_MsgId_t MsgId, }/* end CFE_SB_SubscribeLocal */ - - - -/****************************************************************************** -** Name: CFE_SB_Subscribe -** -** Purpose: API to locally subscribe to a message when QOS and MsgLim defaults -** are sufficient. -** -** Assumptions, External Events, and Notes: -** -** Note: Qos default: priority is low, reliability is low -** MsgLim default: 4 - meaning at most 4 messages of given -** MsgId allowed on the given PipeId. -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgId - The requesting message -** PipeId - The Pipe ID to send the message to -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_Subscribe - See API and header file for details + */ int32 CFE_SB_Subscribe(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId) { @@ -1053,25 +896,9 @@ int32 CFE_SB_SubscribeFull(CFE_SB_MsgId_t MsgId, }/* end CFE_SB_SubscribeFull */ -/****************************************************************************** -** Name: CFE_SB_Unsubscribe -** -** Purpose: API used to unsubscribe to a message. -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgId -** PipeId -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_Unsubscribe - See API and header file for details + */ int32 CFE_SB_Unsubscribe(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId) { uint32 CallerId = 0xFFFFFFFF; @@ -1087,26 +914,9 @@ int32 CFE_SB_Unsubscribe(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId) }/* end CFE_SB_Unsubscribe */ -/****************************************************************************** -** Name: CFE_SB_UnsubscribeLocal -** -** Purpose: CFE Internal API used to locally unsubscribe to a message. This -** request to cancel a subscription will not be sent to peers. -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgId -** PipeId -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_UnsubscribeLocal - See API and header file for details + */ int32 CFE_SB_UnsubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId) { uint32 CallerId = 0xFFFFFFFF; @@ -1290,31 +1100,9 @@ int32 CFE_SB_UnsubscribeFull(CFE_SB_MsgId_t MsgId,CFE_SB_PipeId_t PipeId, }/* end CFE_SB_UnsubscribeFull */ - - -/****************************************************************************** -** Name: CFE_SB_SendMsg -** -** Purpose: API used to send a message on the software bus. -** -** Assumptions, External Events, and Notes: -** -** Note: This function increments and tracks the source sequence -** counter for all telemetry messages. -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgPtr -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_SendMsg - See API and header file for details + */ int32 CFE_SB_SendMsg(CFE_SB_Msg_t *MsgPtr) { int32 Status = 0; @@ -1327,29 +1115,9 @@ int32 CFE_SB_SendMsg(CFE_SB_Msg_t *MsgPtr) -/****************************************************************************** -** Name: CFE_SB_PassMsg -** -** Purpose: API used to send a message on the software bus. -** -** Assumptions, External Events, and Notes: -** -** Note: This function does NOT increment and track the source -** sequence counter for telemetry messages. -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgPtr -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_PassMsg - See API and header file for details + */ int32 CFE_SB_PassMsg(CFE_SB_Msg_t *MsgPtr) { int32 Status = 0; @@ -1712,30 +1480,9 @@ int32 CFE_SB_SendMsgFull(CFE_SB_Msg_t *MsgPtr, -/****************************************************************************** -** Name: CFE_SB_RcvMsg -** -** Purpose: API used to receive a message from the software bus. -** -** Assumptions, External Events, and Notes: -** Notes: -** -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** PipeId -** BufPtr -** timeOut - CFE_SB_PEND, CFE_SB_POLL or millisecond timeout -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_RcvMsg - See API and header file for details + */ int32 CFE_SB_RcvMsg(CFE_SB_MsgPtr_t *BufPtr, CFE_SB_PipeId_t PipeId, int32 TimeOut) @@ -1856,30 +1603,9 @@ int32 CFE_SB_RcvMsg(CFE_SB_MsgPtr_t *BufPtr, }/* end CFE_SB_RcvMsg */ -/****************************************************************************** -** Name: CFE_SB_GetLastSenderId -** -** Purpose: API used for receiving sender Information of the last message received on -** the given pipe. -** -** Assumptions, External Events, and Notes: -** None -** -** Date Written: -** 06/13/2007 -** -** Input Arguments: -** Ptr - caller declares a ptr of type CFE_SB_SenderId_t then gives the -** address of that pointer. -** PipeId - the Pipe Id that the message was received on. -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_GetLastSenderId - See API and header file for details + */ uint32 CFE_SB_GetLastSenderId(CFE_SB_SenderId_t **Ptr,CFE_SB_PipeId_t PipeId) { @@ -1935,30 +1661,9 @@ uint32 CFE_SB_GetLastSenderId(CFE_SB_SenderId_t **Ptr,CFE_SB_PipeId_t PipeId) }/* end CFE_SB_GetLastSenderId */ -/****************************************************************************** -** Name: CFE_SB_ZeroCopyGetPtr -** -** Purpose: API used for for getting a pointer to a buffer (for zero copy mode -** only) -** -** Assumptions, External Events, and Notes: -** None -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgSize -** -** Output Arguments: -** BufferHandle -** -** Return Values: -** Pointer to an empty buffer in SB Memory space, or NULL if the buffer -** could not be allocated. -** -******************************************************************************/ - +/* + * Function: CFE_SB_ZeroCopyGetPtr - See API and header file for details + */ CFE_SB_Msg_t *CFE_SB_ZeroCopyGetPtr(uint16 MsgSize, CFE_SB_ZeroCopyHandle_t *BufferHandle) { @@ -2046,31 +1751,9 @@ CFE_SB_Msg_t *CFE_SB_ZeroCopyGetPtr(uint16 MsgSize, }/* CFE_SB_ZeroCopyGetPtr */ -/****************************************************************************** -** Name: CFE_SB_ZeroCopyReleasePtr -** -** Purpose: API used for releasing a pointer to a buffer (for zero copy mode -** only) This function is typically not needed for zero copy transfers. -** This function is needed only when a ptr is received via -** CFE_SB_ZeroCopyGetPtr, but never used in a send. -** -** Assumptions, External Events, and Notes: -** None -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** Ptr2Release -** BufferHandle -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_ZeroCopyReleasePtr - See API and header file for details + */ int32 CFE_SB_ZeroCopyReleasePtr(CFE_SB_Msg_t *Ptr2Release, CFE_SB_ZeroCopyHandle_t BufferHandle) { @@ -2163,29 +1846,9 @@ int32 CFE_SB_ZeroCopyReleaseDesc(CFE_SB_Msg_t *Ptr2Release, }/* end CFE_SB_ZeroCopyReleaseDesc */ -/****************************************************************************** -** Name: CFE_SB_ZeroCopySend -** -** Purpose: API for sending messages in zero copy mode (with telemetry source -** sequence count incrementing) -** -** Assumptions, External Events, and Notes: -** None -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgPtr - Pointer to message to be sent -** BufferHandle - Handle supplied by the get pointer call -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_ZeroCopySend - See API and header file for details + */ int32 CFE_SB_ZeroCopySend(CFE_SB_Msg_t *MsgPtr, CFE_SB_ZeroCopyHandle_t BufferHandle) { @@ -2202,29 +1865,9 @@ int32 CFE_SB_ZeroCopySend(CFE_SB_Msg_t *MsgPtr, }/* end CFE_SB_ZeroCopySend */ -/****************************************************************************** -** Name: CFE_SB_ZeroCopyPass -** -** Purpose: API for sending messages in zero copy mode (telemetry source -** sequence count is preserved) -** -** Assumptions, External Events, and Notes: -** None -** -** Date Written: -** 04/25/2005 -** -** Input Arguments: -** MsgPtr - Pointer to message to be sent -** BufferHandle - Handle supplied by the get pointer call -** -** Output Arguments: -** None -** -** Return Values: -** Status -** -******************************************************************************/ +/* + * Function: CFE_SB_ZeroCopyPass - See API and header file for details + */ int32 CFE_SB_ZeroCopyPass(CFE_SB_Msg_t *MsgPtr, CFE_SB_ZeroCopyHandle_t BufferHandle) { diff --git a/fsw/cfe-core/src/sb/cfe_sb_msg_id_util.c b/fsw/cfe-core/src/sb/cfe_sb_msg_id_util.c index 86f17b853..6b2132565 100644 --- a/fsw/cfe-core/src/sb/cfe_sb_msg_id_util.c +++ b/fsw/cfe-core/src/sb/cfe_sb_msg_id_util.c @@ -113,22 +113,9 @@ CFE_SB_MsgKey_t CFE_SB_ConvertMsgIdtoMsgKey( CFE_SB_MsgId_t MsgId) return CFE_SB_ValueToMsgKey(MsgId); }/* CFE_SB_ConvertMsgIdtoMsgKey */ -/****************************************************************************** -** Function: CFE_SB_GetMsgId -** -** Purpose: -** Convert the CCSDS SPP APID in the packet to the internal MsgId ID format -** used for SB APIs and routing. -** -** For backward compatability with the existing CCSDS SPP version 1 code base -** the function name has not been changed -** -** Arguments: -** MsgPtr - Pointer to a CCSDS SPP message packet -** -** Return: -** The Message Id in the message packet converted to the cFS MsgId -*/ +/* + * Function: CFE_SB_GetMsgId - See API and header file for details + */ CFE_SB_MsgId_t CFE_SB_GetMsgId(const CFE_SB_Msg_t *MsgPtr) { CFE_SB_MsgId_t MsgId = 0; @@ -166,20 +153,9 @@ return MsgId; }/* end CFE_SB_GetMsgId */ -/****************************************************************************** -** Function: CFE_SB_SetMsgId -** -** Purpose: -** Set the message Id of a message in CCSDS header format -** -** Arguments: -** MsgPtr - Pointer to a CFE_SB_Msg_t -** MsgId - Message Id to be written -** -** -** Return: -** (none) -*/ +/* + * Function: CFE_SB_SetMsgId - See API and header file for details + */ void CFE_SB_SetMsgId(CFE_SB_MsgPtr_t MsgPtr, CFE_SB_MsgId_t MsgId) { diff --git a/fsw/cfe-core/src/sb/cfe_sb_util.c b/fsw/cfe-core/src/sb/cfe_sb_util.c index 673fc8c91..daf01bea7 100644 --- a/fsw/cfe-core/src/sb/cfe_sb_util.c +++ b/fsw/cfe-core/src/sb/cfe_sb_util.c @@ -41,22 +41,9 @@ #include |