From 137dcea508686e56d650fdd2db12a519cef92afb Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Fri, 23 Jul 2021 10:02:39 -0400 Subject: [PATCH] Fix #1703, update docs for CFE_FS_BackgroundFileDumpRequest Update notes to better clarify that the meta object must persist for the duration of the dump operation, which occurs in another task, so it must not be on the stack. Also update documentation for background even callbacks to better clarify arguments and expectations of the implementation. --- modules/core_api/fsw/inc/cfe_fs.h | 4 ++-- .../core_api/fsw/inc/cfe_fs_api_typedefs.h | 20 +++++++++++++++++++ 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/modules/core_api/fsw/inc/cfe_fs.h b/modules/core_api/fsw/inc/cfe_fs.h index 1fd3d1bd1..bbd85d088 100644 --- a/modules/core_api/fsw/inc/cfe_fs.h +++ b/modules/core_api/fsw/inc/cfe_fs.h @@ -291,8 +291,8 @@ CFE_Status_t CFE_FS_ExtractFilenameFromPath(const char *OriginalPath, char *File ** Puts the previously-initialized metadata into the pending request queue ** ** \par Assumptions, External Events, and Notes: -** Metadata structure should be stored in a static memory area (not on heap) as it -** must persist and be accessible by the file writer task throughout the asynchronous +** Metadata structure should be stored in a persistent memory area (not on stack) as +** it must remain accessible by the file writer task throughout the asynchronous ** job operation. ** ** \param[inout] Meta The background file write persistent state object diff --git a/modules/core_api/fsw/inc/cfe_fs_api_typedefs.h b/modules/core_api/fsw/inc/cfe_fs_api_typedefs.h index 0e7a80594..3d9d1e110 100644 --- a/modules/core_api/fsw/inc/cfe_fs_api_typedefs.h +++ b/modules/core_api/fsw/inc/cfe_fs_api_typedefs.h @@ -84,6 +84,18 @@ typedef enum * Data Getter routine provided by requester * * Outputs a data block. Should return true if the file is complete (last record/EOF), otherwise return false. + * + * \param[inout] Meta Pointer to the metadata object + * \param[in] RecordNum Incrementing record number counter + * \param[out] Buffer Pointer to buffer data block, should be set by implementation + * \param[out] BufSize Pointer to buffer data size, should be set by implementation + * + * \returns End of file status + * \retval true if at last data record, and output file should be closed + * \retval false if not at last record, more data records to write + * + * \note The implementation of this function must always set the "Buffer" and "BufSize" outputs. If + * no data is avaliable, they may be set to NULL and 0, respectively. */ typedef bool (*CFE_FS_FileWriteGetData_t)(void *Meta, uint32 RecordNum, void **Buffer, size_t *BufSize); @@ -92,6 +104,14 @@ typedef bool (*CFE_FS_FileWriteGetData_t)(void *Meta, uint32 RecordNum, void **B * * Invoked from certain points in the file write process. Implementation may invoke CFE_EVS_SendEvent() appropriately * to inform of progress. + * + * \param[inout] Meta Pointer to the metadata object + * \param[in] Event Generalized type of event to report (not actual event ID) + * \param[in] Status Generalized status code (may be from OSAL or CFE) + * \param[in] RecordNum Record number counter at which event occurred + * \param[in] BlockSize Size of record being processed when event occured (if applicable) + * \param[in] Position File position/size when event occurred + * */ typedef void (*CFE_FS_FileWriteOnEvent_t)(void *Meta, CFE_FS_FileWriteEvent_t Event, int32 Status, uint32 RecordNum, size_t BlockSize, size_t Position);