diff --git a/fsw/mission_inc/cf_perfids.h b/fsw/mission_inc/cf_perfids.h index 0d4014bdc..7b4b1a7ee 100644 --- a/fsw/mission_inc/cf_perfids.h +++ b/fsw/mission_inc/cf_perfids.h @@ -1,32 +1,31 @@ /************************************************************************ -** File: cf_perfids.h -** -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** Define CF Performance IDs -** -** -** -** -*************************************************************************/ -#ifndef _CF_PERFIDS_H_ -#define _CF_PERFIDS_H_ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ + +/** + * @file + * + * Define CF Performance IDs + */ + +#ifndef CF_PERFIDS_H +#define CF_PERFIDS_H #define CF_PERF_ID_APPMAIN 11 #define CF_PERF_ID_FSEEK 12 @@ -41,7 +40,7 @@ #define CF_PERF_ID_PDURCVD(x) (30 + x) #define CF_PERF_ID_PDUSENT(x) (40 + x) -#endif /* !_CF_PERFIDS_H_ */ +#endif /* !CF_PERFIDS_H */ /************************/ /* End of File Comment */ diff --git a/fsw/platform_inc/cf_msgids.h b/fsw/platform_inc/cf_msgids.h index a95f3aa79..74b1ed12f 100644 --- a/fsw/platform_inc/cf_msgids.h +++ b/fsw/platform_inc/cf_msgids.h @@ -1,44 +1,45 @@ /************************************************************************ -** File: cf_msgids.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application Message IDs header file -** -** -** -*************************************************************************/ -#ifndef _CF_MSGIDS_H_ -#define _CF_MSGIDS_H_ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ + +/** + * @file + * + * The CF Application Message IDs header file + */ + +#ifndef CF_MSGIDS_H +#define CF_MSGIDS_H /************************** -** CF Command Message IDs -***************************/ + * CF Command Message IDs + **************************/ #define CF_CMD_MID 0x18B3 #define CF_SEND_HK_MID 0x18B4 #define CF_WAKE_UP_MID 0x18B5 /*************************** -** CF Telemetry Message IDs -****************************/ + * CF Telemetry Message IDs + ***************************/ #define CF_HK_TLM_MID 0x08B0 #define CF_CONFIG_TLM_MID 0x08B2 -#endif /* !_CF_MSGIDS_H_ */ +#endif /* !CF_MSGIDS_H */ diff --git a/fsw/platform_inc/cf_platform_cfg.h b/fsw/platform_inc/cf_platform_cfg.h index 72d6a1982..76b6b55f6 100644 --- a/fsw/platform_inc/cf_platform_cfg.h +++ b/fsw/platform_inc/cf_platform_cfg.h @@ -1,99 +1,114 @@ /************************************************************************ -** File: cf_platform_cfg.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** CF application platform configuration. -** -** These options are used to configure application behavior. -** -** -** -*************************************************************************/ -#ifndef _CF_PLATFORM_CFG_H_ -#define _CF_PLATFORM_CFG_H_ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * CF application platform configuration. + * These options are used to configure application behavior. + */ + +#ifndef CF_PLATFORM_CFG_H +#define CF_PLATFORM_CFG_H /************************************************************************* -** Macro definitions -**************************************************************************/ + * Macro definitions + *************************************************************************/ /** - ** \cfcfg Entity id size - ** - ** \par Description: - ** The max size of the entity id as expected for all CFDP packets. - ** CF supports the spec's variable size of EID, which can be smaller - ** than the size specified here. - ** - ** \par Limits - ** Must be one of uint8, uint16, uint32, uint64. + * @cfcfg Entity id size + * + * @par Description: + * The maximum size of the entity id as expected for all CFDP packets. + * CF supports the spec's variable size of EID, where the actual size is + * selected at runtime, and therefore the size in CFDP PDUs may be smaller + * than the size specified here. This type only establishes the maximum + * size (and therefore maximum value) that an EID may be. + * + * @note This type is used in several CF commands, and so changing the size + * of this type will affect the following structs: + * CF_ConfigTable_t, configuration table - will change size of file + * CF_ConfigPacket_t, set config params command + * CF_TxFileCmd_t, transmit file command + * CF_PlaybackDirCmd_t, equivalent to above + * CF_TransactionCmd_t, any command that selects a transaction based on EID + * + * @par Limits + * Must be one of uint8, uint16, uint32, uint64. */ typedef uint32 CF_EntityId_t; /** - ** \cfcfg transaction sequence number size - ** - ** \par Description: - ** The max size of the transaction sequence number as expected for all CFDP packets. - ** CF supports the spec's variable size of TSN, which can be smaller - ** than the size specified here. - ** - ** \par Limits - ** Must be one of uint8, uint16, uint32, uint64. + * @cfcfg transaction sequence number size + * + * @par Description: + * The max size of the transaction sequence number as expected for all CFDP packets. + * CF supports the spec's variable size of TSN, where the actual size is + * selected at runtime, and therefore the size in CFDP PDUs may be smaller + * than the size specified here. This type only establishes the maximum + * size (and therefore maximum value) that a TSN may be. + * + * @note This type is used in several CF commands, and so changing the size + * of this type will affect the following structure: + * CF_TransactionCmd_t, any command that selects a transaction based on TSN + * + * @par Limits + * Must be one of uint8, uint16, uint32, uint64. */ typedef uint32 CF_TransactionSeq_t; /** -** \cfcfg Application Pipe Depth -** -** \par Description: -** Dictates the pipe depth of the cf command pipe. -** -** \par Limits: -** The minimum size of this paramater is 1 -** The maximum size dictated by cFE platform configuration -** parameter is CFE_SB_MAX_PIPE_DEPTH -*/ + * @cfcfg Application Pipe Depth + * + * @par Description: + * Dictates the pipe depth of the cf command pipe. + * + * @par Limits: + * The minimum size of this paramater is 1 + * The maximum size dictated by cFE platform configuration + * parameter is CFE_SB_MAX_PIPE_DEPTH + */ #define CF_PIPE_DEPTH 32 /** -** \cfcfg Number of channels -** -** \par Description: -** The number of chanenls in the engine. Changing this -** value changes the configuration table for the application. -** -** \par Limits: -** Must be less <= 200. Obviously it will be smaller than that. -*/ + * @cfcfg Number of channels + * + * @par Description: + * The number of chanenls in the engine. Changing this + * value changes the configuration table for the application. + * + * @par Limits: + * Must be less <= 200. Obviously it will be smaller than that. + */ #define CF_NUM_CHANNELS 2 /** -** \cfcfg Max NAK segments supported in a NAK pdu -** -** \par Description: -** When a NAK pdu is sent or received, this is the max number of -** segment requests supported. This number should match the ground -** cfdp engine configuration as well. -** -** \par Limits: -** -*/ + * @cfcfg Max NAK segments supported in a NAK pdu + * + * @par Description: + * When a NAK pdu is sent or received, this is the max number of + * segment requests supported. This number should match the ground + * cfdp engine configuration as well. + * + * @par Limits: + * + */ #define CF_NAK_MAX_SEGMENTS 58 /* max number of NAK segments CF supports (leave room for overhead */ /* CHUNKS - @@ -106,194 +121,194 @@ typedef uint32 CF_TransactionSeq_t; * CF_CHANNEL_NUM_TX_CHUNKS_PER_TRANSACTION is an array for each channel indciate the number of chunks to keep track of * NAK requests from the receiver per transaction*/ /** -** \cfcfg RX chunks per transaction (per channel) -** -** \par Description: -** Number of chunks per transaction per channel (RX). -** -** \par Limits: -** -*/ + * @cfcfg RX chunks per transaction (per channel) + * + * @par Description: + * Number of chunks per transaction per channel (RX). + * + * @par Limits: + * + */ #define CF_CHANNEL_NUM_RX_CHUNKS_PER_TRANSACTION \ { \ CF_NAK_MAX_SEGMENTS, CF_NAK_MAX_SEGMENTS \ } /** -** \cfcfg TX chunks per transaction (per channel) -** -** \par Description: -** Number of chunks per transaction per channel (TX). -** -** \par Limits: -** -*/ + * @cfcfg TX chunks per transaction (per channel) + * + * @par Description: + * Number of chunks per transaction per channel (TX). + * + * @par Limits: + * + */ #define CF_CHANNEL_NUM_TX_CHUNKS_PER_TRANSACTION \ { \ CF_NAK_MAX_SEGMENTS, CF_NAK_MAX_SEGMENTS \ } /** -** \cfcfg Total number of chunks (tx, rx, all channels) -** -** \par Description: -** Must be equal to the sum of all values input in CF_CHANNEL_NUM_RX_CHUNKS_PER_TRANSACTION -** and CF_CHANNEL_NUM_TX_CHUNKS_PER_TRANSACTION. -** -** \par Limits: -** -*/ + * @cfcfg Total number of chunks (tx, rx, all channels) + * + * @par Description: + * Must be equal to the sum of all values input in CF_CHANNEL_NUM_RX_CHUNKS_PER_TRANSACTION + * and CF_CHANNEL_NUM_TX_CHUNKS_PER_TRANSACTION. + * + * @par Limits: + * + */ /* CF_TOTAL_CHUNKS must be equal to the total number of chunks per rx/tx transactions per channel */ /* (in other words, the summation of all elements in CF_CHANNEL_NUM_R/TX_CHUNKS_PER_TRANSACTION */ #define CF_TOTAL_CHUNKS (CF_NAK_MAX_SEGMENTS * 4) /* definitions that affect file queuing */ /** -** \cfcfg Number of max commanded playback files per chan. -** -** \par Description: -** This is the max number of outstanding ground commanded file transmits per channel. -** -** \par Limits: -** -*/ + * @cfcfg Number of max commanded playback files per chan. + * + * @par Description: + * This is the max number of outstanding ground commanded file transmits per channel. + * + * @par Limits: + * + */ #define CF_MAX_COMMANDED_PLAYBACK_FILES_PER_CHAN 10 /** -** \cfcfg Max number of simultaneous file receives. -** -** \par Description: -** Each channel can support this number of file receive transactions at a time. -** -** \par Limits: -** -*/ + * @cfcfg Max number of simultaneous file receives. + * + * @par Description: + * Each channel can support this number of file receive transactions at a time. + * + * @par Limits: + * + */ #define CF_MAX_SIMULTANEOUS_RX 5 /* definitions that affect execution */ /** -** \cfcfg Max number of commanded playback directories per channel. -** -** \par Description: -** Each channel can support this number of groudn commanded directory playbacks. -** -** \par Limits: -** -*/ + * @cfcfg Max number of commanded playback directories per channel. + * + * @par Description: + * Each channel can support this number of groudn commanded directory playbacks. + * + * @par Limits: + * + */ #define CF_MAX_COMMANDED_PLAYBACK_DIRECTORIES_PER_CHAN 2 /** -** \cfcfg Max number of polling directories per channel. -** -** \par Description: -** This affects the configuration table. There must be an entry (can -** be empty) for each of these polling directories per channel. -** -** \par Limits: -** -*/ + * @cfcfg Max number of polling directories per channel. + * + * @par Description: + * This affects the configuration table. There must be an entry (can + * be empty) for each of these polling directories per channel. + * + * @par Limits: + * + */ #define CF_MAX_POLLING_DIR_PER_CHAN 5 /** -** \cfcfg Number of transactions per playback directoriy. -** -** \par Description: -** Each playback/polling directory operation will be able to have this -** many active transfers at a time pending or active. -** -** \par Limits: -** -*/ + * @cfcfg Number of transactions per playback directoriy. + * + * @par Description: + * Each playback/polling directory operation will be able to have this + * many active transfers at a time pending or active. + * + * @par Limits: + * + */ #define CF_NUM_TRANSACTIONS_PER_PLAYBACK 5 /** -** \cfcfg Number of histories per channel -** -** \par Description: -** Each channel can support this number of file receive transactions at a time. -** -** \par Limits: -** 65536 is the current max. -*/ + * @cfcfg Number of histories per channel + * + * @par Description: + * Each channel can support this number of file receive transactions at a time. + * + * @par Limits: + * 65536 is the current max. + */ #define CF_NUM_HISTORIES_PER_CHANNEL 256 /** -** \cfcfg Max PDU size. -** -** \par Description: -** The max PDU size across all channels in the system. Keep in mind that -** the max filedata pdu will be smaller than this. This size includes -** the PDU headers and everything. While this is the max value for all -** channels, the outgoing_file_chunk_size in the configuration table -** is different for each channel so a smaller size can be used. -** -** \par Limits: -** -*/ + * @cfcfg Max PDU size. + * + * @par Description: + * The max PDU size across all channels in the system. Keep in mind that + * the max filedata pdu will be smaller than this. This size includes + * the PDU headers and everything. While this is the max value for all + * channels, the outgoing_file_chunk_size in the configuration table + * is different for each channel so a smaller size can be used. + * + * @par Limits: + * + */ /* CF_MAX_PDU_SIZE must be the max possible PDU for any channel. Channels can be configured with a smaller max. */ #define CF_MAX_PDU_SIZE 512 /** -** \cfcfg Name of the CF Configuration Table -** -** \par Description: -** This parameter defines the name of the CF Configuration Table. -** -** \par Limits -** The length of this string, including the NULL terminator cannot exceed -** the #OS_MAX_PATH_LEN value. -*/ + * @cfcfg Name of the CF Configuration Table + * + * @par Description: + * This parameter defines the name of the CF Configuration Table. + * + * @par Limits + * The length of this string, including the NULL terminator cannot exceed + * the #OS_MAX_PATH_LEN value. + */ #define CF_CONFIG_TABLE_NAME "config_table" /** -** \cfcfg CF Configuration Table Filename -** -** \par Description: -** The value of this constant defines the filename of the CF Config Table -** -** \par Limits -** The length of this string, including the NULL terminator cannot exceed -** the #OS_MAX_PATH_LEN value. -*/ + * @cfcfg CF Configuration Table Filename + * + * @par Description: + * The value of this constant defines the filename of the CF Config Table + * + * @par Limits + * The length of this string, including the NULL terminator cannot exceed + * the #OS_MAX_PATH_LEN value. + */ #define CF_CONFIG_TABLE_FILENAME "/cf/cf_def_config.tbl" /** -** \cfcfg Maximum file name length. -** -** \par Limits: -** -*/ + * @cfcfg Maximum file name length. + * + * @par Limits: + * + */ #define CF_FILENAME_MAX_NAME OS_MAX_FILE_NAME /** -** \cfcfg Maximum file path (not including file name) -** -** \par Limits: -** -*/ + * @cfcfg Maximum file path (not including file name) + * + * @par Limits: + * + */ #define CF_FILENAME_MAX_PATH (OS_MAX_PATH_LEN - OS_MAX_FILE_NAME) /** -** \cfcfg Max filename and path length. -** -** \par Limits: -** -*/ + * @cfcfg Max filename and path length. + * + * @par Limits: + * + */ #define CF_FILENAME_MAX_LEN (CF_FILENAME_MAX_NAME + CF_FILENAME_MAX_PATH) /** -** \cfcfg R2 crc calc chunk size -** -** \par Description -** R2 performs crc calculation upon file completion in chunks. This is the size -** of the buffer. The larger the size the more stack will be used, but -** the faster it can go. The overall number of bytes calculated per wakeup -** is set in the configuration table. -** -** \par Limits: -** -*/ + * @cfcfg R2 crc calc chunk size + * + * @par Description + * R2 performs crc calculation upon file completion in chunks. This is the size + * of the buffer. The larger the size the more stack will be used, but + * the faster it can go. The overall number of bytes calculated per wakeup + * is set in the configuration table. + * + * @par Limits: + * + */ #define CF_R2_CRC_CHUNK_SIZE 1024 #if CF_FILENAME_MAX_LEN > OS_MAX_PATH_LEN @@ -301,11 +316,11 @@ typedef uint32 CF_TransactionSeq_t; #endif /** -** \cfcfg Number of milliseconds to wait for a SB message -** -** \par Limits: -** -*/ + * @cfcfg Number of milliseconds to wait for a SB message + * + * @par Limits: + * + */ #define CF_RCVMSG_TIMEOUT 100 -#endif /* !_CF_PLATFORM_CFG_H_ */ +#endif /* !CF_PLATFORM_CFG_H */ diff --git a/fsw/platform_inc/cf_tbldefs.h b/fsw/platform_inc/cf_tbldefs.h index ed12dbf99..6d08a29b6 100644 --- a/fsw/platform_inc/cf_tbldefs.h +++ b/fsw/platform_inc/cf_tbldefs.h @@ -1,82 +1,95 @@ /************************************************************************ -** File: cf_tbldefs.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application Table Definitions header file -** -** -** -*************************************************************************/ - -#ifndef CF_TBLDEFS__H -#define CF_TBLDEFS__H + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application Table Definitions header file + */ + +#ifndef CF_TBLDEFS_H +#define CF_TBLDEFS_H #include "cf_platform_cfg.h" #include "cf_cfdp_pdu.h" +/** + * @brief Configuration entry for directory polling + * + */ typedef struct CF_PollDir { - uint32_t interval_sec; /* number of seconds to wait before trying a new directory. - Must be >0 or slot is inactive. */ - uint8 priority; /* priority to use when placing transactions on the pending queue */ - CF_CFDP_Class_t cfdp_class; /* the CFDP class to send */ - CF_EntityId_t dest_eid; /* destination entity id */ - char src_dir[CF_FILENAME_MAX_PATH]; /* path to source dir */ - char dst_dir[CF_FILENAME_MAX_PATH]; /* path to destination dir */ - uint8 enabled; + uint32 + interval_sec; /**< number of seconds to wait before trying a new directory. Must be >0 or slot is inactive. */ + uint8 priority; /**< priority to use when placing transactions on the pending queue */ + CF_CFDP_Class_t cfdp_class; /**< the CFDP class to send */ + CF_EntityId_t dest_eid; /**< destination entity id */ + + char src_dir[CF_FILENAME_MAX_PATH]; /**< path to source dir */ + char dst_dir[CF_FILENAME_MAX_PATH]; /**< path to destination dir */ + + uint8 enabled; } CF_PollDir_t; +/** + * @brief Configuration entry for CFDP channel + * + */ typedef struct CF_ChannelConfig { - uint32 max_outgoing_messages_per_wakeup; /* max number of messages to send per wakeup (0 - unlimited) */ - uint32 rx_max_messages_per_wakeup; /* max number of rx messages to process per wakeup */ + uint32 max_outgoing_messages_per_wakeup; /**< max number of messages to send per wakeup (0 - unlimited) */ + uint32 rx_max_messages_per_wakeup; /**< max number of rx messages to process per wakeup */ - CFE_SB_MsgId_Atom_t mid_input; /* msgid integer value for incoming messages */ - CFE_SB_MsgId_Atom_t mid_output; /* msgid integer value for outgoing messages */ + CFE_SB_MsgId_Atom_t mid_input; /**< msgid integer value for incoming messages */ + CFE_SB_MsgId_Atom_t mid_output; /**< msgid integer value for outgoing messages */ - uint16 pipe_depth_input; /* depth of pipe to receive incoming pdu */ + uint16 pipe_depth_input; /**< depth of pipe to receive incoming pdu */ - CF_PollDir_t polldir[CF_MAX_POLLING_DIR_PER_CHAN]; + CF_PollDir_t polldir[CF_MAX_POLLING_DIR_PER_CHAN]; /**< Configuration for polled directories */ - char sem_name[OS_MAX_API_NAME]; /* name of throttling semaphore in TO */ - uint8 dequeue_enabled; /* if 1, then the channel will make pending transactions active */ + char sem_name[OS_MAX_API_NAME]; /**< name of throttling semaphore in TO */ + uint8 dequeue_enabled; /**< if 1, then the channel will make pending transactions active */ } CF_ChannelConfig_t; +/** + * @brief Top-level CFDP configuration structure + * + */ typedef struct CF_ConfigTable { - uint32 ticks_per_second; /* expected ticks per second to cfdp app */ - uint32 rx_crc_calc_bytes_per_wakeup; /* max number of bytes per wakeup to calculate r2 crc for recvd file (must by + uint32 ticks_per_second; /**< expected ticks per second to cfdp app */ + uint32 rx_crc_calc_bytes_per_wakeup; /**< max number of bytes per wakeup to calculate r2 crc for recvd file (must be 1024-byte aligned */ - CF_EntityId_t local_eid; /* the local entity ID of the CF app */ + CF_EntityId_t local_eid; /**< the local entity ID of the CF app */ - CF_ChannelConfig_t chan[CF_NUM_CHANNELS]; + CF_ChannelConfig_t chan[CF_NUM_CHANNELS]; /**< Channel configuration */ - uint32 ack_timer_s; /* in seconds */ - uint32 nak_timer_s; /* in seconds */ - uint32 inactivity_timer_s; /* in seconds */ + uint32 ack_timer_s; /**< in seconds */ + uint32 nak_timer_s; /**< in seconds */ + uint32 inactivity_timer_s; /**< in seconds */ - uint8 ack_limit; /* number of times to retry ACK (for ex, send fin and wait for fin-ack) */ - uint8 nak_limit; /* number of times to retry NAK before giving up (resets on a single response */ + uint8 ack_limit; /**< number of times to retry ACK (for ex, send fin and wait for fin-ack) */ + uint8 nak_limit; /**< number of times to retry NAK before giving up (resets on a single response */ - uint16 outgoing_file_chunk_size; /* size of outgoing file data PDUs */ - char tmp_dir[CF_FILENAME_MAX_PATH]; /* temp directory to put temp files */ + uint16 outgoing_file_chunk_size; /**< maximum size of outgoing file data PDUs */ + char tmp_dir[CF_FILENAME_MAX_PATH]; /**< directory to put temp files */ } CF_ConfigTable_t; -#endif /* !CF_TBLDEFS__H */ +#endif /* !CF_TBLDEFS_H */ diff --git a/fsw/src/cf_app.c b/fsw/src/cf_app.c index 20890d56b..bc8b5678a 100644 --- a/fsw/src/cf_app.c +++ b/fsw/src/cf_app.c @@ -1,28 +1,28 @@ /************************************************************************ -** File: cf_app.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** Purpose: -** The CF Application main application source file -** -** This file contains the functions that initialize the application and link -** all logic and functionality to the CFS. -** -*************************************************************************/ + * File: cf_app.c + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * Purpose: + * The CF Application main application source file + * + * This file contains the functions that initialize the application and link + * all logic and functionality to the CFS. + * + ************************************************************************/ #include "cfe.h" #include "cf_verify.h" @@ -37,33 +37,28 @@ CF_AppData_t CF_AppData; -/************************************************************************/ -/** \brief Send CF housekeeping packet -** -** \par Description -** The command to send the CF housekeeping packet comes in on -** the software bus. This function sends the message. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_HkCmd + * + * Application-scope internal function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_HkCmd(void) { CFE_MSG_SetMsgTime(&CF_AppData.hk.tlm_header.Msg, CFE_TIME_GetTime()); /* return value ignored */ CFE_SB_TransmitMsg(&CF_AppData.hk.tlm_header.Msg, true); } -/************************************************************************/ -/** \brief Checks to see if a table update is pending, and perform it. -** -** \par Description -** Updates the table if the engine is disabled. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CheckTables + * + * Application-scope internal function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CheckTables(void) { CFE_Status_t status; @@ -111,21 +106,14 @@ void CF_CheckTables(void) } } -/************************************************************************/ -/** \brief Validation function for config table. -** -** \par Description -** Checks that the config table being loaded has correct data. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ValidateConfigTable + * + * Application-scope internal function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_ValidateConfigTable(void *tbl_ptr) { CF_ConfigTable_t *tbl = (CF_ConfigTable_t *)tbl_ptr; @@ -159,18 +147,14 @@ int32 CF_ValidateConfigTable(void *tbl_ptr) return ret; } -/************************************************************************/ -/** \brief Load the table on application start -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_TableInit + * + * Application-scope internal function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_TableInit(void) { int32 status = CFE_SUCCESS; @@ -217,22 +201,14 @@ int32 CF_TableInit(void) return status; } -/************************************************************************/ -/** \brief CF app init function -** -** \par Description -** Initializes all aspects of the CF application. Messages, -** pipes, events, table, and the cfdp engine. -** -** \par Assumptions, External Events, and Notes: -** This must only be called once. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Init + * + * Application-scope internal function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_Init(void) { static CFE_EVS_BinFilter_t cf_event_filters[] = { @@ -399,16 +375,14 @@ int32 CF_Init(void) return status; } -/************************************************************************/ -/** \brief CF wakeup function -** -** \par Description -** Performs a single engine cycle for each wakeup -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WakeUp + * + * Application-scope internal function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_WakeUp(void) { CFE_ES_PerfLogEntry(CF_PERF_ID_CYCLE_ENG); @@ -416,17 +390,14 @@ void CF_WakeUp(void) CFE_ES_PerfLogExit(CF_PERF_ID_CYCLE_ENG); } -/************************************************************************/ -/** \brief CF message processing function -** -** \par Description -** Initializes all aspects of the CF application. Messages, -** pipes, events, table, and the cfdp engine. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ProcessMsg + * + * Application-scope internal function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_ProcessMsg(CFE_SB_Buffer_t *msg) { CFE_SB_MsgId_t msg_id; @@ -456,17 +427,14 @@ void CF_ProcessMsg(CFE_SB_Buffer_t *msg) } } -/************************************************************************/ -/** \brief CF app entry point -** -** \par Description -** Main entry point of CF application. -** Calls the init function and manages the app run loop. -** -** \par Assumptions, External Events, and Notes: -** This must only be called once. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_AppMain + * + * Entry point function + * See description in cf_app.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_AppMain(void) { int32 status; diff --git a/fsw/src/cf_app.h b/fsw/src/cf_app.h index 33b1cce14..a9a425208 100644 --- a/fsw/src/cf_app.h +++ b/fsw/src/cf_app.h @@ -1,29 +1,29 @@ /************************************************************************ -** File: cf_app.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application main application header file -** -*************************************************************************/ - -#ifndef CF_APP__H -#define CF_APP__H + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application main application header file + */ + +#ifndef CF_APP_H +#define CF_APP_H #include "cfe.h" @@ -34,9 +34,21 @@ #include "cf_cfdp.h" #include "cf_clist.h" -#define CF_PIPE_NAME "CF_CMD_PIPE" +/** + * @brief The name of the application command pipe for CF + */ +#define CF_PIPE_NAME "CF_CMD_PIPE" + +/** + * @brief A common prefix for all data pipes for CF + */ #define CF_CHANNEL_PIPE_PREFIX "CF_CHAN_" +/** + * @brief The CF application global state structure + * + * This contains all variables related to CF application state + */ typedef struct { CF_HkPacket_t hk; @@ -52,15 +64,115 @@ typedef struct CF_Engine_t engine; } CF_AppData_t; -void CF_HkCmd(void); -void CF_CheckTables(void); +/** + * @brief Singleton instance of the application global data + */ +extern CF_AppData_t CF_AppData; + +/************************************************************************/ +/** @brief Send CF housekeeping packet + * + * @par Description + * The command to send the CF housekeeping packet + * + * @par Assumptions, External Events, and Notes: + * None + */ +void CF_HkCmd(void); + +/************************************************************************/ +/** @brief Checks to see if a table update is pending, and perform it. + * + * @par Description + * Updates the table if the engine is disabled. + * + * @par Assumptions, External Events, and Notes: + * None + */ +void CF_CheckTables(void); + +/************************************************************************/ +/** @brief Validation function for config table. + * + * @par Description + * Checks that the config table being loaded has correct data. + * + * @par Assumptions, External Events, and Notes: + * None + * + * + * @retval #CFE_SUCCESS \copydoc CFE_SUCCESSS + * @retval Returns anything else on error. + * + */ int32 CF_ValidateConfigTable(void *tbl_ptr); + +/************************************************************************/ +/** @brief Load the table on application start + * + * @par Assumptions, External Events, and Notes: + * None + * + * + * @retval #CFE_SUCCESS \copydoc CFE_SUCCESSS + * @retval Returns anything else on error. + * + */ int32 CF_TableInit(void); + +/************************************************************************/ +/** @brief CF app init function + * + * @par Description + * Initializes all aspects of the CF application. Messages, + * pipes, events, table, and the cfdp engine. + * + * @par Assumptions, External Events, and Notes: + * This must only be called once. + * + * + * @retval #CFE_SUCCESS \copydoc CFE_SUCCESSS + * @retval Returns anything else on error. + * + */ int32 CF_Init(void); -void CF_WakeUp(void); -void CF_ProcessMsg(CFE_SB_Buffer_t *msg); -void CF_AppMain(void); -extern CF_AppData_t CF_AppData; +/************************************************************************/ +/** @brief CF wakeup function + * + * @par Description + * Performs a single engine cycle for each wakeup + * + * @par Assumptions, External Events, and Notes: + * None + * + */ +void CF_WakeUp(void); + +/************************************************************************/ +/** @brief CF message processing function + * + * @par Description + * Initializes all aspects of the CF application. Messages, + * pipes, events, table, and the cfdp engine. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + */ +void CF_ProcessMsg(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief CF app entry point + * + * @par Description + * Main entry point of CF application. + * Calls the init function and manages the app run loop. + * + * @par Assumptions, External Events, and Notes: + * This must only be called once. + * + */ +void CF_AppMain(void); -#endif /* !CF_APP__H */ +#endif /* !CF_APP_H */ diff --git a/fsw/src/cf_assert.h b/fsw/src/cf_assert.h index fb42c9d00..e37d615c3 100644 --- a/fsw/src/cf_assert.h +++ b/fsw/src/cf_assert.h @@ -1,31 +1,29 @@ /************************************************************************ -** File: CF_Assert.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application CF_Assert macro -** -** Revision 1.0 2020/07/15 sseeger -** -*************************************************************************/ - -#ifndef CF_ASSERT__H -#define CF_ASSERT__H + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application CF_Assert macro + */ + +#ifndef CF_ASSERT_H +#define CF_ASSERT_H #include "cfe.h" @@ -58,4 +56,4 @@ #define CF_Assert(x) /* no-op */ #endif /* CF_DEBUG_BUILD */ -#endif /* !CF_ASSERT__H */ +#endif /* !CF_ASSERT_H */ diff --git a/fsw/src/cf_cfdp.c b/fsw/src/cf_cfdp.c index b0ff5ec55..d1f88d3c4 100644 --- a/fsw/src/cf_cfdp.c +++ b/fsw/src/cf_cfdp.c @@ -1,35 +1,34 @@ /************************************************************************ -** File: cf_cfdp.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application main cfdp engine and pdu parsing file -** -** This file contains two sets of functions. The first is what is needed -** to deal with CFDP PDUs. Specifically validating them for correctness -** and ensuring the byte-order is correct for the target. The second -** is incoming and outgoing CFDP PDUs pass through here. All receive -** CFDP PDU logic is performed here and the data is passed to the -** R (rx) and S (tx) logic. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application main cfdp engine and pdu parsing implementation + * + * This file contains two sets of functions. The first is what is needed + * to deal with CFDP PDUs. Specifically validating them for correctness + * and ensuring the byte-order is correct for the target. The second + * is incoming and outgoing CFDP PDUs pass through here. All receive + * CFDP PDU logic is performed here and the data is passed to the + * R (rx) and S (tx) logic. + */ #include "cfe.h" #include "cf_verify.h" @@ -47,17 +46,14 @@ #include #include "cf_assert.h" -/** - * @brief Initiate the process of encoding a new PDU to send +/*---------------------------------------------------------------- * - * This resets the encoder and PDU buffer to initial values, and prepares for encoding a new PDU - * for sending to a remote entity. + * Function: CF_CFDP_EncodeStart * - * @param penc Encoder state structure, will be reset/initialized by this call to point to msgbuf. - * @param msgbuf Pointer to encapsulation message, in this case a CFE software bus message - * @param ph Pointer to logical PDU buffer content, will be cleared to all zero by this call - * @param msgbuf_size Allocated size of msgbuf encapsulation structure (encoding cannot exceed this) - */ + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeStart(CF_EncoderState_t *penc, void *msgbuf, CF_Logical_PduBuffer_t *ph, size_t encap_hdr_size, size_t total_size) { @@ -86,17 +82,14 @@ void CF_CFDP_EncodeStart(CF_EncoderState_t *penc, void *msgbuf, CF_Logical_PduBu } } -/** - * @brief Initiate the process of decoding a receieved PDU +/*---------------------------------------------------------------- * - * This resets the decoder and PDU buffer to initial values, and prepares for decoding a new PDU - * that was received from a remote entity. + * Function: CF_CFDP_DecodeStart * - * @param pdec Decoder state structure, will be reset/initialized by this call to point to msgbuf. - * @param msgbuf Pointer to encapsulation message, in this case a CFE software bus message - * @param ph Pointer to logical PDU buffer content, will be cleared to all zero by this call - * @param msgbuf_size Total size of msgbuf encapsulation structure (decoding cannot exceed this) - */ + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeStart(CF_DecoderState_t *pdec, const void *msgbuf, CF_Logical_PduBuffer_t *ph, size_t encap_hdr_size, size_t total_size) { @@ -125,50 +118,40 @@ void CF_CFDP_DecodeStart(CF_DecoderState_t *pdec, const void *msgbuf, CF_Logical } } -/************************************************************************/ -/** \brief Arm the ack timer -** -** \par Description -** Helper function to arm the ack timer and set the flag. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ArmAckTimer + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_ArmAckTimer(CF_Transaction_t *t) { CF_Timer_InitRelSec(&t->ack_timer, CF_AppData.config_table->ack_timer_s); t->flags.com.ack_timer_armed = 1; } -/************************************************************************/ -/** \brief Determine the cfdp class (1 or 2) of the transaction -** -** \par Assumptions, External Events, and Notes: -** ti must not be null. ti must be an initialized transaction. -** -** \returns -** \retstmt 0 for class 1, and 1 for class 2 \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_GetClass + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline CF_CFDP_Class_t CF_CFDP_GetClass(const CF_Transaction_t *ti) { CF_Assert(ti->flags.com.q_index != CF_QueueIdx_FREE); return !!((ti->state == CF_TxnState_S2) || (ti->state == CF_TxnState_R2)); } -/************************************************************************/ -/** \brief Determine if a cfdp transaction is a sender or not -** -** \par Assumptions, External Events, and Notes: -** ti must not be null. ti must be an initialized transaction. -** -** \returns -** \retstmt 0 for receiver, and 1 for sender \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_IsSender + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline int CF_CFDP_IsSender(CF_Transaction_t *ti) { CF_Assert(ti->flags.com.q_index != CF_QueueIdx_FREE); @@ -177,29 +160,26 @@ static inline int CF_CFDP_IsSender(CF_Transaction_t *ti) return !!((ti->state == CF_TxnState_S1) || (ti->state == CF_TxnState_S2)); } -/************************************************************************/ -/** \brief arm inactivity timer -** -** \par Description -** Arms the inactivity timer for the given transaction from timeout -** specified in the config table. -** -** \par Assumptions, External Events, and Notes: -** The given transaction is active and initialized. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ArmInactTimer + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_CFDP_ArmInactTimer(CF_Transaction_t *t) { CF_Timer_InitRelSec(&t->inactivity_timer, CF_AppData.config_table->inactivity_timer_s); } -/************************************************************************/ -/** \brief Dispatch received packet to its transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be null. It must be an initialized transaction. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DispatchRecv + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { static const CF_CFDP_TxnRecvDispatchTable_t state_fns = {.rx = {[CF_TxnState_IDLE] = CF_CFDP_RecvIdle, @@ -213,13 +193,13 @@ void CF_CFDP_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) CF_CFDP_ArmInactTimer(t); /* whenever a packet was received by the other size, always arm its inactivity timer */ } -/************************************************************************/ -/** \brief Dispatches control to the active tx transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. t must be a valid tx transaction. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DispatchTx + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static void CF_CFDP_DispatchTx(CF_Transaction_t *t) { static const CF_CFDP_TxnSendDispatchTable_t state_fns = { @@ -228,17 +208,13 @@ static void CF_CFDP_DispatchTx(CF_Transaction_t *t) CF_CFDP_TxStateDispatch(t, &state_fns); } -/************************************************************************/ -/** \brief Get an unused chunks structure off the chunks queue. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retstmt Address to a free chunks structure. Will not be null. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_FindUnusedChunks + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static CF_ChunkWrapper_t *CF_CFDP_FindUnusedChunks(CF_Channel_t *c, CF_Direction_t dir) { CF_ChunkWrapper_t *ret; @@ -250,16 +226,13 @@ static CF_ChunkWrapper_t *CF_CFDP_FindUnusedChunks(CF_Channel_t *c, CF_Direction return ret; } -/************************************************************************/ -/** \brief Sets the PDU header length. -** -** \par Assumptions, External Events, and Notes: -** ph must not be NULL. -** -** This should be called once all encoding is complete. Therefore the final -** position of the encoder state should reflect the total size of the PDU. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_SetPduLength + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static void CF_CFDP_SetPduLength(CF_Logical_PduBuffer_t *ph) { uint16 final_pos; @@ -276,14 +249,14 @@ static void CF_CFDP_SetPduLength(CF_Logical_PduBuffer_t *ph) CF_CFDP_EncodeHeaderFinalSize(ph->penc, &ph->pdu_header); } -/************************************************************************/ -/** \brief Build the PDU header in the output buffer to prepare to send a packet. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** CF_AppData.engine.out.msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ConstructPduHeader + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_Logical_PduBuffer_t *CF_CFDP_ConstructPduHeader(const CF_Transaction_t *t, CF_CFDP_FileDirective_t directive_code, CF_EntityId_t src_eid, CF_EntityId_t dst_eid, bool towards_sender, CF_TransactionSeq_t tsn, bool silent) @@ -348,19 +321,13 @@ CF_Logical_PduBuffer_t *CF_CFDP_ConstructPduHeader(const CF_Transaction_t *t, CF return ph; } -/************************************************************************/ -/** \brief strnlen implementation because some older toolchain don't support -** -** TODO: remove this in favor of OS_strnlen someday -** -** \par Assumptions, External Events, and Notes: -** s must not be NULL. -** -** \returns -** \retstmt The length of the string not including null terminator, or maxlen if no null. -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_strnlen + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline size_t CF_strnlen(const char *s, size_t maxlen) { const char *end = memchr(s, 0, maxlen); @@ -372,19 +339,14 @@ static inline size_t CF_strnlen(const char *s, size_t maxlen) return maxlen; } -/************************************************************************/ -/** \brief Build a metadata PDU for transmit. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retcode CF_SendRet_SUCCESS on success. \endcode -** \retcode CF_SendRet_NO_MSG if message buffer cannot be obtained. \endcode -** \retcode CF_SendRet_ERROR if an error occurred while building the packet. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_SendMd + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_SendRet_t CF_CFDP_SendMd(CF_Transaction_t *t) { CF_Logical_PduBuffer_t *ph = @@ -424,19 +386,14 @@ CF_SendRet_t CF_CFDP_SendMd(CF_Transaction_t *t) return sret; } -/************************************************************************/ -/** \brief Build a filedata PDU for transmit. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retcode CF_SendRet_SUCCESS on success. \endcode -** \retcode CF_SendRet_NO_MSG if message buffer cannot be obtained. \endcode -** \retcode CF_SendRet_ERROR if an error occurred while building the packet. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_SendFd + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_SendRet_t CF_CFDP_SendFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* NOTE: SendFd does not need a call to CF_CFDP_MsgOutGet, as the caller already has it */ @@ -451,19 +408,14 @@ CF_SendRet_t CF_CFDP_SendFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Common functionality between SendEof and SendFin -** -** Writes the TLV for the faulting EID to the given address. -** -** \par Assumptions, External Events, and Notes: -** tlv must not be NULL. -** -** \returns -** \retstmt Returns the tlv length \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_AppendTlv + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_AppendTlv(CF_Logical_TlvList_t *ptlv_list, CF_CFDP_TlvType_t tlv_type) { CF_Logical_Tlv_t *ptlv; @@ -495,19 +447,14 @@ void CF_CFDP_AppendTlv(CF_Logical_TlvList_t *ptlv_list, CF_CFDP_TlvType_t tlv_ty } } -/************************************************************************/ -/** \brief Build a eof PDU for transmit. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retcode CF_SendRet_SUCCESS on success. \endcode -** \retcode CF_SendRet_NO_MSG if message buffer cannot be obtained. \endcode -** \retcode CF_SendRet_ERROR if an error occurred while building the packet. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_SendEof + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_SendRet_t CF_CFDP_SendEof(CF_Transaction_t *t) { CF_Logical_PduBuffer_t *ph = @@ -541,19 +488,14 @@ CF_SendRet_t CF_CFDP_SendEof(CF_Transaction_t *t) return ret; } -/************************************************************************/ -/** \brief Build a ack PDU for transmit. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retcode CF_SendRet_SUCCESS on success. \endcode -** \retcode CF_SendRet_NO_MSG if message buffer cannot be obtained. \endcode -** \retcode CF_SendRet_ERROR if an error occurred while building the packet. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_SendAck + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_SendRet_t CF_CFDP_SendAck(CF_Transaction_t *t, CF_CFDP_AckTxnStatus_t ts, CF_CFDP_FileDirective_t dir_code, CF_CFDP_ConditionCode_t cc, CF_EntityId_t peer_eid, CF_TransactionSeq_t tsn) { @@ -598,19 +540,14 @@ CF_SendRet_t CF_CFDP_SendAck(CF_Transaction_t *t, CF_CFDP_AckTxnStatus_t ts, CF_ return ret; } -/************************************************************************/ -/** \brief Build a fin PDU for transmit. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retcode CF_SendRet_SUCCESS on success. \endcode -** \retcode CF_SendRet_NO_MSG if message buffer cannot be obtained. \endcode -** \retcode CF_SendRet_ERROR if an error occurred while building the packet. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_SendFin + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_SendRet_t CF_CFDP_SendFin(CF_Transaction_t *t, CF_CFDP_FinDeliveryCode_t dc, CF_CFDP_FinFileStatus_t fs, CF_CFDP_ConditionCode_t cc) { @@ -645,19 +582,14 @@ CF_SendRet_t CF_CFDP_SendFin(CF_Transaction_t *t, CF_CFDP_FinDeliveryCode_t dc, return ret; } -/************************************************************************/ -/** \brief Build a nak PDU for transmit. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retcode CF_SendRet_SUCCESS on success. \endcode -** \retcode CF_SendRet_NO_MSG if message buffer cannot be obtained. \endcode -** \retcode CF_SendRet_ERROR if an error occurred while building the packet. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_SendNak + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_SendRet_t CF_CFDP_SendNak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { CF_Logical_PduNak_t *nak; @@ -686,22 +618,14 @@ CF_SendRet_t CF_CFDP_SendNak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Unpack a PDU header from a received message. -** -** \par Description -** PDUs are received and processed in-place, but there may be endian -** concerns as well as the need to check data for validity. -** -** \par Assumptions, External Events, and Notes: -** A new message has been received. -** -** \returns -** \retcode 0 on success \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvPh + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_RecvPh(uint8 chan_num, CF_Logical_PduBuffer_t *ph) { CF_Assert(chan_num < CF_NUM_CHANNELS); @@ -731,18 +655,14 @@ int CF_CFDP_RecvPh(uint8 chan_num, CF_Logical_PduBuffer_t *ph) return -1; } -/************************************************************************/ -/** \brief Unpack a metadata PDU from a received message. -** -** \par Assumptions, External Events, and Notes: -** A new message has been received. t must not be NULL. -** -** \returns -** \retcode 0 on success \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvMd + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_RecvMd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { const CF_Logical_PduMd_t *md = &ph->int_header.md; @@ -798,18 +718,14 @@ int CF_CFDP_RecvMd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return -1; } -/************************************************************************/ -/** \brief Unpack a file data PDU from a received message. -** -** \par Assumptions, External Events, and Notes: -** A new message has been received. t must not be NULL. -** -** \returns -** \retcode 0 on success \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvFd + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_RecvFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { int ret = 0; @@ -848,18 +764,14 @@ int CF_CFDP_RecvFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Unpack an eof PDU from a received message. -** -** \par Assumptions, External Events, and Notes: -** A new message has been received. -** -** \returns -** \retcode 0 on success \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvEof + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_RecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* CF_CFDP_RecvPh() must have been called before this, so use ldst to access pdu header */ @@ -877,18 +789,14 @@ int CF_CFDP_RecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Unpack an ack PDU from a received message. -** -** \par Assumptions, External Events, and Notes: -** A new message has been received. -** -** \returns -** \retcode 0 on success \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvAck + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_RecvAck(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* CF_CFDP_RecvPh() must have been called before this, so use ldst to access pdu header */ @@ -907,18 +815,14 @@ int CF_CFDP_RecvAck(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Unpack an ack PDU from a received message. -** -** \par Assumptions, External Events, and Notes: -** A new message has been received. -** -** \returns -** \retcode 0 on success \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvFin + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_RecvFin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* CF_CFDP_RecvPh() must have been called before this, so use ldst to access pdu header */ @@ -938,18 +842,14 @@ int CF_CFDP_RecvFin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Unpack a nak PDU from a received message. -** -** \par Assumptions, External Events, and Notes: -** A new message has been received. num_segment_requests must not be NULL. -** -** \returns -** \retcode 0 on success \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvNak + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_RecvNak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { int ret = 0; @@ -966,36 +866,27 @@ int CF_CFDP_RecvNak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Receive state function to ignore a packet. -** -** \par Description -** This function signature must match all receive state functions. -** The parameter t is ignored here. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvDrop + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_RecvDrop(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { ++CF_AppData.hk.channel_hk[t->chan_num].counters.recv.dropped; } -/************************************************************************/ -/** \brief Receive state function to process new rx transaction. -** -** \par Description -** An idle transaction has never had message processing performed on it. -** Typically, the first packet received for a transaction would be -** the metadata pdu. There's a special case for R2 where the metadata -** pdu could be missed, and filedata comes in instead. In that case, -** an R2 transaction must still be started. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. There must be a received message. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_RecvIdle + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_RecvIdle(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { CF_Logical_PduFileDirectiveHeader_t *fdh; @@ -1074,21 +965,14 @@ void CF_CFDP_RecvIdle(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) } } -/************************************************************************/ -/** \brief Initialization function for the cfdp engine -** -** \par Description -** Performs per-channel initialization. -** -** \par Assumptions, External Events, and Notes: -** Only called once. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_InitEngine + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_CFDP_InitEngine(void) { /* initialize all transaction nodes */ @@ -1169,23 +1053,14 @@ int32 CF_CFDP_InitEngine(void) return ret; } -/************************************************************************/ -/** \brief List traversal function that cycles the first active tx. -** -** \par Description -** There can only be one active tx transaction per engine cycle. -** This function finds the first active, and then sends file -** data pdus until there are no outgoing message buffers. -** -** \par Assumptions, External Events, and Notes: -** node must not be NULL. context must not be NULL. -** -** \returns -** \retcode 1 when it's found, which terminates list traversal \endcode -** \retcode 0 when it isn't found, which causes list traversal to continue \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_CycleTxFirstActive + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_CycleTxFirstActive(CF_CListNode_t *node, void *context) { CF_CFDP_CycleTx_args_t *args = (CF_CFDP_CycleTx_args_t *)context; @@ -1216,24 +1091,14 @@ int CF_CFDP_CycleTxFirstActive(CF_CListNode_t *node, void *context) return ret; /* exit traversal */ } -/************************************************************************/ -/** \brief Cycle the current active tx or make a new one active. -** -** \par Description -** First traverses all tx transactions on the active queue. If at -** least one is found, then it stops. Otherwise it moves a -** transaction on the pending queue to the active queue and -** tries again to find an active one. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_CycleTx + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_CycleTx(CF_Channel_t *c) { if (CF_AppData.config_table->chan[(c - CF_AppData.engine.channels)].dequeue_enabled) @@ -1263,18 +1128,14 @@ void CF_CFDP_CycleTx(CF_Channel_t *c) } } -/************************************************************************/ -/** \brief List traversal function that calls a r or s tick function. -** -** \par Assumptions, External Events, and Notes: -** node must not be NULL. context must not be NULL. -** -** \returns -** \retcode 1 when it's found, which terminates list traversal \endcode -** \retcode 0 when it isn't found, which causes list traversal to continue \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DoTick + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_DoTick(CF_CListNode_t *node, void *context) { int ret = CF_CLIST_CONT; /* CF_CLIST_CONT means don't tick one, keep looking for cur */ @@ -1302,23 +1163,14 @@ int CF_CFDP_DoTick(CF_CListNode_t *node, void *context) return ret; /* don't tick one, keep looking for cur */ } -/************************************************************************/ -/** \brief Call R and then S tick functions for all active transactions. -** -** \par Description -** Traverses all transactions in the RX and TXW queues, and calls -** their tick functions. Note that the TXW queue is used twice: -** once for regular tick processing, and one for NAK response. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_TickTransactions + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_TickTransactions(CF_Channel_t *c) { void (*fns[CF_TickType_NUM_TYPES])(CF_Transaction_t *, int *) = {CF_CFDP_R_Tick, CF_CFDP_S_Tick, @@ -1366,13 +1218,14 @@ void CF_CFDP_TickTransactions(CF_Channel_t *c) early_exit:; } -/************************************************************************/ -/** \brief Helper function to set tx file state in a transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_InitTxnTxFile + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_InitTxnTxFile(CF_Transaction_t *t, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority) { t->chan_num = chan; @@ -1381,17 +1234,13 @@ void CF_CFDP_InitTxnTxFile(CF_Transaction_t *t, CF_CFDP_Class_t cfdp_class, uint t->state = cfdp_class ? CF_TxnState_S2 : CF_TxnState_S1; } -/************************************************************************/ -/** \brief Helper function to set tx field state in a transaction. -** -** \par Description -** Sets up the transaction structure, including finding unused -** chunks and inserting the transaction into the PEND queue. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_TxFile_Initiate + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static void CF_CFDP_TxFile_Initiate(CF_Transaction_t *t, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority, CF_EntityId_t dest_id) { @@ -1413,22 +1262,14 @@ static void CF_CFDP_TxFile_Initiate(CF_Transaction_t *t, CF_CFDP_Class_t cfdp_cl CF_InsertSortPrio(t, CF_QueueIdx_PEND); } -/************************************************************************/ -/** \brief Begin transmit of a file. -** -** \par Description -** This function sets up a transaction for and starts transmit of -** the given filename. -** -** \par Assumptions, External Events, and Notes: -** src_filename must not be NULL. dst_filename must not be NULL. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_TxFile + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_CFDP_TxFile(const char *src_filename, const char *dst_filename, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority, CF_EntityId_t dest_id) { @@ -1465,21 +1306,13 @@ int32 CF_CFDP_TxFile(const char *src_filename, const char *dst_filename, CF_CFDP return ret; } -/************************************************************************/ -/** \brief Helper function to set up directory playback. -** -** \par Description -** Sets up CF_Playback_t data. Used by both playback and polling functions. -** -** \par Assumptions, External Events, and Notes: -** p must not be NULL. src_filename must not be NULL. dst_filename must not be NULL. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_PlaybackDir_Initiate + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static int32 CF_CFDP_PlaybackDir_Initiate(CF_Playback_t *p, const char *src_filename, const char *dst_filename, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority, CF_EntityId_t dest_id) @@ -1515,22 +1348,14 @@ static int32 CF_CFDP_PlaybackDir_Initiate(CF_Playback_t *p, const char *src_file return ret; } -/************************************************************************/ -/** \brief Begin transmit of a directory. -** -** \par Description -** This function sets up CF_Playback_t structure with state so it can -** become part of the directory polling done at each engine cycle. -** -** \par Assumptions, External Events, and Notes: -** src_filename must not be NULL. dst_filename must not be NULL. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_PlaybackDir + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_CFDP_PlaybackDir(const char *src_filename, const char *dst_filename, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority, uint16 dest_id) { @@ -1555,22 +1380,14 @@ int32 CF_CFDP_PlaybackDir(const char *src_filename, const char *dst_filename, CF return CF_CFDP_PlaybackDir_Initiate(p, src_filename, dst_filename, cfdp_class, keep, chan, priority, dest_id); } -/************************************************************************/ -/** \brief Step each active playback directory. -** -** \par Description -** Check if a playback directory needs iterated, and if so does, and -** if a valid file is found initiates playback on it. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. p must not be NULL. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ProcessPlaybackDirectory + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_ProcessPlaybackDirectory(CF_Channel_t *c, CF_Playback_t *p) { os_dirent_t dirent; @@ -1629,13 +1446,13 @@ void CF_CFDP_ProcessPlaybackDirectory(CF_Channel_t *c, CF_Playback_t *p) } } -/************************************************************************/ -/** \brief Update the playback or polling counter for channel HK -** -** \par Assumptions, External Events, and Notes: -** pb must not be NULL. counter must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_UpdatePollPbCounted + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static void CF_CFDP_UpdatePollPbCounted(CF_Playback_t *pb, int up, uint8 *counter) { if (pb->counted != up) @@ -1655,17 +1472,13 @@ static void CF_CFDP_UpdatePollPbCounted(CF_Playback_t *pb, int up, uint8 *counte } } -/************************************************************************/ -/** \brief Call CF_CFDP_ProcessPlaybackDirectory on all commanded playbacks. -** -** \par Description -** This function signature must match all receive state functions. -** The parameter t is ignored here. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ProcessPlaybackDirectories + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static void CF_CFDP_ProcessPlaybackDirectories(CF_Channel_t *c) { int i; @@ -1679,17 +1492,14 @@ static void CF_CFDP_ProcessPlaybackDirectories(CF_Channel_t *c) } } -/************************************************************************/ -/** \brief Kick the dir playback if timer elapsed. -** -** \par Description -** This function waits for the polling directory interval timer, -** and if it has expired, starts a playback in the polling directory. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ProcessPollingDirectories + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_ProcessPollingDirectories(CF_Channel_t *c) { int i; @@ -1746,13 +1556,14 @@ void CF_CFDP_ProcessPollingDirectories(CF_Channel_t *c) } } -/************************************************************************/ -/** \brief Cycle the engine. Called once per wakeup. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_CycleEngine + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_CycleEngine(void) { int i; @@ -1786,13 +1597,14 @@ void CF_CFDP_CycleEngine(void) } } -/************************************************************************/ -/** \brief Reset a transaction and all its internals to an unused state. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ResetTransaction + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_ResetTransaction(CF_Transaction_t *t, int keep_history) { CF_Channel_t *c = &CF_AppData.engine.channels[t->chan_num]; @@ -1853,18 +1665,14 @@ void CF_CFDP_ResetTransaction(CF_Transaction_t *t, int keep_history) CF_FreeTransaction(t); } -/************************************************************************/ -/** \brief Copy data from a lv (length, value) pair. -** -** \par Assumptions, External Events, and Notes: -** src_lv must not be NULL. data must not be NULL. -** -** \returns -** \retcode The number of bytes copied from the lv. \endcode -** \retcode -1 on error \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_CopyStringFromLV + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_CopyStringFromLV(char *buf, size_t buf_maxsz, const CF_Logical_Lv_t *src_lv) { if (src_lv->length < buf_maxsz) @@ -1879,13 +1687,14 @@ int CF_CFDP_CopyStringFromLV(char *buf, size_t buf_maxsz, const CF_Logical_Lv_t return -1; /* invalid len in lv? */ } -/************************************************************************/ -/** \brief Cancels a transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_CancelTransaction + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_CancelTransaction(CF_Transaction_t *t) { void (*fns[2])(CF_Transaction_t * t) = {CF_CFDP_R_Cancel, CF_CFDP_S_Cancel}; @@ -1897,16 +1706,14 @@ void CF_CFDP_CancelTransaction(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief List traversal function to close all files in all active transactions. -** -** \par Assumptions, External Events, and Notes: -** n must not be NULL. context must not be NULL. -** -** \returns -** \retcode Always 0 indicate list traversal should not exit early. \endcode -** \endreturns -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_CloseFiles + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_CloseFiles(CF_CListNode_t *n, void *context) { CF_Transaction_t *t = container_of(n, CF_Transaction_t, cl_node); @@ -1917,13 +1724,14 @@ int CF_CFDP_CloseFiles(CF_CListNode_t *n, void *context) return CF_CLIST_CONT; } -/************************************************************************/ -/** \brief Disables the cfdp engine and resets all state in it. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DisableEngine + * + * Application-scope internal function + * See description in cf_cfdp.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DisableEngine(void) { int i, j; diff --git a/fsw/src/cf_cfdp.h b/fsw/src/cf_cfdp.h index 1fb58e513..641735a03 100644 --- a/fsw/src/cf_cfdp.h +++ b/fsw/src/cf_cfdp.h @@ -1,40 +1,45 @@ /************************************************************************ -** File: cf_cfdp.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application cfdp engine and packet parsing header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application cfdp engine and packet parsing header file + */ #ifndef CF_CFDP_H #define CF_CFDP_H #include "cf_cfdp_types.h" +/** + * @brief Structure for use with the CF_CFDP_CycleTx() function + */ typedef struct CF_CFDP_CycleTx_args { - CF_Channel_t *c; - int ran_one; + CF_Channel_t *c; /**< channel structure */ + int ran_one; /**< should be set to 1 if a transaction was cycled */ } CF_CFDP_CycleTx_args_t; +/** + * @brief Structure for use with the CF_CFDP_DoTick() function + */ typedef struct CF_CFDP_Tick_args { CF_Channel_t *c; /* IN param */ @@ -43,75 +48,643 @@ typedef struct CF_CFDP_Tick_args int cont; /* if 1, then re-traverse the list */ } CF_CFDP_Tick_args_t; +/********************************************************************************/ +/** + * @brief Initiate the process of encoding a new PDU to send + * + * This resets the encoder and PDU buffer to initial values, and prepares for encoding a new PDU + * for sending to a remote entity. + * + * @param penc Encoder state structure, will be reset/initialized by this call to point to msgbuf. + * @param msgbuf Pointer to encapsulation message, in this case a CFE software bus message + * @param ph Pointer to logical PDU buffer content, will be cleared to all zero by this call + * @param encap_hdr_size Offset of first CFDP PDU octet within buffer + * @param msgbuf_size Allocated size of msgbuf encapsulation structure (encoding cannot exceed this) + */ void CF_CFDP_EncodeStart(CF_EncoderState_t *penc, void *msgbuf, CF_Logical_PduBuffer_t *ph, size_t encap_hdr_size, size_t total_size); + +/********************************************************************************/ +/** + * @brief Initiate the process of decoding a receieved PDU + * + * This resets the decoder and PDU buffer to initial values, and prepares for decoding a new PDU + * that was received from a remote entity. + * + * @param pdec Decoder state structure, will be reset/initialized by this call to point to msgbuf. + * @param msgbuf Pointer to encapsulation message, in this case a CFE software bus message + * @param ph Pointer to logical PDU buffer content, will be cleared to all zero by this call + * @param encap_hdr_size Offset of first CFDP PDU octet within buffer + * @param msgbuf_size Total size of msgbuf encapsulation structure (decoding cannot exceed this) + */ void CF_CFDP_DecodeStart(CF_DecoderState_t *pdec, const void *msgbuf, CF_Logical_PduBuffer_t *ph, size_t encap_hdr_size, size_t total_size); /* engine execution functions */ -void CF_CFDP_ResetTransaction(CF_Transaction_t *t, int keep_history); + +/************************************************************************/ +/** @brief Reset a transaction and all its internals to an unused state. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param keep_history Whether the transaction info should be preserved in history + */ +void CF_CFDP_ResetTransaction(CF_Transaction_t *t, int keep_history); + +/************************************************************************/ +/** @brief Initialization function for the cfdp engine + * + * @par Description + * Performs all initialization of the CFDP engine + * + * @par Assumptions, External Events, and Notes: + * Only called once. + * + * @retval #CFE_SUCCESS \copydoc CFE_SUCCESSS + * @returns anything else on error. + * + */ int32 CF_CFDP_InitEngine(void); -void CF_CFDP_CycleEngine(void); -void CF_CFDP_DisableEngine(void); -/* ground commands into the engine */ -/* returns NULL on err */ +/************************************************************************/ +/** @brief Cycle the engine. Called once per wakeup. + * + * @par Assumptions, External Events, and Notes: + * None + * + */ +void CF_CFDP_CycleEngine(void); + +/************************************************************************/ +/** @brief Disables the cfdp engine and resets all state in it. + * + * @par Assumptions, External Events, and Notes: + * None + * + */ +void CF_CFDP_DisableEngine(void); + +/************************************************************************/ +/** @brief Begin transmit of a file. + * + * @par Description + * This function sets up a transaction for and starts transmit of + * the given filename. + * + * @par Assumptions, External Events, and Notes: + * src_filename must not be NULL. dst_filename must not be NULL. + * + * @param src_filename Local filename + * @param dst_filename Remote filename + * @param cfdp_class Whether to perform a class 1 or class 2 transfer + * @param keep Whether to keep or delete the local file after completion + * @param chan CF channel number to use + * @param priority CF priority level + * @param dest_id Entity ID of remote receiver + * + * @retval #CFE_SUCCESS \copydoc CFE_SUCCESSS + * @returns Anything else on error. + */ int32 CF_CFDP_TxFile(const char *src_filename, const char *dst_filename, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority, CF_EntityId_t dest_id); + +/************************************************************************/ +/** @brief Begin transmit of a directory. + * + * @par Description + * This function sets up CF_Playback_t structure with state so it can + * become part of the directory polling done at each engine cycle. + * + * @par Assumptions, External Events, and Notes: + * src_filename must not be NULL. dst_filename must not be NULL. + * + * @param src_filename Local filename + * @param dst_filename Remote filename + * @param cfdp_class Whether to perform a class 1 or class 2 transfer + * @param keep Whether to keep or delete the local file after completion + * @param chan CF channel number to use + * @param priority CF priority level + * @param dest_id Entity ID of remote receiver + * + * @retval #CFE_SUCCESS \copydoc CFE_SUCCESSS + * @returns Anything else on error. + */ int32 CF_CFDP_PlaybackDir(const char *src_filename, const char *dst_filename, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority, uint16 dest_id); -/* PDU send functions */ -/* CF_CFDP_ConstructPduHeader sets length of 0. Must set it after building packet */ +/************************************************************************/ +/** @brief Build the PDU header in the output buffer to prepare to send a packet. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param directive_code Code to use for file directive headers (set to 0 for data) + * @param src_eid Value to set in source entity ID field + * @param dst_eid Value to set in destination entity ID field + * @param towards_sender Whether this is transmitting toward the sender entity + * @param tsn Transaction sequence number to put into PDU + * @param silent If true, supresses error event if no message buffer available + * + * @returns Pointer to PDU buffer which may be filled with additional data + * @retval NULL if no message buffer available + */ CF_Logical_PduBuffer_t *CF_CFDP_ConstructPduHeader(const CF_Transaction_t *t, CF_CFDP_FileDirective_t directive_code, CF_EntityId_t src_eid, CF_EntityId_t dst_eid, bool towards_sender, CF_TransactionSeq_t tsn, bool silent); -CF_SendRet_t CF_CFDP_SendMd(CF_Transaction_t *t); -CF_SendRet_t CF_CFDP_SendFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); -CF_SendRet_t CF_CFDP_SendEof(CF_Transaction_t *t); -/* NOTE: CF_CFDP_SendAck() takes a CF_TransactionSeq_t instead of getting it from transaction history because + +/************************************************************************/ +/** @brief Build a metadata PDU for transmit. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * + * @returns CF_SendRet_t status code + * @retval CF_SendRet_SUCCESS on success. + * @retval CF_SendRet_NO_MSG if message buffer cannot be obtained. + * @retval CF_SendRet_ERROR if an error occurred while building the packet. + */ +CF_SendRet_t CF_CFDP_SendMd(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Send a previously-assembled filedata PDU for transmit. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to logical PDU buffer content + * + * @note Unlike other "send" routines, the file data PDU must be acquired and + * filled by the caller prior to invoking this routine. This routine only + * sends the PDU that was previously allocated and assembled. As such, the + * typical failure possibilies do not apply to this call. + * + * @returns CF_SendRet_t status code + * @retval CF_SendRet_SUCCESS on success. + */ +CF_SendRet_t CF_CFDP_SendFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Build a eof PDU for transmit. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * + * @returns CF_SendRet_t status code + * @retval CF_SendRet_SUCCESS on success. + * @retval CF_SendRet_NO_MSG if message buffer cannot be obtained. + * @retval CF_SendRet_ERROR if an error occurred while building the packet. + */ +CF_SendRet_t CF_CFDP_SendEof(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Build a ack PDU for transmit. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @note CF_CFDP_SendAck() takes a CF_TransactionSeq_t instead of getting it from transaction history because * of the special case where a FIN-ACK must be sent for an unknown transaction. It's better for * long term maintenance to not build an incomplete CF_History_t for it. + * + * @param t Pointer to the transaction object + * @param ts Transaction ACK status + * @param dir_code File directive code being ACK'ed + * @param cc Condition code of transaction + * @param peer_eid Remote entity ID + * @param tsn Transaction sequence number + * + * @returns CF_SendRet_t status code + * @retval CF_SendRet_SUCCESS on success. + * @retval CF_SendRet_NO_MSG if message buffer cannot be obtained. + * @retval CF_SendRet_ERROR if an error occurred while building the packet. + * */ CF_SendRet_t CF_CFDP_SendAck(CF_Transaction_t *t, CF_CFDP_AckTxnStatus_t ts, CF_CFDP_FileDirective_t dir_code, CF_CFDP_ConditionCode_t cc, CF_EntityId_t peer_eid, CF_TransactionSeq_t tsn); + +/************************************************************************/ +/** @brief Build a fin PDU for transmit. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param dc Final delivery status code (complete or incomplete) + * @param fs Final file status (retained or rejected, etc) + * @param cc Final CFDP condition code + * + * @returns CF_SendRet_t status code + * @retval CF_SendRet_SUCCESS on success. + * @retval CF_SendRet_NO_MSG if message buffer cannot be obtained. + * @retval CF_SendRet_ERROR if an error occurred while building the packet. + */ CF_SendRet_t CF_CFDP_SendFin(CF_Transaction_t *t, CF_CFDP_FinDeliveryCode_t dc, CF_CFDP_FinFileStatus_t fs, CF_CFDP_ConditionCode_t cc); + +/************************************************************************/ +/** @brief Send a previously-assembled nak PDU for transmit. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to logical PDU buffer content + * + * @note Unlike other "send" routines, the NAK PDU must be acquired and + * filled by the caller prior to invoking this routine. This routine only + * encodes and sends the previously-assembled PDU buffer. As such, the + * typical failure possibilies do not apply to this call. + * + * @returns CF_SendRet_t status code + * @retval CF_SendRet_SUCCESS on success. + */ CF_SendRet_t CF_CFDP_SendNak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); +/************************************************************************/ +/** @brief Appends a single TLV value to the logical PDU data + * + * This function implements common functionality between SendEof and SendFin + * which append a TLV value specifying the faulting entity ID. + * + * @par Assumptions, External Events, and Notes: + * ptlv_list must not be NULL. + * Only CF_CFDP_TLV_TYPE_ENTITY_ID type is currently implemented + * + * @param ptlv_list TLV list from current PDU buffer. + * @param tlv_type Type of TLV to append. Currently must be CF_CFDP_TLV_TYPE_ENTITY_ID. + */ void CF_CFDP_AppendTlv(CF_Logical_TlvList_t *ptlv_list, CF_CFDP_TlvType_t tlv_type); -/* PDU receive functions */ -/* returns 0 on success */ +/************************************************************************/ +/** @brief Unpack a basic PDU header from a received message. + * + * @par Description + * This interprets the common PDU header and the file directive header + * (if applicable) and populates the logical PDU buffer. + * + * @par Assumptions, External Events, and Notes: + * A new message has been received. + * + * @param chan_num The channel number for statistics purposes + * @param ph The logical PDU buffer being received + * + * @returns integer status code + * @retval 0 on success + * @retval -1 on error + * + */ int CF_CFDP_RecvPh(uint8 chan_num, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Unpack a metadata PDU from a received message. + * + * This should only be invoked for buffers that have been identified + * as a metadata PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + * + * @returns integer status code + * @retval 0 on success + * @retval -1 on error + */ int CF_CFDP_RecvMd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Unpack a file data PDU from a received message. + * + * This should only be invoked for buffers that have been identified + * as a file data PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + * + * @returns integer status code + * @retval 0 on success + * @retval -1 on error + * + */ int CF_CFDP_RecvFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Unpack an eof PDU from a received message. + * + * This should only be invoked for buffers that have been identified + * as an end of file PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + * + * @returns integer status code + * @retval 0 on success + * @retval -1 on error + * + */ int CF_CFDP_RecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Unpack an ack PDU from a received message. + * + * This should only be invoked for buffers that have been identified + * as an acknowledgement PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + * + * @returns integer status code + * @retval 0 on success + * @retval -1 on error + * + */ int CF_CFDP_RecvAck(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Unpack an fin PDU from a received message. + * + * This should only be invoked for buffers that have been identified + * as an final PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + * + * @returns integer status code + * @retval 0 on success + * @retval -1 on error + * + */ int CF_CFDP_RecvFin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Unpack a nak PDU from a received message. + * + * This should only be invoked for buffers that have been identified + * as an negative/non-acknowledgement PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + * + * @returns integer status code + * @retval 0 on success + * @retval -1 on error + * + */ int CF_CFDP_RecvNak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); +/************************************************************************/ +/** @brief Dispatch received packet to its handler. + * + * This dispatches the PDU to the appropriate handler + * based on the transaction state + * + * @par Assumptions, External Events, and Notes: + * t must not be null. It must be an initialized transaction. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + * + */ void CF_CFDP_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); +/************************************************************************/ +/** @brief Cancels a transaction. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * + */ void CF_CFDP_CancelTransaction(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Helper function to set tx file state in a transaction. + * + * This sets various fields inside a newly-allocated transaction + * structure appropriately for sending a file. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param cfdp_class Set to class 1 or class 2 + * @param keep Whether to keep the local file + * @param chan CF channel number + * @param priority Priority of transfer + * + */ void CF_CFDP_InitTxnTxFile(CF_Transaction_t *t, CF_CFDP_Class_t cfdp_class, uint8 keep, uint8 chan, uint8 priority); /* functions to handle LVs (length-value, cfdp spec) */ /* returns number of bytes copied, or -1 on error */ -extern int CF_CFDP_CopyStringFromLV(char *buf, size_t buf_maxsz, const CF_Logical_Lv_t *src_lv); -extern void CF_CFDP_ArmAckTimer(CF_Transaction_t *t); +/************************************************************************/ +/** @brief Copy string data from a lv (length, value) pair. + * + * This copies a string value from an LV pair inside a PDU buffer. + * In CF this is used for file names embedded within PDUs. + * + * @note This function assures that the output string is terminated + * appropriately, such that it can be used as a normal C string. As + * such, the buffer size must be at least 1 byte larger than the maximum + * string length. + * + * @par Assumptions, External Events, and Notes: + * src_lv must not be NULL. buf must not be NULL. + * + * @param buf Pointer to buffer to store string + * @param buf_maxsz Total size of buffer pointer to by buf (usable size is 1 byte less, for termination) + * @param src_lv Pointer to LV pair from logical PDU buffer + * + * @returns The resulting string length, NOT including termination character + * @retval -1 on error + */ +int CF_CFDP_CopyStringFromLV(char *buf, size_t buf_maxsz, const CF_Logical_Lv_t *src_lv); +/************************************************************************/ +/** @brief Arm the ack timer + * + * @par Description + * Helper function to arm the ack timer and set the flag. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + */ +void CF_CFDP_ArmAckTimer(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Receive state function to ignore a packet. + * + * @par Description + * This function signature must match all receive state functions. + * The parameter t is ignored here. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + */ void CF_CFDP_RecvDrop(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Receive state function to process new rx transaction. + * + * @par Description + * An idle transaction has never had message processing performed on it. + * Typically, the first packet received for a transaction would be + * the metadata pdu. There's a special case for R2 where the metadata + * pdu could be missed, and filedata comes in instead. In that case, + * an R2 transaction must still be started. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. There must be a received message. + * + * @param t Pointer to the transaction state + * @param ph The logical PDU buffer being received + */ void CF_CFDP_RecvIdle(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); +/************************************************************************/ +/** @brief List traversal function to close all files in all active transactions. + * + * This helper is used in conjunction with CF_CList_Traverse(). + * + * @par Assumptions, External Events, and Notes: + * n must not be NULL. + * + * @param n List node pointer + * @param context Opaque pointer, not used in this function + * + * @returns integer traversal code + * @retval Always CF_LIST_CONT indicate list traversal should not exit early. + */ int CF_CFDP_CloseFiles(CF_CListNode_t *n, void *context); +/************************************************************************/ +/** @brief Cycle the current active tx or make a new one active. + * + * @par Description + * First traverses all tx transactions on the active queue. If at + * least one is found, then it stops. Otherwise it moves a + * transaction on the pending queue to the active queue and + * tries again to find an active one. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param c Channel to cycle + */ void CF_CFDP_CycleTx(CF_Channel_t *c); -int CF_CFDP_CycleTxFirstActive(CF_CListNode_t *node, void *context); + +/************************************************************************/ +/** @brief List traversal function that cycles the first active tx. + * + * This helper is used in conjunction with CF_CList_Traverse(). + * + * @par Description + * There can only be one active tx transaction per engine cycle. + * This function finds the first active, and then sends file + * data pdus until there are no outgoing message buffers. + * + * @par Assumptions, External Events, and Notes: + * node must not be NULL. context must not be NULL. + * + * @param node Pointer to list node + * @param context Pointer to CF_CFDP_CycleTx_args_t object (passed through) + * + * @returns integer traversal code + * @retval CF_CLIST_EXIT when it's found, which terminates list traversal + * @retval CF_CLIST_CONT when it's isn't found, which causes list traversal to continue + */ +int CF_CFDP_CycleTxFirstActive(CF_CListNode_t *node, void *context); + +/************************************************************************/ +/** @brief Call R and then S tick functions for all active transactions. + * + * @par Description + * Traverses all transactions in the RX and TXW queues, and calls + * their tick functions. Note that the TXW queue is used twice: + * once for regular tick processing, and one for NAK response. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param c Channel to tick + */ void CF_CFDP_TickTransactions(CF_Channel_t *c); + +/************************************************************************/ +/** @brief Step each active playback directory. + * + * @par Description + * Check if a playback directory needs iterated, and if so does, and + * if a valid file is found initiates playback on it. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. p must not be NULL. + * + * @param c The channel associated with the playback + * @param p The playback state + */ void CF_CFDP_ProcessPlaybackDirectory(CF_Channel_t *c, CF_Playback_t *p); + +/************************************************************************/ +/** @brief Kick the dir playback if timer elapsed. + * + * @par Description + * This function waits for the polling directory interval timer, + * and if it has expired, starts a playback in the polling directory. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param c The channel associated with the playback + */ void CF_CFDP_ProcessPollingDirectories(CF_Channel_t *c); -int CF_CFDP_DoTick(CF_CListNode_t *node, void *context); + +/************************************************************************/ +/** @brief List traversal function that calls a r or s tick function. + * + * This helper is used in conjunction with CF_CList_Traverse(). + * + * @par Assumptions, External Events, and Notes: + * node must not be NULL. context must not be NULL. + * + * @param node Pointer to list node + * @param context Pointer to CF_CFDP_Tick_args_t object (passed through) + * + * @returns integer traversal code + * @retval CF_CLIST_EXIT when it's found, which terminates list traversal + * @retval CF_CLIST_CONT when it's isn't found, which causes list traversal to continue + */ +int CF_CFDP_DoTick(CF_CListNode_t *node, void *context); #endif /* !CF_CFDP_H */ diff --git a/fsw/src/cf_cfdp_dispatch.c b/fsw/src/cf_cfdp_dispatch.c index 3a4f01451..c9cc0d33b 100644 --- a/fsw/src/cf_cfdp_dispatch.c +++ b/fsw/src/cf_cfdp_dispatch.c @@ -1,24 +1,24 @@ /************************************************************************ -** File: cf_cfdp_dispatch.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** -*************************************************************************/ + * File: cf_cfdp_dispatch.c + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + * + ************************************************************************/ #include "cfe.h" #include "cf_verify.h" @@ -39,7 +39,7 @@ * Function: CF_CFDP_R_DispatchRecv * * Application-scope internal function - * See description in header file for argument/return detail + * See description in cf_cfdp_dispatch.h for argument/return detail * *-----------------------------------------------------------------*/ void CF_CFDP_R_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, @@ -98,7 +98,7 @@ void CF_CFDP_R_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, * Function: CF_CFDP_S_DispatchRecv * * Application-scope internal function - * See description in header file for argument/return detail + * See description in cf_cfdp_dispatch.h for argument/return detail * *-----------------------------------------------------------------*/ void CF_CFDP_S_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, @@ -156,7 +156,7 @@ void CF_CFDP_S_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, * Function: CF_CFDP_S_DispatchTransmit * * Application-scope internal function - * See description in header file for argument/return detail + * See description in cf_cfdp_dispatch.h for argument/return detail * *-----------------------------------------------------------------*/ void CF_CFDP_S_DispatchTransmit(CF_Transaction_t *t, const CF_CFDP_S_SubstateSendDispatchTable_t *dispatch) @@ -175,7 +175,7 @@ void CF_CFDP_S_DispatchTransmit(CF_Transaction_t *t, const CF_CFDP_S_SubstateSen * Function: CF_CFDP_TxStateDispatch * * Application-scope internal function - * See description in header file for argument/return detail + * See description in cf_cfdp_dispatch.h for argument/return detail * *-----------------------------------------------------------------*/ void CF_CFDP_TxStateDispatch(CF_Transaction_t *t, const CF_CFDP_TxnSendDispatchTable_t *dispatch) @@ -195,7 +195,7 @@ void CF_CFDP_TxStateDispatch(CF_Transaction_t *t, const CF_CFDP_TxnSendDispatchT * Function: CF_CFDP_RxStateDispatch * * Application-scope internal function - * See description in header file for argument/return detail + * See description in cf_cfdp_dispatch.h for argument/return detail * *-----------------------------------------------------------------*/ void CF_CFDP_RxStateDispatch(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, diff --git a/fsw/src/cf_cfdp_dispatch.h b/fsw/src/cf_cfdp_dispatch.h index 48fd9c7ea..ea2e79d5f 100644 --- a/fsw/src/cf_cfdp_dispatch.h +++ b/fsw/src/cf_cfdp_dispatch.h @@ -1,24 +1,29 @@ /************************************************************************ -** File: cf_cfdp_dispatch.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ + +/** + * @file + * + * Common routines to dispatch operations based on a transaction state + * and/or received PDU type. + */ #ifndef CF_CFDP_DISPATCH_H #define CF_CFDP_DISPATCH_H @@ -119,6 +124,7 @@ typedef struct CF_CFDP_StateSendFunc_t substate[CF_TxSubState_NUM_STATES]; } CF_CFDP_S_SubstateSendDispatchTable_t; +/************************************************************************/ /** * @brief Dispatch function for received PDUs on receieve-file transactions * @@ -132,6 +138,7 @@ typedef struct void CF_CFDP_R_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, const CF_CFDP_R_SubstateDispatchTable_t *dispatch, CF_CFDP_StateRecvFunc_t fd_fn); +/************************************************************************/ /** * @brief Dispatch function for received PDUs on send-file transactions * @@ -145,6 +152,7 @@ void CF_CFDP_R_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, void CF_CFDP_S_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, const CF_CFDP_S_SubstateRecvDispatchTable_t *dispatch); +/************************************************************************/ /** * @brief Dispatch function to send/generate PDUs on send-file transactions * @@ -158,6 +166,7 @@ void CF_CFDP_S_DispatchRecv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph, */ void CF_CFDP_S_DispatchTransmit(CF_Transaction_t *t, const CF_CFDP_S_SubstateSendDispatchTable_t *dispatch); +/************************************************************************/ /** * @brief Top-level Dispatch function send a PDU based on current state of a transaction * @@ -169,6 +178,7 @@ void CF_CFDP_S_DispatchTransmit(CF_Transaction_t *t, const CF_CFDP_S_SubstateSen */ void CF_CFDP_TxStateDispatch(CF_Transaction_t *t, const CF_CFDP_TxnSendDispatchTable_t *dispatch); +/************************************************************************/ /** * @brief Top-level Dispatch function receive a PDU based on current state of a transaction * diff --git a/fsw/src/cf_cfdp_pdu.h b/fsw/src/cf_cfdp_pdu.h index e5b123d24..e2aa29505 100644 --- a/fsw/src/cf_cfdp_pdu.h +++ b/fsw/src/cf_cfdp_pdu.h @@ -1,5 +1,4 @@ /************************************************************************ -** File: cf_cfdp_pdu.h ** ** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) ** Application version 3.0.0” @@ -16,13 +15,7 @@ ** See the License for the specific language governing permissions and ** limitations under the License. ** -** -** Purpose: -** The CF Application CFDP PDU definitions header file -** -** -** -*************************************************************************/ +*/ /** * @file diff --git a/fsw/src/cf_cfdp_r.c b/fsw/src/cf_cfdp_r.c index 441a98952..243be19a2 100644 --- a/fsw/src/cf_cfdp_r.c +++ b/fsw/src/cf_cfdp_r.c @@ -1,30 +1,30 @@ /************************************************************************ -** File: cf_cfdp_r.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application CFDP receive logic source file -** -** Handles all CFDP engine functionality specific to RX transactions. -** -** -** -*************************************************************************/ + * File: cf_cfdp_r.c + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + * Purpose: + * The CF Application CFDP receive logic source file + * + * Handles all CFDP engine functionality specific to RX transactions. + * + * + * + ************************************************************************/ #include "cfe.h" #include "cf_verify.h" @@ -41,46 +41,41 @@ #include #include "cf_assert.h" -/************************************************************************/ -/** \brief Helper function to store condition code set send_fin flag. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_SetCc + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_SetCc(CF_Transaction_t *t, CF_CFDP_ConditionCode_t cc) { t->history->cc = cc; t->flags.rx.send_fin = 1; } -/************************************************************************/ -/** \brief CFDP R1 transaction reset function. -** -** \par Description -** All R transactions use this call to indicate the transaction -** state can be returned to the system. While this function currently -** only calls CF_CFDP_ResetTransaction(), it is here as a placeholder. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R1_Reset + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R1_Reset(CF_Transaction_t *t) { CF_CFDP_ResetTransaction(t, 1); } -/************************************************************************/ -/** \brief CFDP R2 transaction reset function. -** -** \par Description -** Handles reset logic for R2, then calls R1 reset logic. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_Reset + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_Reset(CF_Transaction_t *t) { if ((t->state_data.r.sub_state == CF_RxSubState_WAIT_FOR_FIN_ACK) || @@ -96,17 +91,14 @@ void CF_CFDP_R2_Reset(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief Checks that the transaction file's CRC matches expected. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt 0 on CRC match, otherwise error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_CheckCrc + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_R_CheckCrc(CF_Transaction_t *t, uint32 expected_crc) { int ret = 0; @@ -124,22 +116,14 @@ int CF_CFDP_R_CheckCrc(CF_Transaction_t *t, uint32 expected_crc) return ret; } -/************************************************************************/ -/** \brief Checks R2 transaction state for transaction completion status. -** -** \par Description -** This function is called anywhere there's a desire to know if the -** transaction has completed. It may trigger other actions by setting -** flags to be handled during tick processing. In order for a -** transaction to be complete, it must have had its meta-data PDU -** received, the EOF must have been received, and there must be -** no gaps in the file. EOF is not checked in this function, because -** it's only called from functions after EOF is received. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_Complete + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_Complete(CF_Transaction_t *t, int ok_to_send_nak) { int send_nak = 0; @@ -204,17 +188,14 @@ void CF_CFDP_R2_Complete(CF_Transaction_t *t, int ok_to_send_nak) err_out:; } -/************************************************************************/ -/** \brief Process a filedata PDU on a transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. bytes_received must not be NULL. -** -** \returns -** \retstmt 0 on success. Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_ProcessFd + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_R_ProcessFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { const CF_Logical_PduFileDataHeader_t *fd; @@ -264,22 +245,14 @@ int CF_CFDP_R_ProcessFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Processing receive EOF common functionality for R1/R2. -** -** \par Description -** This function is used for both R1 and R2 eof receive. It calls -** the unmarshaling function and then checks known transaction -** data against the PDU. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -** \returns -** \retstmt 0 on success. Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_SubstateRecvEof + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_R_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { int ret = CF_RxEofRet_SUCCESS; @@ -315,20 +288,14 @@ int CF_CFDP_R_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) return ret; } -/************************************************************************/ -/** \brief Process receive EOF for R1. -** -** \par Description -** Only need to confirm crc for R1. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -** \returns -** \retstmt 0 on success. Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R1_SubstateRecvEof + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R1_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { int ret = CF_CFDP_R_SubstateRecvEof(t, ph); @@ -351,21 +318,14 @@ void CF_CFDP_R1_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) CF_CFDP_R1_Reset(t); } -/************************************************************************/ -/** \brief Process receive EOF for R2. -** -** \par Description -** For R2, need to trigger the send of EOF-ACK and then call the -** check complete function which will either send NAK or FIN. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -** \returns -** \retstmt 0 on success. Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_SubstateRecvEof + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { const CF_Logical_PduEof_t *eof; @@ -416,16 +376,14 @@ void CF_CFDP_R2_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) } } -/************************************************************************/ -/** \brief Process received file data for R1. -** -** \par Description -** For R1, only need to digest the CRC. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R1_SubstateRecvFileData + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R1_SubstateRecvFileData(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* got file data pdu? */ @@ -443,20 +401,14 @@ void CF_CFDP_R1_SubstateRecvFileData(CF_Transaction_t *t, CF_Logical_PduBuffer_t CF_CFDP_R1_Reset(t); } -/************************************************************************/ -/** \brief Process received file data for R2. -** -** \par Description -** For R2, the CRC is checked after the whole file is received -** since there may be gaps. Instead, insert file received range -** data into chunks. Once NAK has been received, this function -** always checks for completion. This function also re-arms -** the ack timer. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_SubstateRecvFileData + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_SubstateRecvFileData(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { const CF_Logical_PduFileDataHeader_t *fd; @@ -491,20 +443,14 @@ void CF_CFDP_R2_SubstateRecvFileData(CF_Transaction_t *t, CF_Logical_PduBuffer_t CF_CFDP_R2_Reset(t); } -/************************************************************************/ -/** \brief Loads a single NAK segment request. -** -** \par Description -** This is a function callback from cf_chunks_compuete_gaps(). -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. c must not be NULL. opaque must not be NULL. -** -** \returns -** \retstmt 0 on success. Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_GapCompute + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_GapCompute(const CF_ChunkList_t *chunks, const CF_Chunk_t *c, void *opaque) { CF_GapComputeArgs_t *args = (CF_GapComputeArgs_t *)opaque; @@ -531,24 +477,14 @@ void CF_CFDP_R2_GapCompute(const CF_ChunkList_t *chunks, const CF_Chunk_t *c, vo } } -/************************************************************************/ -/** \brief Send a NAK pdu for R2. -** -** \par Description -** NAK pdu is sent when there are gaps in the received data. The -** chunks class tracks this and generates the nak pdu by calculating -** gaps internally and calling CF_CFDP_R2_GapCompute(). There is a special -** case where if a metadata pdu has not been received, then a nak -** packet will be sent to request another. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt 0 on success. Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_SubstateSendNak + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_R_SubstateSendNak(CF_Transaction_t *t) { CF_Logical_PduBuffer_t *ph = @@ -625,13 +561,14 @@ int CF_CFDP_R_SubstateSendNak(CF_Transaction_t *t) return ret; } -/************************************************************************/ -/** \brief Initialize a transaction structure for R. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_Init + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R_Init(CF_Transaction_t *t) { int32 ret; @@ -679,28 +616,14 @@ void CF_CFDP_R_Init(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief Calculate up to the configured amount of bytes of CRC. -** -** \par Description -** The configuration table has a number of bytes to calculate per -** transaction per wakeup. At each wakeup, the file is read and -** this number of bytes are calculated. This function will set -** the checksum error condition code if the final crc does not match. -** -** \par PTFO -** Increase throughput by consuming all crc bytes per wakeup in -** transaction-order. This would require a change to the meaning -** of the value in the configuration table. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt 0 on completion, and -1 on non-completion. Error status is stored in condition code. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_CalcCrcChunk + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_R2_CalcCrcChunk(CF_Transaction_t *t) { uint8 buf[CF_R2_CRC_CHUNK_SIZE]; @@ -791,17 +714,14 @@ int CF_CFDP_R2_CalcCrcChunk(CF_Transaction_t *t) return ret; } -/************************************************************************/ -/** \brief Send a FIN pdu. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt 0 on success. Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_SubstateSendFin + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_R2_SubstateSendFin(CF_Transaction_t *t) { CF_SendRet_t sret; @@ -832,17 +752,14 @@ int CF_CFDP_R2_SubstateSendFin(CF_Transaction_t *t) return ret; } -/************************************************************************/ -/** \brief Process receive FIN-ACK pdu. -** -** \par Description -** This is the end of an R2 transaction. Simply reset the transaction -** state. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_Recv_fin_ack + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_Recv_fin_ack(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { if (!CF_CFDP_RecvAck(t, ph)) @@ -858,20 +775,14 @@ void CF_CFDP_R2_Recv_fin_ack(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) } } -/************************************************************************/ -/** \brief Process receive metadata pdu for R2. -** -** \par Description -** It's possible that metadata PDU was missed in cf_cfdp.c, or that -** it was re-sent. This function checks if it was already processed, -** and if not, handles it. If there was a temp file opened due to -** missed metadata pdu, it will move the file to the correct -** destination according to the metadata pdu. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_RecvMd + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_RecvMd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* it isn't an error to get another MD pdu, right? */ @@ -953,13 +864,14 @@ void CF_CFDP_R2_RecvMd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) err_out:; } -/************************************************************************/ -/** \brief R1 receive pdu processing. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R1_Recv + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R1_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { static const CF_CFDP_FileDirectiveDispatchTable_t r1_fdir_handlers = { @@ -972,13 +884,14 @@ void CF_CFDP_R1_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) CF_CFDP_R_DispatchRecv(t, ph, &substate_fns, CF_CFDP_R1_SubstateRecvFileData); } -/************************************************************************/ -/** \brief R2 receive pdu processing. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R2_Recv + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R2_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { static const CF_CFDP_FileDirectiveDispatchTable_t r2_fdir_handlers_normal = { @@ -999,13 +912,14 @@ void CF_CFDP_R2_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) CF_CFDP_R_DispatchRecv(t, ph, &substate_fns, CF_CFDP_R2_SubstateRecvFileData); } -/************************************************************************/ -/** \brief Cancel an R transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_Cancel + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R_Cancel(CF_Transaction_t *t) { /* for cancel, only need to send FIN if R2 */ @@ -1019,13 +933,14 @@ void CF_CFDP_R_Cancel(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief Sends an inactivity timer expired event to EVS. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_SendInactivityEvent + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R_SendInactivityEvent(CF_Transaction_t *t) { CFE_EVS_SendEvent(CF_EID_ERR_CFDP_R_INACT_TIMER, CFE_EVS_EventType_ERROR, "CF R%d(%u:%u): inactivity timer expired", @@ -1033,20 +948,14 @@ void CF_CFDP_R_SendInactivityEvent(CF_Transaction_t *t) ++CF_AppData.hk.channel_hk[t->chan_num].counters.fault.inactivity_timer; } -/************************************************************************/ -/** \brief Perform tick (time-based) processing for R transactions. -** -** \par Description -** This function is called on every transaction by the engine on -** every CF wakeup. This is where flags are checked to send ACK, -** NAK, and FIN. It checks for inactivity timer and processes the -** ack timer. The ack timer is what triggers re-sends of PDUs -** that require acknowledgment. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. cont is unused, so may be NULL -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_R_Tick + * + * Application-scope internal function + * See description in cf_cfdp_r.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_R_Tick(CF_Transaction_t *t, int *cont /* unused */) { /* Steven is not real happy with this function. There should be a better way to separate out diff --git a/fsw/src/cf_cfdp_r.h b/fsw/src/cf_cfdp_r.h index 952d17027..92a19545a 100644 --- a/fsw/src/cf_cfdp_r.h +++ b/fsw/src/cf_cfdp_r.h @@ -1,59 +1,399 @@ /************************************************************************ -** File: cf_cfdp_r.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ + +/** + * @file + * + * Implementation related to CFDP Receive File transactions + * + * This file contains various state handling routines for + * transactions which are receiving a file. + */ #ifndef CF_CFDP_R_H #define CF_CFDP_R_H #include "cf_cfdp.h" +/** + * @brief Argument for Gap Compute function + * + * This is used in conjunction with CF_CFDP_R2_GapCompute + */ typedef struct { - CF_Transaction_t *t; - CF_Logical_PduNak_t *nak; + CF_Transaction_t *t; /**< Current transaction being processed */ + CF_Logical_PduNak_t *nak; /**< Current NAK PDU contents */ } CF_GapComputeArgs_t; +/************************************************************************/ +/** @brief R1 receive pdu processing. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_R1_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief R2 receive pdu processing. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_R2_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Perform tick (time-based) processing for R transactions. + * + * @par Description + * This function is called on every transaction by the engine on + * every CF wakeup. This is where flags are checked to send ACK, + * NAK, and FIN. It checks for inactivity timer and processes the + * ack timer. The ack timer is what triggers re-sends of PDUs + * that require acknowledgment. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. cont is unused, so may be NULL + * + * @param t Pointer to the transaction object + * @param cont Ignored/Unused + * + */ void CF_CFDP_R_Tick(CF_Transaction_t *t, int *cont); + +/************************************************************************/ +/** @brief Cancel an R transaction. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_R_Cancel(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Initialize a transaction structure for R. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_R_Init(CF_Transaction_t *t); +/************************************************************************/ +/** @brief Helper function to store condition code set send_fin flag. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param cc Condition Code value to set within transaction + */ void CF_CFDP_R2_SetCc(CF_Transaction_t *t, CF_CFDP_ConditionCode_t cc); + +/************************************************************************/ +/** @brief CFDP R1 transaction reset function. + * + * @par Description + * All R transactions use this call to indicate the transaction + * state can be returned to the system. While this function currently + * only calls CF_CFDP_ResetTransaction(), it is here as a placeholder. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_R1_Reset(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief CFDP R2 transaction reset function. + * + * @par Description + * Handles reset logic for R2, then calls R1 reset logic. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_R2_Reset(CF_Transaction_t *t); -int CF_CFDP_R_CheckCrc(CF_Transaction_t *t, uint32 expected_crc); + +/************************************************************************/ +/** @brief Checks that the transaction file's CRC matches expected. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * + * @retval 0 on CRC match, otherwise error. + * + * + * @param t Pointer to the transaction object + */ +int CF_CFDP_R_CheckCrc(CF_Transaction_t *t, uint32 expected_crc); + +/************************************************************************/ +/** @brief Checks R2 transaction state for transaction completion status. + * + * @par Description + * This function is called anywhere there's a desire to know if the + * transaction has completed. It may trigger other actions by setting + * flags to be handled during tick processing. In order for a + * transaction to be complete, it must have had its meta-data PDU + * received, the EOF must have been received, and there must be + * no gaps in the file. EOF is not checked in this function, because + * it's only called from functions after EOF is received. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param ok_to_send_nak If set to 0, supresses sending of a NAK packet + */ void CF_CFDP_R2_Complete(CF_Transaction_t *t, int ok_to_send_nak); -int CF_CFDP_R_ProcessFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); -int CF_CFDP_R_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Process a filedata PDU on a transaction. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * + * @retval 0 on success. Returns anything else on error. + * + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ +int CF_CFDP_R_ProcessFd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Processing receive EOF common functionality for R1/R2. + * + * @par Description + * This function is used for both R1 and R2 eof receive. It calls + * the unmarshaling function and then checks known transaction + * data against the PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * + * @retval 0 on success. Returns anything else on error. + * + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ +int CF_CFDP_R_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Process receive EOF for R1. + * + * @par Description + * Only need to confirm crc for R1. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * + * @retval 0 on success. Returns anything else on error. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + * + */ void CF_CFDP_R1_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Process receive EOF for R2. + * + * @par Description + * For R2, need to trigger the send of EOF-ACK and then call the + * check complete function which will either send NAK or FIN. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * + * @retval 0 on success. Returns anything else on error. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + * + */ void CF_CFDP_R2_SubstateRecvEof(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Process received file data for R1. + * + * @par Description + * For R1, only need to digest the CRC. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_R1_SubstateRecvFileData(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Process received file data for R2. + * + * @par Description + * For R2, the CRC is checked after the whole file is received + * since there may be gaps. Instead, insert file received range + * data into chunks. Once NAK has been received, this function + * always checks for completion. This function also re-arms + * the ack timer. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_R2_SubstateRecvFileData(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Loads a single NAK segment request. + * + * @par Description + * This is a function callback from CF_ChunkList_ComputeGaps(). + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. c must not be NULL. opaque must not be NULL. + * + * @retval 0 on success. Returns anything else on error. + * + * @param chunks Not used, required for compatibility with CF_ChunkList_ComputeGaps + * @param c Pointer to a single chunk information + * @param opaque Pointer to a CF_GapComputeArgs_t object (passed via CF_ChunkList_ComputeGaps) + */ void CF_CFDP_R2_GapCompute(const CF_ChunkList_t *chunks, const CF_Chunk_t *c, void *opaque); -int CF_CFDP_R_SubstateSendNak(CF_Transaction_t *t); -int CF_CFDP_R2_CalcCrcChunk(CF_Transaction_t *t); -int CF_CFDP_R2_SubstateSendFin(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Send a NAK pdu for R2. + * + * @par Description + * NAK pdu is sent when there are gaps in the received data. The + * chunks class tracks this and generates the nak pdu by calculating + * gaps internally and calling CF_CFDP_R2_GapCompute(). There is a special + * case where if a metadata pdu has not been received, then a nak + * packet will be sent to request another. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @retval 0 on success. Returns anything else on error. + * + * @param t Pointer to the transaction object + */ +int CF_CFDP_R_SubstateSendNak(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Calculate up to the configured amount of bytes of CRC. + * + * @par Description + * The configuration table has a number of bytes to calculate per + * transaction per wakeup. At each wakeup, the file is read and + * this number of bytes are calculated. This function will set + * the checksum error condition code if the final crc does not match. + * + * @par PTFO + * Increase throughput by consuming all crc bytes per wakeup in + * transaction-order. This would require a change to the meaning + * of the value in the configuration table. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @retval 0 on completion + * @retval -1 on non-completion. Error status is stored in condition code. + * + */ +int CF_CFDP_R2_CalcCrcChunk(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Send a FIN pdu. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @retval 0 on success. Returns anything else on error. + * + * @param t Pointer to the transaction object + * + */ +int CF_CFDP_R2_SubstateSendFin(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Process receive FIN-ACK pdu. + * + * @par Description + * This is the end of an R2 transaction. Simply reset the transaction + * state. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_R2_Recv_fin_ack(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Process receive metadata pdu for R2. + * + * @par Description + * It's possible that metadata PDU was missed in cf_cfdp.c, or that + * it was re-sent. This function checks if it was already processed, + * and if not, handles it. If there was a temp file opened due to + * missed metadata pdu, it will move the file to the correct + * destination according to the metadata pdu. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_R2_RecvMd(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Sends an inactivity timer expired event to EVS. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_R_SendInactivityEvent(CF_Transaction_t *t); #endif /* CF_CFDP_R_H */ diff --git a/fsw/src/cf_cfdp_s.c b/fsw/src/cf_cfdp_s.c index 71e0bfeb8..294baf01e 100644 --- a/fsw/src/cf_cfdp_s.c +++ b/fsw/src/cf_cfdp_s.c @@ -1,30 +1,30 @@ /************************************************************************ -** File: cf_cfdp_s.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application CFDP send logic source file -** -** Handles all CFDP engine functionality specific to TX transactions. -** -** -** -*************************************************************************/ + * File: cf_cfdp_s.c + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application CFDP send logic source file + * + * Handles all CFDP engine functionality specific to TX transactions. + */ #include "cfe.h" #include "cf_verify.h" @@ -41,36 +41,27 @@ #include #include "cf_assert.h" -/************************************************************************/ -/** \brief CFDP S1 transaction reset function. -** -** \par Description -** All S transactions use this call to indicate the transaction -** state can be returned to the system. While this function currently -** only calls CF_CFDP_ResetTransaction(), it is here as a placeholder. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_Reset + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ static inline void CF_CFDP_S_Reset(CF_Transaction_t *t) { CF_CFDP_ResetTransaction(t, 1); } -/************************************************************************/ -/** \brief Send an eof pdu. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retcode CF_SendRet_SUCCESS on success. \endcode -** \retcode CF_SendRet_NO_MSG if message buffer cannot be obtained. \endcode -** \retcode CF_SendRet_ERROR if an error occurred while building the packet. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_SendEof + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_SendRet_t CF_CFDP_S_SendEof(CF_Transaction_t *t) { if (!t->flags.com.crc_calc) @@ -81,13 +72,14 @@ CF_SendRet_t CF_CFDP_S_SendEof(CF_Transaction_t *t) return CF_CFDP_SendEof(t); } -/************************************************************************/ -/** \brief Sends an eof for S1. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S1_SubstateSendEof + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S1_SubstateSendEof(CF_Transaction_t *t) { /* this looks weird, but the idea is we want to reset the transaction if some error occurs while sending @@ -99,13 +91,14 @@ void CF_CFDP_S1_SubstateSendEof(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief Triggers tick processing to send an EOF and wait for EOF-ACK for S2 -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_SubstateSendEof + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_SubstateSendEof(CF_Transaction_t *t) { t->state_data.s.sub_state = CF_TxSubState_WAIT_FOR_EOF_ACK; @@ -118,23 +111,14 @@ void CF_CFDP_S2_SubstateSendEof(CF_Transaction_t *t) CF_InsertSortPrio(t, CF_QueueIdx_TXW); } -/************************************************************************/ -/** \brief Helper function to populate the pdu with file data and send it. -** -** \par Description -** This function checks the file offset cache and if the desired -** location is where the file offset is, it can skip a seek() call. -** The file is read into the filedata pdu and then the pdu is sent. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt The number of bytes sent in the file data PDU. \endcode -** \endreturns -** -*************************************************************************/ -/* if bytes_to_read is 0, then read max possible */ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_SendFileData + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_CFDP_S_SendFileData(CF_Transaction_t *t, uint32 foffs, uint32 bytes_to_read, uint8 calc_crc) { int32 ret = -1; @@ -244,22 +228,14 @@ int32 CF_CFDP_S_SendFileData(CF_Transaction_t *t, uint32 foffs, uint32 bytes_to_ return ret; } -/************************************************************************/ -/** \brief Standard state function to send the next file data PDU for active transaction. -** -** \par Description -** During the transfer of active transaction file data pdus, the file -** offset is saved. This function sends the next chunk of data. If -** the file offset equals the file size, then transition to the EOF -** state. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ -/* regular filedata send - * based on t->foffs for current offset - * checks for EOF and changes state if necessary */ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_SubstateSendFileData + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S_SubstateSendFileData(CF_Transaction_t *t) { int32 bytes_processed = CF_CFDP_S_SendFileData(t, t->foffs, (t->fsize - t->foffs), 1); @@ -285,21 +261,14 @@ void CF_CFDP_S_SubstateSendFileData(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief Respond to a nak by sending filedata pdus as response. -** -** \par Description -** Checks to see if a metadata pdu or filedata re-transmits must -** occur. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt 0 if no NAK processed. 1 if NAK processed. <0 if error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_CheckAndRespondNak + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CFDP_S_CheckAndRespondNak(CF_Transaction_t *t) { const CF_Chunk_t *c; @@ -347,17 +316,14 @@ int CF_CFDP_S_CheckAndRespondNak(CF_Transaction_t *t) return ret; } -/************************************************************************/ -/** \brief Send filedata handling for S2. -** -** \par Description -** S2 will either respond to a NAK by sending retransmits, or in -** absence of a NAK, it will send more of the original file data. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_SubstateSendFileData + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_SubstateSendFileData(CF_Transaction_t *t) { int ret = CF_CFDP_S_CheckAndRespondNak(t); @@ -376,17 +342,14 @@ void CF_CFDP_S2_SubstateSendFileData(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief Send metadata PDU. -** -** \par Description -** Construct and send a metadata PDU. This function determines the -** size of the file to put in the metadata PDU. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_SubstateSendMetadata + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S_SubstateSendMetadata(CF_Transaction_t *t) { int status; @@ -466,13 +429,14 @@ void CF_CFDP_S_SubstateSendMetadata(CF_Transaction_t *t) CF_CFDP_S_Reset(t); } -/************************************************************************/ -/** \brief Send FIN-ACK packet for S2. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_SubstateSendFinAck + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S_SubstateSendFinAck(CF_Transaction_t *t) { /* if send, or error, reset. if no message, try again next cycle */ @@ -483,13 +447,14 @@ void CF_CFDP_S_SubstateSendFinAck(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief A fin was received before file complete, so abandon the transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_EarlyFin + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_EarlyFin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* received early fin, so just cancel */ @@ -499,31 +464,28 @@ void CF_CFDP_S2_EarlyFin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) CF_CFDP_S_Reset(t); } -/************************************************************************/ -/** \brief S2 received FIN, so set flag to send FIN-ACK. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_Fin + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_Fin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { t->state_data.s.s2.fin_cc = ph->int_header.fin.cc; t->state_data.s.sub_state = CF_TxSubState_SEND_FIN_ACK; } -/************************************************************************/ -/** \brief S2 NAK pdu received handling. -** -** \par Description -** Stores the segment requests from the NAK packet in the chunks -** structure. These can be used to generate re-transmit filedata -** PDUs. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_Nak + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_Nak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { const CF_Logical_SegmentRequest_t *sr; @@ -583,30 +545,28 @@ void CF_CFDP_S2_Nak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) } } -/************************************************************************/ -/** \brief S2 NAK handling but with arming the NAK timer. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_Nak_Arm + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_Nak_Arm(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { CF_CFDP_ArmAckTimer(t); CF_CFDP_S2_Nak(t, ph); } -/************************************************************************/ -/** \brief S2 received ack pdu in wait for EOF-ACK state. -** -** \par Description -** This function will trigger a state transition to CF_TxSubState_WAIT_FOR_FIN, -** which waits for a FIN pdu. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. ph must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_WaitForEofAck + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_WaitForEofAck(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { if (!CF_CFDP_RecvAck(t, ph)) @@ -631,13 +591,14 @@ void CF_CFDP_S2_WaitForEofAck(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) } } -/************************************************************************/ -/** \brief S1 receive pdu processing. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S1_Recv + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S1_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { /* s1 doesn't need to receive anything */ @@ -645,13 +606,14 @@ void CF_CFDP_S1_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) CF_CFDP_S_DispatchRecv(t, ph, &substate_fns); } -/************************************************************************/ -/** \brief S2 receive pdu processing. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_Recv + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) { static const CF_CFDP_FileDirectiveDispatchTable_t s2_meta = {.fdirective = { @@ -682,13 +644,14 @@ void CF_CFDP_S2_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph) CF_CFDP_S_DispatchRecv(t, ph, &substate_fns); } -/************************************************************************/ -/** \brief S1 dispatch function. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S1_Tx + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S1_Tx(CF_Transaction_t *t) { static const CF_CFDP_S_SubstateSendDispatchTable_t substate_fns = { @@ -701,13 +664,14 @@ void CF_CFDP_S1_Tx(CF_Transaction_t *t) CF_CFDP_S_DispatchTransmit(t, &substate_fns); } -/************************************************************************/ -/** \brief S2 dispatch function. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S2_Tx + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S2_Tx(CF_Transaction_t *t) { static const CF_CFDP_S_SubstateSendDispatchTable_t substate_fns = { @@ -720,13 +684,14 @@ void CF_CFDP_S2_Tx(CF_Transaction_t *t) CF_CFDP_S_DispatchTransmit(t, &substate_fns); } -/************************************************************************/ -/** \brief Cancel an S transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_Cancel + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S_Cancel(CF_Transaction_t *t) { if (t->state_data.s.sub_state < CF_TxSubState_EOF) @@ -736,19 +701,14 @@ void CF_CFDP_S_Cancel(CF_Transaction_t *t) } } -/************************************************************************/ -/** \brief Perform tick (time-based) processing for S transactions. -** -** \par Description -** This function is called on every transaction by the engine on -** every CF wakeup. This is where flags are checked to send EOF or -** FIN-ACK. If nothing else is sent, it checks to see if a NAK -** retransmit must occur. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. cont is unused, so may be NULL -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_Tick + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S_Tick(CF_Transaction_t *t, int *cont /* unused */) { /* Steven is not real happy with this function. There should be a better way to separate out @@ -819,18 +779,14 @@ void CF_CFDP_S_Tick(CF_Transaction_t *t, int *cont /* unused */) err_out:; } -/************************************************************************/ -/** \brief Perform NAK response for TX transactions -** -** \par Description -** This function is called at tick processing time to send pending -** NAK responses. It indicates "cont" is 1 if there are more responses -** left to send. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. cont must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_S_Tick_Nak + * + * Application-scope internal function + * See description in cf_cfdp_s.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_S_Tick_Nak(CF_Transaction_t *t, int *cont) { int ret = CF_CFDP_S_CheckAndRespondNak(t); diff --git a/fsw/src/cf_cfdp_s.h b/fsw/src/cf_cfdp_s.h index 9a742a8bb..25bdb4ac7 100644 --- a/fsw/src/cf_cfdp_s.h +++ b/fsw/src/cf_cfdp_s.h @@ -1,62 +1,317 @@ /************************************************************************ -** File: cf_cfdp.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application cfdp engine and packet parsing header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * Implementation related to CFDP Send File transactions + * + * This file contains various state handling routines for + * transactions which are sending a file. + */ #ifndef CF_CFDP_S_H #define CF_CFDP_S_H #include "cf_cfdp_types.h" -/* Engine functional dispatch. These are all implemented in cf_cfdp_r.c or cf_cfdp_s.c */ +/************************************************************************/ +/** @brief S1 receive pdu processing. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_S1_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief S2 receive pdu processing. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ void CF_CFDP_S2_Recv(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief S1 dispatch function. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_S1_Tx(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief S2 dispatch function. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_S2_Tx(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Perform tick (time-based) processing for S transactions. + * + * @par Description + * This function is called on every transaction by the engine on + * every CF wakeup. This is where flags are checked to send EOF or + * FIN-ACK. If nothing else is sent, it checks to see if a NAK + * retransmit must occur. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. cont is unused, so may be NULL + * + * @param t Pointer to the transaction object + * @param cont Unused, exists for compatibility with tick processor + */ void CF_CFDP_S_Tick(CF_Transaction_t *t, int *cont); + +/************************************************************************/ +/** @brief Perform NAK response for TX transactions + * + * @par Description + * This function is called at tick processing time to send pending + * NAK responses. It indicates "cont" is 1 if there are more responses + * left to send. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. cont must not be NULL. + * + * @param t Pointer to the transaction object + * @param cont Set to 1 if a nak was generated + */ void CF_CFDP_S_Tick_Nak(CF_Transaction_t *t, int *cont); + +/************************************************************************/ +/** @brief Cancel an S transaction. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_CFDP_S_Cancel(CF_Transaction_t *t); -/* Handler routines for send-file transactions */ -/* These are not called from outside this module, but are declared here so they can be unit tested */ +/*********************************************************************** + * + * Handler routines for send-file transactions + * These are not called from outside this module, but are declared here so they can be unit tested + * + ************************************************************************/ + +/************************************************************************/ +/** @brief Send an eof pdu. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @retval CF_SendRet_SUCCESS on success. + * @retval CF_SendRet_NO_MSG if message buffer cannot be obtained. + * @retval CF_SendRet_ERROR if an error occurred while building the packet. + * + * @param t Pointer to the transaction object + */ CF_SendRet_t CF_CFDP_S_SendEof(CF_Transaction_t *t); -void CF_CFDP_S1_SubstateSendEof(CF_Transaction_t *t); -void CF_CFDP_S2_SubstateSendEof(CF_Transaction_t *t); -int32 CF_CFDP_S_SendFileData(CF_Transaction_t *t, uint32 foffs, uint32 bytes_to_read, uint8 calc_crc); -void CF_CFDP_S_SubstateSendFileData(CF_Transaction_t *t); -int CF_CFDP_S_CheckAndRespondNak(CF_Transaction_t *t); -void CF_CFDP_S2_SubstateSendFileData(CF_Transaction_t *t); -void CF_CFDP_S_SubstateSendMetadata(CF_Transaction_t *t); -void CF_CFDP_S_SubstateSendFinAck(CF_Transaction_t *t); -void CF_CFDP_S2_EarlyFin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); -void CF_CFDP_S2_Fin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); -void CF_CFDP_S2_Nak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); -void CF_CFDP_S2_Nak_Arm(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); -void CF_CFDP_S2_WaitForEofAck(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); -#endif /* !CF_CFDP_S_H */ +/************************************************************************/ +/** @brief Sends an eof for S1. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ +void CF_CFDP_S1_SubstateSendEof(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Triggers tick processing to send an EOF and wait for EOF-ACK for S2 + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ +void CF_CFDP_S2_SubstateSendEof(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Helper function to populate the pdu with file data and send it. + * + * @par Description + * This function checks the file offset cache and if the desired + * location is where the file offset is, it can skip a seek() call. + * The file is read into the filedata pdu and then the pdu is sent. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @returns The number of bytes sent in the file data PDU, or negative value on error + * + * @param t Pointer to the transaction object + * @param foffs Position in file to send data from + * @param bytes_to_read Number of bytes to send (maximum) + * @param calc_crc Enable CRC/Checksum calculation + * + */ +int32 CF_CFDP_S_SendFileData(CF_Transaction_t *t, uint32 foffs, uint32 bytes_to_read, uint8 calc_crc); -#ifdef __cplusplus -static inline void CF_CFDP_S_Reset(CF_Transaction_t *t) -#endif +/************************************************************************/ +/** @brief Standard state function to send the next file data PDU for active transaction. + * + * @par Description + * During the transfer of active transaction file data pdus, the file + * offset is saved. This function sends the next chunk of data. If + * the file offset equals the file size, then transition to the EOF + * state. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ +void CF_CFDP_S_SubstateSendFileData(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Respond to a nak by sending filedata pdus as response. + * + * @par Description + * Checks to see if a metadata pdu or filedata re-transmits must + * occur. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @returns negative value if error. + * @retval 0 if no NAK processed. + * @retval 1 if NAK processed. + * + * @param t Pointer to the transaction object + */ +int CF_CFDP_S_CheckAndRespondNak(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Send filedata handling for S2. + * + * @par Description + * S2 will either respond to a NAK by sending retransmits, or in + * absence of a NAK, it will send more of the original file data. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ +void CF_CFDP_S2_SubstateSendFileData(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Send metadata PDU. + * + * @par Description + * Construct and send a metadata PDU. This function determines the + * size of the file to put in the metadata PDU. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ +void CF_CFDP_S_SubstateSendMetadata(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief Send FIN-ACK packet for S2. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ +void CF_CFDP_S_SubstateSendFinAck(CF_Transaction_t *t); + +/************************************************************************/ +/** @brief A fin was received before file complete, so abandon the transaction. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ +void CF_CFDP_S2_EarlyFin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief S2 received FIN, so set flag to send FIN-ACK. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ +void CF_CFDP_S2_Fin(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief S2 NAK pdu received handling. + * + * @par Description + * Stores the segment requests from the NAK packet in the chunks + * structure. These can be used to generate re-transmit filedata + * PDUs. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ +void CF_CFDP_S2_Nak(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief S2 NAK handling but with arming the NAK timer. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ +void CF_CFDP_S2_Nak_Arm(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief S2 received ack pdu in wait for EOF-ACK state. + * + * @par Description + * This function will trigger a state transition to CF_TxSubState_WAIT_FOR_FIN, + * which waits for a FIN pdu. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. ph must not be NULL. + * + * @param t Pointer to the transaction object + * @param ph Pointer to the PDU information + */ +void CF_CFDP_S2_WaitForEofAck(CF_Transaction_t *t, CF_Logical_PduBuffer_t *ph); + +#endif /* !CF_CFDP_S_H */ diff --git a/fsw/src/cf_cfdp_sbintf.c b/fsw/src/cf_cfdp_sbintf.c index ca695b100..4b804452c 100644 --- a/fsw/src/cf_cfdp_sbintf.c +++ b/fsw/src/cf_cfdp_sbintf.c @@ -1,23 +1,23 @@ /************************************************************************ -** File: cf_cfdp_sbintf.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -*************************************************************************/ + * File: cf_cfdp_sbintf.c + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ /** * @file @@ -53,25 +53,14 @@ #include #include "cf_assert.h" -/************************************************************************/ -/** \brief Obtain a message buffer to construct a PDU inside. -** -** \par Description -** This performs the handshaking via semaphore with the consumer -** of the PDU. If the semaphore can be obtained, a software bus -** buffer is obtained and it is returned. If the semaphore is -** unavailable, then the current transaction is remembered for next -** engine cycle. If silent is true, then the event message is not -** printed in the case of no buffer available. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt Pointer to a CF_Logical_PduBuffer_t on success. Otherwise NULL. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_MsgOutGet + * + * Application-scope internal function + * See description in cf_cfdp_sbintf.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_Logical_PduBuffer_t *CF_CFDP_MsgOutGet(const CF_Transaction_t *t, bool silent) { /* if channel is frozen, do not take message */ @@ -136,13 +125,14 @@ CF_Logical_PduBuffer_t *CF_CFDP_MsgOutGet(const CF_Transaction_t *t, bool silent return ret; } -/************************************************************************/ -/** \brief Sends the current output buffer via the software bus. -** -** \par Assumptions, External Events, and Notes: -** The PDU in the output buffer is ready to transmit. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_Send + * + * Application-scope internal function + * See description in cf_cfdp_sbintf.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_Send(uint8 chan_num, const CF_Logical_PduBuffer_t *ph) { CFE_MSG_Size_t sb_msgsize; @@ -164,13 +154,14 @@ void CF_CFDP_Send(uint8 chan_num, const CF_Logical_PduBuffer_t *ph) CF_AppData.engine.out.msg = NULL; } -/************************************************************************/ -/** \brief Process received message on channel PDU input pipe. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_ReceiveMessage + * + * Application-scope internal function + * See description in cf_cfdp_sbintf.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_ReceiveMessage(CF_Channel_t *c) { CF_Transaction_t *t; /* initialized below */ diff --git a/fsw/src/cf_cfdp_sbintf.h b/fsw/src/cf_cfdp_sbintf.h index e254d2d46..9ea965891 100644 --- a/fsw/src/cf_cfdp_sbintf.h +++ b/fsw/src/cf_cfdp_sbintf.h @@ -1,32 +1,79 @@ /************************************************************************ -** File: cf_cfdp_sbintf.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * This is the interface to the CFE Software Bus for PDU transmit/recv. + * + * It may serve as a future point of abstraction to interface with message + * passing interfaces other than the CFE software bus, if necessary. + */ #ifndef CF_CFDP_SBINTF_H #define CF_CFDP_SBINTF_H #include "cf_cfdp_types.h" +/************************************************************************/ +/** @brief Obtain a message buffer to construct a PDU inside. + * + * @par Description + * This performs the handshaking via semaphore with the consumer + * of the PDU. If the semaphore can be obtained, a software bus + * buffer is obtained and it is returned. If the semaphore is + * unavailable, then the current transaction is remembered for next + * engine cycle. If silent is true, then the event message is not + * printed in the case of no buffer available. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param silent If true, suppresses error events if no message can be allocated + * + * @returns Pointer to a CF_Logical_PduBuffer_t on success. + * @retval NULL on error + */ CF_Logical_PduBuffer_t *CF_CFDP_MsgOutGet(const CF_Transaction_t *t, bool silent); -void CF_CFDP_Send(uint8 chan_num, const CF_Logical_PduBuffer_t *ph); -void CF_CFDP_ReceiveMessage(CF_Channel_t *c); + +/************************************************************************/ +/** @brief Sends the current output buffer via the software bus. + * + * @par Assumptions, External Events, and Notes: + * The PDU in the output buffer is ready to transmit. + * + * @param chan_num Channel number for statistics/accounting purposes + * @param ph Pointer to PDU buffer to send + * + */ +void CF_CFDP_Send(uint8 chan_num, const CF_Logical_PduBuffer_t *ph); + +/************************************************************************/ +/** @brief Process received message on channel PDU input pipe. + * + * @par Assumptions, External Events, and Notes: + * c must be a member of the array within the CF_AppData global object + * + * @param c Channel to receive message on + * + */ +void CF_CFDP_ReceiveMessage(CF_Channel_t *c); #endif /* !CF_CFDP_SBINTF_H */ diff --git a/fsw/src/cf_cfdp_types.h b/fsw/src/cf_cfdp_types.h index 1a111701f..53067de51 100644 --- a/fsw/src/cf_cfdp_types.h +++ b/fsw/src/cf_cfdp_types.h @@ -1,28 +1,32 @@ /************************************************************************ -** File: cf_cfdp_types.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application cfdp engine and packet parsing header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * Macros and data types used across the CF application + * + * @note Functions should not be declared in this file. This should + * be limited to shared macros and data types only. For unit testing, + * functions should be declared only in a header file with the same name + * as the C file that defines that function. + */ #ifndef CF_CFDP_TYPES_H #define CF_CFDP_TYPES_H @@ -36,27 +40,46 @@ #include "cf_crc.h" #include "cf_codec.h" +/** + * @brief Maximum possible number of transactions that may exist on a single CF channel + */ #define CF_NUM_TRANSACTIONS_PER_CHANNEL \ (CF_MAX_COMMANDED_PLAYBACK_FILES_PER_CHAN + CF_MAX_SIMULTANEOUS_RX + \ ((CF_MAX_POLLING_DIR_PER_CHAN + CF_MAX_COMMANDED_PLAYBACK_DIRECTORIES_PER_CHAN) * \ CF_NUM_TRANSACTIONS_PER_PLAYBACK)) + +/** + * @brief Maximum possible number of transactions that may exist in the CF application + */ #define CF_NUM_TRANSACTIONS (CF_NUM_CHANNELS * CF_NUM_TRANSACTIONS_PER_CHANNEL) +/** + * @brief Maximum possible number of history entries that may exist in the CF application + */ #define CF_NUM_HISTORIES (CF_NUM_CHANNELS * CF_NUM_HISTORIES_PER_CHANNEL) +/** + * @brief Maximum possible number of chunk entries that may exist in the CF application + */ #define CF_NUM_CHUNKS_ALL_CHANNELS (CF_TOTAL_CHUNKS * CF_NUM_TRANSACTIONS_PER_CHANNEL) +/** + * @brief High-level state of a transaction + */ typedef enum { - CF_TxnState_IDLE = 0, - CF_TxnState_R1 = 1, - CF_TxnState_S1 = 2, - CF_TxnState_R2 = 3, - CF_TxnState_S2 = 4, - CF_TxnState_DROP = 5, /* class 1 received file data without metadata, no file info, so drop */ - CF_TxnState_INVALID = 6 + CF_TxnState_IDLE = 0, /**< State assigned to a newly allocated transaction object */ + CF_TxnState_R1 = 1, /**< Recieve file as class 1 */ + CF_TxnState_S1 = 2, /**< Send file as class 1 */ + CF_TxnState_R2 = 3, /**< Receive file as class 2 */ + CF_TxnState_S2 = 4, /**< Send file as class 2 */ + CF_TxnState_DROP = 5, /**< State where all PDUs are dropped */ + CF_TxnState_INVALID = 6 /**< Marker value for the highest possible state number */ } CF_TxnState_t; +/** + * @brief Sub-state of a send file transaction + */ typedef enum { CF_TxSubState_METADATA = 0, @@ -68,6 +91,9 @@ typedef enum CF_TxSubState_NUM_STATES = 6 } CF_TxSubState_t; +/** + * @brief Sub-state of a receive file transaction + */ typedef enum { CF_RxSubState_FILEDATA = 0, @@ -76,6 +102,9 @@ typedef enum CF_RxSubState_NUM_STATES = 3, } CF_RxSubState_t; +/** + * @brief Special return values from some receive PDU processing functions + */ typedef enum { CF_RxEofRet_SUCCESS = 0, @@ -84,12 +113,23 @@ typedef enum CF_RxEofRet_INVALID = 3, } CF_RxEofRet_t; -typedef struct +/** + * @brief Cache of source and destination filename + * + * This pairs a source and destination file name together + * to be retained for future reference in the transaction/history + */ +typedef struct CF_TxnFilenames { char src_filename[CF_FILENAME_MAX_LEN]; char dst_filename[CF_FILENAME_MAX_LEN]; } CF_TxnFilenames_t; +/** + * @brief Direction identifier + * + * Differentiates between send and receive history entries + */ typedef enum { CF_Direction_RX = 0, @@ -97,23 +137,38 @@ typedef enum CF_Direction_NUM = 2, } CF_Direction_t; +/** + * @brief CF History entry + * + * Records CF app operations for future reference + */ typedef struct CF_History { - CF_TxnFilenames_t fnames; - CF_CListNode_t cl_node; - CF_Direction_t dir; - CF_CFDP_ConditionCode_t cc; - CF_EntityId_t src_eid; /* src_eid is always the source eid */ - CF_EntityId_t peer_eid; /* peer_eid is always the "other guy", which is the same src_eid for RX */ - CF_TransactionSeq_t seq_num; /* stays constant for entire transfer */ + CF_TxnFilenames_t fnames; /**< file names associated with this history entry */ + CF_CListNode_t cl_node; /**< for connection to a CList */ + CF_Direction_t dir; /**< direction of this history entry */ + CF_CFDP_ConditionCode_t cc; /**< final condition code of operation */ + CF_EntityId_t src_eid; /**< the source eid of the transaction */ + CF_EntityId_t peer_eid; /**< peer_eid is always the "other guy", which is the same src_eid for RX */ + CF_TransactionSeq_t seq_num; /**< transaction identifier, stays constant for entire transfer */ } CF_History_t; +/** + * @brief Wrapper around a CF_ChunkList_t object + * + * This allows a CF_ChunkList_t to be stored within a CList data storage structure + */ typedef struct CF_ChunkWrapper { CF_ChunkList_t chunks; CF_CListNode_t cl_node; } CF_ChunkWrapper_t; +/** + * @brief CF Playback entry + * + * Keeps the state of CF playback requests + */ typedef struct CF_Playback { uint32 dir_id; @@ -129,6 +184,11 @@ typedef struct CF_Playback bool counted; } CF_Playback_t; +/** + * @brief CF Poll entry + * + * Keeps the state of CF directory polling + */ typedef struct CF_Poll { CF_Playback_t pb; @@ -136,12 +196,18 @@ typedef struct CF_Poll bool timer_set; } CF_Poll_t; +/** + * @brief Data specific to a class 2 send file transaction + */ typedef struct CF_TxS2_Data { uint8 fin_cc; /* remember the cc in the received fin pdu to echo in eof-fin */ uint8 acknak_count; } CF_TxS2_Data_t; +/** + * @brief Data specific to a send file transaction + */ typedef struct CF_TxState_Data { CF_TxSubState_t sub_state; @@ -150,6 +216,9 @@ typedef struct CF_TxState_Data CF_TxS2_Data_t s2; } CF_TxState_Data_t; +/** + * @brief Data specific to a class 2 receive file transaction + */ typedef struct CF_RxS2_Data { uint32 eof_crc; @@ -161,6 +230,9 @@ typedef struct CF_RxS2_Data uint8 acknak_count; } CF_RxS2_Data_t; +/** + * @brief Data specific to a receive file transaction + */ typedef struct CF_RxState_Data { CF_RxSubState_t sub_state; @@ -169,6 +241,9 @@ typedef struct CF_RxState_Data CF_RxS2_Data_t r2; } CF_RxState_Data_t; +/** + * @brief Data that applies to all types of transactions + */ typedef struct CF_Flags_Common { uint8 q_index; /* which Q is this in? */ @@ -178,6 +253,9 @@ typedef struct CF_Flags_Common bool crc_calc; } CF_Flags_Common_t; +/** + * @brief Flags that apply to receive transactions + */ typedef struct CF_Flags_Rx { CF_Flags_Common_t com; @@ -192,6 +270,9 @@ typedef struct CF_Flags_Rx bool fd_nak_sent; /* latches that at least one nak has been sent for file data */ } CF_Flags_Rx_t; +/** + * @brief Flags that apply to send transactions + */ typedef struct CF_Flags_Tx { CF_Flags_Common_t com; @@ -200,19 +281,30 @@ typedef struct CF_Flags_Tx bool cmd_tx; /* indicates transaction is commanded (ground) tx */ } CF_Flags_Tx_t; +/** + * @brief Summary of all possible transaction flags (tx and rx) + */ typedef union CF_StateFlags { - CF_Flags_Common_t com; - CF_Flags_Rx_t rx; - CF_Flags_Tx_t tx; + CF_Flags_Common_t com; /**< applies to all transactions */ + CF_Flags_Rx_t rx; /**< applies to only receive file transactions */ + CF_Flags_Tx_t tx; /**< applies to only send file transactions */ } CF_StateFlags_t; +/** + * @brief Summary of all possible transaction state information (tx and rx) + */ typedef union CF_StateData { - CF_TxState_Data_t s; - CF_RxState_Data_t r; + CF_TxState_Data_t s; /**< applies to only send file transactions */ + CF_RxState_Data_t r; /**< applies to only receive file transactions */ } CF_StateData_t; +/** + * @brief Transaction state object + * + * This keeps the state of CF file transactions + */ typedef struct CF_Transaction { CF_TxnState_t state; /* each engine is commanded to do something, which is the overall state */ @@ -246,6 +338,9 @@ typedef struct CF_Transaction } CF_Transaction_t; +/** + * @brief CF queue identifiers + */ typedef enum { CF_QueueIdx_PEND = 0, /* first one on this list is active */ @@ -258,6 +353,9 @@ typedef enum CF_QueueIdx_NUM = 7, } CF_QueueIdx_t; +/** + * @brief Identifies the type of timer tick being processed + */ typedef enum { CF_TickType_RX, @@ -266,6 +364,15 @@ typedef enum CF_TickType_NUM_TYPES } CF_TickType_t; +/** + * @brief Channel state object + * + * This keeps the state of CF channels + * + * Each CF channel has a separate transaction list, PDU throttle, playback, + * and poll state, as well as separate addresses on the underlying message + * transport (e.g. SB). + */ typedef struct CF_Channel { CF_CListNode_t *qs[CF_QueueIdx_NUM]; @@ -290,39 +397,74 @@ typedef struct CF_Channel /* NOTE: the use of CF_CFDP_PduHeader_t below is correct, but the CF_PduRecvMsg_t and CF_PduSendMsg_t * structures are both longer than these definitions. They are always backed by a buffer * of size CF_MAX_PDU_SIZE */ + +/** + * @brief PDU receive encapsulation structure + * + * This encapsulates a CFDP pdu into a format that is received over the software bus, + * adding "command" encapsulation (even though these are not really commands). + * + * @note this is only the definition of the header. In reality all messages are + * larger than this, up to CF_MAX_PDU_SIZE. + */ typedef struct CF_PduRecvMsg { - CFE_MSG_CommandHeader_t hdr; - CF_CFDP_PduHeader_t ph; + CFE_MSG_CommandHeader_t hdr; /**< software bus headers, not really used by CF */ + CF_CFDP_PduHeader_t ph; /**< Beginning of CFDP headers */ } CF_PduRecvMsg_t; +/** + * @brief PDU send encapsulation structure + * + * This encapsulates a CFDP pdu into a format that is sent over the software bus, + * adding "telemetry" encapsulation (even though these are not really telemetry items). + * + * @note this is only the definition of the header. In reality all messages are + * larger than this, up to CF_MAX_PDU_SIZE. + */ typedef struct CF_PduSendMsg { - CFE_MSG_TelemetryHeader_t hdr; - CF_CFDP_PduHeader_t ph; + CFE_MSG_TelemetryHeader_t hdr; /**< software bus headers, not really used by CF */ + CF_CFDP_PduHeader_t ph; /**< Beginning of CFDP headers */ } CF_PduSendMsg_t; +/** + * @brief CF engine output state + * + * Keeps the state of the current output PDU in the CF engine + */ typedef struct CF_Output { - CFE_SB_Buffer_t *msg; - CF_EncoderState_t encode; + CFE_SB_Buffer_t *msg; /**< Binary message to be sent to underlying transport */ + CF_EncoderState_t encode; /**< Encoding state (while building message) */ - /* Temporary R/W buffer for holding output PDUs while working with them */ + /** + * Temporary R/W buffer for holding output PDUs while working with them + */ CF_Logical_PduBuffer_t tx_pdudata; } CF_Output_t; +/** + * @brief CF engine input state + * + * Keeps the state of the current input PDU in the CF engine + */ typedef struct CF_Input { - CFE_SB_Buffer_t *msg; - CF_DecoderState_t decode; + CFE_SB_Buffer_t *msg; /**< Binary message received from underlying transport */ + CF_DecoderState_t decode; /**< Decoding state (while interpreting message) */ - /* Temporary R/W buffer for holding input PDUs while working with them */ + /** + * Temporary R/W buffer for holding input PDUs while working with them + */ CF_Logical_PduBuffer_t rx_pdudata; } CF_Input_t; -/* An engine represents a pairing to a local EID +/** + * @brief An engine represents a pairing to a local EID * - * Each engine can have at most CF_MAX_SIMULTANEOUS_TRANSACTIONS */ + * Each engine can have at most CF_MAX_SIMULTANEOUS_TRANSACTIONS + */ typedef struct CF_Engine { CF_TransactionSeq_t seq_num; /* keep track of the next sequence number to use for sends */ @@ -342,12 +484,15 @@ typedef struct CF_Engine uint8 enabled; } CF_Engine_t; +/** + * @brief Special return values from some send PDU processing functions + */ typedef enum { - CF_SendRet_SUCCESS = 0, - CF_SendRet_NO_MSG = 1, - CF_SendRet_ERROR = 2, /* the send itself failed */ - CF_SendRet_FAILURE = 3, /* generic failure message not relating to message send */ + CF_SendRet_SUCCESS = 0, /**< Successfully sent */ + CF_SendRet_NO_MSG = 1, /**< No send buffer available, throttling limit reached */ + CF_SendRet_ERROR = 2, /**< the send itself failed */ + CF_SendRet_FAILURE = 3, /**< generic failure message not relating to message send */ } CF_SendRet_t; #endif diff --git a/fsw/src/cf_chunk.c b/fsw/src/cf_chunk.c index 5dec9b75f..d2ca7c5b9 100644 --- a/fsw/src/cf_chunk.c +++ b/fsw/src/cf_chunk.c @@ -1,56 +1,49 @@ /************************************************************************ -** File: cf_chunk.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application chunks (sparse gap tracking) logic file -** -** This class handles the complexity of sparse gap tracking so that -** the CFDP engine doesn't need to worry about it. Information is given -** to the class and when needed calculations are made internally to -** help the engine build NAK packets. Received NAK segmnent requests -** are stored in this class as well and used for re-transmit processing. -** -** This is intended to be mostly a generic purpose class used by CF. -** -** -** -*************************************************************************/ - -/* Most of this was originally written by Stephen Newell stephen@sjnewell.com - * who wrote it responding to my asking him about the problem. He wrote it - * in C++ and I (Steven Seeger) ported it to C and fixed a couple bugs and - * added some stuff. - * - * This is a pretty generic implemenation of a solution to the problem of - * sparse gap tracking over a linear range. */ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application chunks (sparse gap tracking) logic file + * + * This class handles the complexity of sparse gap tracking so that + * the CFDP engine doesn't need to worry about it. Information is given + * to the class and when needed calculations are made internally to + * help the engine build NAK packets. Received NAK segmnent requests + * are stored in this class as well and used for re-transmit processing. + * + * This is intended to be mostly a generic purpose class used by CF. + */ + #include #include "cf_verify.h" #include "cf_assert.h" #include "cf_chunk.h" -/************************************************************************/ -/** \brief Erase a range of chunks. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_EraseRange + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_Chunks_EraseRange(CF_ChunkList_t *chunks, CF_ChunkIdx_t start, CF_ChunkIdx_t end) { CF_Assert(end >= start); @@ -61,13 +54,14 @@ void CF_Chunks_EraseRange(CF_ChunkList_t *chunks, CF_ChunkIdx_t start, CF_ChunkI } } -/************************************************************************/ -/** \brief Erase a single chunk. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_EraseChunk + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_Chunks_EraseChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t erase_index) { CF_Assert(chunks->count > 0); @@ -79,13 +73,14 @@ void CF_Chunks_EraseChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t erase_index) --chunks->count; } -/************************************************************************/ -/** \brief Insert a chunk before index_before. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. chunk must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_InsertChunk + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_Chunks_InsertChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t index_before, const CF_Chunk_t *chunk) { CF_Assert(chunks->count < chunks->max_chunks); @@ -101,20 +96,14 @@ void CF_Chunks_InsertChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t index_before, c ++chunks->count; } -/************************************************************************/ -/** \brief Finds where a chunk should be inserted in the chunks. -** -** \par Description -** This is a C version of std::lower_bound from C++ algorithms. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. chunk must not be NULL. -** -** \returns -** \retstmt Returns an index to the first chunk that is greater than or equal to the requested's offset. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_FindInsertPosition + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_ChunkIdx_t CF_Chunks_FindInsertPosition(CF_ChunkList_t *chunks, const CF_Chunk_t *chunk) { CF_ChunkIdx_t first = 0; @@ -141,17 +130,14 @@ CF_ChunkIdx_t CF_Chunks_FindInsertPosition(CF_ChunkList_t *chunks, const CF_Chun return first; } -/************************************************************************/ -/** \brief Possibly combines the given chunk with the previous chunk. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. chunk must not be NULL. -** -** \returns -** \retstmt Returns 1 if combined with another chunk; otherwise 0. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_CombinePrevious + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_Chunks_CombinePrevious(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk) { int ret = 0; @@ -176,17 +162,14 @@ int CF_Chunks_CombinePrevious(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_ return ret; } -/************************************************************************/ -/** \brief Possibly combines the given chunk with the next chunk. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. chunk must not be NULL. -** -** \returns -** \retstmt Returns 1 if combined with another chunk; otherwise 0. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_CombineNext + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_Chunks_CombineNext(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk) { /* check if not at the end */ @@ -238,17 +221,14 @@ int CF_Chunks_CombineNext(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chun return ret; } -/************************************************************************/ -/** \brief Finds the smallest size out of all chunks. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. -** -** \returns -** \retstmt The chunk index with the smallest size. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_FindSmallestSize + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_ChunkIdx_t CF_Chunks_FindSmallestSize(const CF_ChunkList_t *chunks) { CF_ChunkIdx_t i; @@ -265,17 +245,14 @@ CF_ChunkIdx_t CF_Chunks_FindSmallestSize(const CF_ChunkList_t *chunks) return smallest; } -/************************************************************************/ -/** \brief Insert a chunk. -** -** \par Description -** Finds the correct insertion point for a chunk. May combine with -** an existing chunk if contiguous. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. chunk must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Chunks_Insert + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_Chunks_Insert(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk) { int n = CF_Chunks_CombineNext(chunks, i, chunk); @@ -310,13 +287,14 @@ void CF_Chunks_Insert(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t } } -/************************************************************************/ -/** \brief Public function to add a chunk. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ChunkListAdd + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_ChunkListAdd(CF_ChunkList_t *chunks, CF_ChunkOffset_t offset, CF_ChunkSize_t size) { const CF_Chunk_t chunk = {offset, size}; @@ -339,18 +317,14 @@ void CF_ChunkListAdd(CF_ChunkList_t *chunks, CF_ChunkOffset_t offset, CF_ChunkSi } } -/************************************************************************/ -/** \brief Public function to remove some amount of size from the first chunk. -** -** \par Description -** This may remove the chunk entirely. This function is to satisfy the -** use-case where data is retrieved from the structure in-order and -** once consumed should be removed. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ChunkList_RemoveFromFirst + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_ChunkList_RemoveFromFirst(CF_ChunkList_t *chunks, CF_ChunkSize_t size) { CF_Chunk_t *c = &chunks->chunks[0]; /* front is always 0 */ @@ -371,30 +345,27 @@ void CF_ChunkList_RemoveFromFirst(CF_ChunkList_t *chunks, CF_ChunkSize_t size) } } -/************************************************************************/ -/** \brief Public function to remove some amount of size from the first chunk. -** -** \par Description -** This may remove the chunk entirely. This function is to satisfy the -** use-case where data is retrieved from the structure in-order and -** once consumed should be removed. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ChunkList_GetFirstChunk + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ const CF_Chunk_t *CF_ChunkList_GetFirstChunk(const CF_ChunkList_t *chunks) { return chunks->count ? &chunks->chunks[0] : NULL; } -/************************************************************************/ -/** \brief Initialize a chunks structure. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. chunks_mem must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ChunkListInit + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_ChunkListInit(CF_ChunkList_t *chunks, CF_ChunkIdx_t max_chunks, CF_Chunk_t *chunks_mem) { CF_Assert(max_chunks > 0); @@ -403,35 +374,28 @@ void CF_ChunkListInit(CF_ChunkList_t *chunks, CF_ChunkIdx_t max_chunks, CF_Chunk CF_ChunkListReset(chunks); } -/************************************************************************/ -/** \brief Resets a chunks structure. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ChunkListReset + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_ChunkListReset(CF_ChunkList_t *chunks) { chunks->count = 0; memset(chunks->chunks, 0, sizeof(*chunks->chunks) * chunks->max_chunks); } -/************************************************************************/ -/** \brief Compute gaps between chunks, and call a callback for each. -** -** \par Description -** This function walks over all chunks and computes the gaps between. -** It can exit early if the calculated gap start is larger than the -** desired total. -** -** \par Assumptions, External Events, and Notes: -** chunks must not be NULL. compute_gap_fn is a valid function address. -** -** \returns -** \retstmt The number of computed gaps. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ChunkList_ComputeGaps + * + * Application-scope internal function + * See description in cf_chunk.h for argument/return detail + * + *-----------------------------------------------------------------*/ uint32 CF_ChunkList_ComputeGaps(const CF_ChunkList_t *chunks, CF_ChunkIdx_t max_gaps, CF_ChunkSize_t total, CF_ChunkOffset_t start, CF_ChunkList_ComputeGapFn_t compute_gap_fn, void *opaque) { diff --git a/fsw/src/cf_chunk.h b/fsw/src/cf_chunk.h index 0ddb49803..41218b64c 100644 --- a/fsw/src/cf_chunk.h +++ b/fsw/src/cf_chunk.h @@ -1,28 +1,27 @@ /************************************************************************ -** File: cf_chunk.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application chunks (spare gap tracking) header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application chunks (spare gap tracking) header file + */ #ifndef CF_CHUNK_H #define CF_CHUNK_H @@ -33,22 +32,43 @@ typedef uint32 CF_ChunkIdx_t; typedef uint32 CF_ChunkOffset_t; typedef uint32 CF_ChunkSize_t; -/* I talked this over with a friend, Stephen Newell (stephen@sjnewell.com) and he wrote something in c++. - * I liked it, so converted it to C. Giving credit where it's due. */ - +/** + * @brief Pairs an offset with a size to identify a specific piece of a file + */ typedef struct CF_Chunk { - CF_ChunkOffset_t offset; - CF_ChunkSize_t size; + CF_ChunkOffset_t offset; /**< The start offset of the chunk within the file */ + CF_ChunkSize_t size; /**< The size of the chunk */ } CF_Chunk_t; +/** + * @brief A list of CF_Chunk_t pairs + * + * This list is ordered by chunk offset, from lowest to highest + */ typedef struct CF_ChunkList { - CF_ChunkIdx_t count; - CF_ChunkIdx_t max_chunks; - CF_Chunk_t *chunks; + CF_ChunkIdx_t count; /**< number of chunks currently in the array */ + CF_ChunkIdx_t max_chunks; /**< maximum number of chunks allowed in the list (allocation size) */ + CF_Chunk_t *chunks; /**< chunk list array */ } CF_ChunkList_t; +/** + * @brief Function for use with CF_ChunkList_ComputeGaps() + * + * @param cs Pointer to the CF_ChunkList_t object + * @param c Pointer to the chunk being currently processed + * @param opaque Opaque pointer passed through from initial call + */ +typedef void (*CF_ChunkList_ComputeGapFn_t)(const CF_ChunkList_t *cs, const CF_Chunk_t *c, void *opaque); + +/** + * @brief Selects the larger of the two passed-in offsets + * + * @param a First chunk offset + * @param b Second chunk offset + * @return the larger CF_ChunkOffset_t value + */ static inline CF_ChunkOffset_t CF_Chunk_MAX(CF_ChunkOffset_t a, CF_ChunkOffset_t b) { if (a > b) @@ -61,32 +81,227 @@ static inline CF_ChunkOffset_t CF_Chunk_MAX(CF_ChunkOffset_t a, CF_ChunkOffset_t } } +/************************************************************************/ +/** @brief Initialize a CF_ChunkList_t structure. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. chunks_mem must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object to initialize + * @param max_chunks Maximum number of entries in the chunks_mem array + * @param chunks_mem Array of CF_Chunk_t objects with length of max_chunks + */ void CF_ChunkListInit(CF_ChunkList_t *chunks, CF_ChunkIdx_t max_chunks, CF_Chunk_t *chunks_mem); + +/************************************************************************/ +/** @brief Public function to add a chunk. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param offset Offset of chunk to add + * @param size Size of chunk to add + */ void CF_ChunkListAdd(CF_ChunkList_t *chunks, CF_ChunkOffset_t offset, CF_ChunkSize_t size); + +/************************************************************************/ +/** @brief Resets a chunks structure. + * + * All chunks are removed from the list, but the max_chunks and chunk memory + * pointers are retained. This returns the chunk list to the same state as + * it was after the initial call to CF_ChunkListInit(). + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + */ void CF_ChunkListReset(CF_ChunkList_t *chunks); -/* CF_ChunkList_RemoveFromFirst - + +/************************************************************************/ +/** @brief Public function to remove some amount of size from the first chunk. + * + * @par Description + * This may remove the chunk entirely. This function is to satisfy the + * use-case where data is retrieved from the structure in-order and + * once consumed should be removed. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. * + * @note * Good computer science would have a generic remove function, but that's much more complex * than we need for the use case. We aren't trying to make chunks a general purpose * reusable module, so just take the simple case that we need. * - * Same applies for CF_ChunkList_GetFirstChunk() */ -void CF_ChunkList_RemoveFromFirst(CF_ChunkList_t *chunks, CF_ChunkSize_t size); + * @param chunks Pointer to CF_ChunkList_t object + * @param size Size to remove + */ +void CF_ChunkList_RemoveFromFirst(CF_ChunkList_t *chunks, CF_ChunkSize_t size); + +/************************************************************************/ +/** @brief Public function to get the entire first chunk from the list + * + * This returns the first chunk from the list, or NULL if the list is empty. + * + * @note The chunk remains on the list - this call does not consume or remove the chunk + * from the list. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. + * + * @returns Pointer to first chunk from the CF_ChunkList_t object + * @retval NULL if the list was empty + */ const CF_Chunk_t *CF_ChunkList_GetFirstChunk(const CF_ChunkList_t *chunks); -typedef void (*CF_ChunkList_ComputeGapFn_t)(const CF_ChunkList_t *cs, const CF_Chunk_t *c, void *opaque); -/* returns number of gaps, in case anyone cares about number of gaps */ +/************************************************************************/ +/** @brief Compute gaps between chunks, and call a callback for each. + * + * @par Description + * This function walks over all chunks and computes the gaps between. + * It can exit early if the calculated gap start is larger than the + * desired total. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. compute_gap_fn is a valid function address. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param max_gaps Maximum number of gaps to compute + * @param total Size of the entire file + * @param start Beginning offset for gap computation + * @param compute_gap_fn Callback function to be invoked for each gap + * @param opaque Opaque pointer to pass through to callback function + * + * @returns The number of computed gaps. + */ uint32 CF_ChunkList_ComputeGaps(const CF_ChunkList_t *chunks, CF_ChunkIdx_t max_gaps, CF_ChunkSize_t total, CF_ChunkOffset_t start, CF_ChunkList_ComputeGapFn_t compute_gap_fn, void *opaque); -/* internal functions which need to be unit-tested */ -void CF_Chunks_EraseRange(CF_ChunkList_t *chunks, CF_ChunkIdx_t start, CF_ChunkIdx_t end); -void CF_Chunks_EraseChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t erase_index); -void CF_Chunks_InsertChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t index_before, const CF_Chunk_t *chunk); +/************************************************************************/ +/** @brief Erase a range of chunks. + * + * @note This changes the chunk IDs of all chunks that follow + * Items in the list after the end item will be shifted/moved to close the gap. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param start Starting chunk ID to erase (inclusive) + * @param end Ending chunk ID (exclusive, this chunk will not be erased) + */ +void CF_Chunks_EraseRange(CF_ChunkList_t *chunks, CF_ChunkIdx_t start, CF_ChunkIdx_t end); + +/************************************************************************/ +/** @brief Erase a single chunk. + * + * @note This changes the chunk IDs of all chunks that follow + * Items in the list after the erase_index will be shifted/moved to close the gap. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param erase_index chunk ID to erase + */ +void CF_Chunks_EraseChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t erase_index); + +/************************************************************************/ +/** @brief Insert a chunk before index_before. + * + * @note This changes the chunk IDs of all chunks that follow + * Items in the list after the index_before will be shifted/moved to open a gap. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. chunk must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param index_before position to insert at - this becomes the ID of the inserted chunk + * @param chunk Chunk data to insert (copied) + */ +void CF_Chunks_InsertChunk(CF_ChunkList_t *chunks, CF_ChunkIdx_t index_before, const CF_Chunk_t *chunk); + +/************************************************************************/ +/** @brief Finds where a chunk should be inserted in the chunks. + * + * @par Description + * This is a C version of std::lower_bound from C++ algorithms. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. chunk must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param chunk Chunk data to insert + * + * @returns an index to the first chunk that is greater than or equal to the requested's offset. + * + */ CF_ChunkIdx_t CF_Chunks_FindInsertPosition(CF_ChunkList_t *chunks, const CF_Chunk_t *chunk); -int CF_Chunks_CombinePrevious(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk); -int CF_Chunks_CombineNext(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk); + +/************************************************************************/ +/** @brief Possibly combines the given chunk with the previous chunk. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. chunk must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param i Index of chunk to combine + * @param chunk Chunk data to combine + * + * @returns boolean code indicating if chunks were combined + * @retval 1 if combined with another chunk + * @retval 0 if not combined + * + */ +int CF_Chunks_CombinePrevious(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk); + +/************************************************************************/ +/** @brief Possibly combines the given chunk with the next chunk. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. chunk must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param i Index of chunk to combine + * @param chunk Chunk data to combine + * + * @returns boolean code indicating if chunks were combined + * @retval 1 if combined with another chunk + * @retval 0 if not combined + * + */ +int CF_Chunks_CombineNext(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk); + +/************************************************************************/ +/** @brief Finds the smallest size out of all chunks. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * + * @returns The chunk index with the smallest size. + * @retval 0 if the chunk list is empty + * + */ CF_ChunkIdx_t CF_Chunks_FindSmallestSize(const CF_ChunkList_t *chunks); -void CF_Chunks_Insert(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk); + +/************************************************************************/ +/** @brief Insert a chunk. + * + * @par Description + * Inserts the chunk at the specified location. May combine with + * an existing chunk if contiguous. + * + * @par Assumptions, External Events, and Notes: + * chunks must not be NULL. chunk must not be NULL. + * + * @param chunks Pointer to CF_ChunkList_t object + * @param i Position to insert chunk at + * @param chunk Chunk data to insert + */ +void CF_Chunks_Insert(CF_ChunkList_t *chunks, CF_ChunkIdx_t i, const CF_Chunk_t *chunk); #endif /* !CF_CHUNK_H */ diff --git a/fsw/src/cf_clist.c b/fsw/src/cf_clist.c index df333b3b9..1758450d8 100644 --- a/fsw/src/cf_clist.c +++ b/fsw/src/cf_clist.c @@ -1,58 +1,59 @@ /************************************************************************ -** File: cf_clist.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application circular list definition source file -** -** This is a circular doubly-linked list implementation. It is used for -** all data structures in CF. -** -** This file is intended to be a generic class that can be used in other apps. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application circular list definition source file + * + * This is a circular doubly-linked list implementation. It is used for + * all data structures in CF. + * + * This file is intended to be a generic class that can be used in other apps. + */ #include "cf_verify.h" #include "cf_clist.h" #include "cf_assert.h" -/************************************************************************/ -/** \brief Initialize a clist node. -** -** \par Assumptions, External Events, and Notes: -** node must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_InitNode + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CList_InitNode(CF_CListNode_t *node) { node->next = node; node->prev = node; } -/************************************************************************/ -/** \brief Insert the given node into the front of a list. -** -** \par Assumptions, External Events, and Notes: -** head must not be NULL. node must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_InsertFront + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CList_InsertFront(CF_CListNode_t **head, CF_CListNode_t *node) { CF_Assert(head); @@ -73,13 +74,14 @@ void CF_CList_InsertFront(CF_CListNode_t **head, CF_CListNode_t *node) *head = node; } -/************************************************************************/ -/** \brief Insert the given node into the back of a list. -** -** \par Assumptions, External Events, and Notes: -** head must not be NULL. node must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_InsertBack + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CList_InsertBack(CF_CListNode_t **head, CF_CListNode_t *node) { CF_Assert(head); @@ -102,17 +104,14 @@ void CF_CList_InsertBack(CF_CListNode_t **head, CF_CListNode_t *node) } } -/************************************************************************/ -/** \brief Remove the first node from a list and return it. -** -** \par Assumptions, External Events, and Notes: -** head must not be NULL. -** -** \returns -** \retstmt The first node (now removed) in the list; NULL if list was empty. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_Pop + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_CListNode_t *CF_CList_Pop(CF_CListNode_t **head) { CF_CListNode_t *ret; @@ -128,13 +127,14 @@ CF_CListNode_t *CF_CList_Pop(CF_CListNode_t **head) return ret; } -/************************************************************************/ -/** \brief Remove the given node from the list. -** -** \par Assumptions, External Events, and Notes: -** head must not be NULL. node must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_Remove + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CList_Remove(CF_CListNode_t **head, CF_CListNode_t *node) { CF_Assert(head); @@ -164,13 +164,14 @@ void CF_CList_Remove(CF_CListNode_t **head, CF_CListNode_t *node) CF_CList_InitNode(node); } -/************************************************************************/ -/** \brief Insert the given node into the last after the given start node. -** -** \par Assumptions, External Events, and Notes: -** head must not be NULL. node must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_InsertAfter + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CList_InsertAfter(CF_CListNode_t **head, CF_CListNode_t *start, CF_CListNode_t *after) { /* calling insert_after with nothing to insert after (no head) makes no sense */ @@ -186,13 +187,14 @@ void CF_CList_InsertAfter(CF_CListNode_t **head, CF_CListNode_t *start, CF_CList after->next->prev = after; } -/************************************************************************/ -/** \brief Traverse the entire list, calling the given function on all nodes. -** -** \par Assumptions, External Events, and Notes: -** start may be NULL. fn must be a valid function. context may be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_Traverse + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CList_Traverse(CF_CListNode_t *start, CF_CListFn_t fn, void *context) { CF_CListNode_t *n = start; @@ -228,13 +230,14 @@ void CF_CList_Traverse(CF_CListNode_t *start, CF_CListFn_t fn, void *context) err_out:; } -/************************************************************************/ -/** \brief Reverse list traversal, starting from end, calling given function on all nodes. -** -** \par Assumptions, External Events, and Notes: -** end may be NULL. fn must be a valid function. context may be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CList_Traverse_R + * + * Application-scope internal function + * See description in cf_clist.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CList_Traverse_R(CF_CListNode_t *end, CF_CListFn_t fn, void *context) { if (end) diff --git a/fsw/src/cf_clist.h b/fsw/src/cf_clist.h index d4406d810..465dd58d6 100644 --- a/fsw/src/cf_clist.h +++ b/fsw/src/cf_clist.h @@ -1,66 +1,166 @@ /************************************************************************ -** File: cf_clist.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application circular list header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application circular list header file + */ #ifndef CF_CLIST_H #define CF_CLIST_H #include -#define CF_CLIST_CONT 0 -#define CF_CLIST_EXIT 1 - -/* circular linked list */ +#define CF_CLIST_CONT 0 /**< Constant indicating to continue traversal */ +#define CF_CLIST_EXIT 1 /**< Constant indicating to stop traversal */ +/** + * @brief Node link structure + */ struct CF_CListNode { struct CF_CListNode *next; struct CF_CListNode *prev; }; +/** + * @brief Circular linked list node links + */ typedef struct CF_CListNode CF_CListNode_t; -/* good a place as any to put container_of for CF */ +/** + * @brief Obtains a pointer to the parent structure + * + * Given a pointer to a CF_CListNode_t object which is known to be a member of a + * larger container, this converts the pointer to that of the parent. + */ #define container_of(ptr, type, member) ((type *)((char *)(ptr) - (char *)offsetof(type, member))) +/** + * @brief Callback function type for use with CF_CList_Traverse() + * + * @param node Current node being traversed + * @param context Opaque pointer passed through from initial call + * + * @returns integer status code indicating whether to continue traversal + * @retval #CF_CLIST_CONT Indicates to continue traversing the list + * @retval #CF_CLIST_EXIT Indicates to stop traversing the list + */ +typedef int (*CF_CListFn_t)(CF_CListNode_t *node, void *context); + +/************************************************************************/ +/** @brief Initialize a clist node. + * + * @par Assumptions, External Events, and Notes: + * node must not be NULL. + * + * @param node Pointer to node structure to be initialized + */ void CF_CList_InitNode(CF_CListNode_t *node); -/* in the functions, head is the list head */ -void CF_CList_InsertFront(CF_CListNode_t **head, CF_CListNode_t *node); -void CF_CList_InsertBack(CF_CListNode_t **head, CF_CListNode_t *node); -void CF_CList_Remove(CF_CListNode_t **head, CF_CListNode_t *node); +/************************************************************************/ +/** @brief Insert the given node into the front of a list. + * + * @par Assumptions, External Events, and Notes: + * head must not be NULL. node must not be NULL. + * + * @param head Pointer to head of list to insert into + * @param node Pointer to node to insert + */ +void CF_CList_InsertFront(CF_CListNode_t **head, CF_CListNode_t *node); + +/************************************************************************/ +/** @brief Insert the given node into the back of a list. + * + * @par Assumptions, External Events, and Notes: + * head must not be NULL. node must not be NULL. + * + * @param head Pointer to head of list to insert into + * @param node Pointer to node to insert + */ +void CF_CList_InsertBack(CF_CListNode_t **head, CF_CListNode_t *node); + +/************************************************************************/ +/** @brief Remove the given node from the list. + * + * @par Assumptions, External Events, and Notes: + * head must not be NULL. node must not be NULL. + * + * @param head Pointer to head of list to remove from + * @param node Pointer to node to remove + */ +void CF_CList_Remove(CF_CListNode_t **head, CF_CListNode_t *node); + +/************************************************************************/ +/** @brief Remove the first node from a list and return it. + * + * @par Assumptions, External Events, and Notes: + * head must not be NULL. + * + * @param head Pointer to head of list to remove from + * + * @returns The first node (now removed) in the list + * @retval NULL if list was empty. + * + */ CF_CListNode_t *CF_CList_Pop(CF_CListNode_t **head); -void CF_CList_InsertAfter(CF_CListNode_t **head, CF_CListNode_t *start, CF_CListNode_t *after); -/* NOTE: if CF_CListFn_t returns non-zero, the list traversal stops */ -typedef int (*CF_CListFn_t)(CF_CListNode_t *node, void *context); +/************************************************************************/ +/** @brief Insert the given node into the last after the given start node. + * + * @par Assumptions, External Events, and Notes: + * head must not be NULL. node must not be NULL. + * + * @param head Pointer to head of list to remove from + * @param start Pointer to node to insert + * @param after Pointer to position to insert after + */ +void CF_CList_InsertAfter(CF_CListNode_t **head, CF_CListNode_t *start, CF_CListNode_t *after); -/* NOTE on traversal: it's ok to delete the current node, but do not delete - * other nodes in the same list!! */ +/************************************************************************/ +/** @brief Traverse the entire list, calling the given function on all nodes. + * + * @par Assumptions, External Events, and Notes: + * start may be NULL. fn must be a valid function. context may be NULL. + * + * @note on traversal it's ok to delete the current node, but do not delete + * other nodes in the same list!! + * + * @param start List to traverse (first node) + * @param fn Callback function to invoke for each node + * @param context Opaque pointer to pass to callback + */ void CF_CList_Traverse(CF_CListNode_t *start, CF_CListFn_t fn, void *context); -/* NOTE: traverse_R will work backwards from the parameter's prev, and end on param */ + +/************************************************************************/ +/** @brief Reverse list traversal, starting from end, calling given function on all nodes. + * + * @par Assumptions, External Events, and Notes: + * end may be NULL. fn must be a valid function. context may be NULL. + * + * @note traverse_R will work backwards from the parameter's prev, and end on param + * + * @param end List to traverse (last node) + * @param fn Callback function to invoke for each node + * @param context Opaque pointer to pass to callback + */ void CF_CList_Traverse_R(CF_CListNode_t *end, CF_CListFn_t fn, void *context); #endif /* !CF_CLIST_H */ diff --git a/fsw/src/cf_cmd.c b/fsw/src/cf_cmd.c index 1f8bd5289..5fc699280 100644 --- a/fsw/src/cf_cmd.c +++ b/fsw/src/cf_cmd.c @@ -1,31 +1,30 @@ /************************************************************************ -** File: cf_cmd.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application command handling source file -** -** All ground commands are processed in this file. All supporting functions -** necessary to process the commands are also here. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application command handling source file + * + * All ground commands are processed in this file. All supporting functions + * necessary to process the commands are also here. + */ #include "cf_app.h" #include "cf_verify.h" @@ -43,19 +42,14 @@ #define ALL_POLLDIRS ALL_CHANNELS #define COMPOUND_KEY 254 -/************************************************************************/ -/** \brief The no-operation command. -** -** \par Description -** This function has a signature the same of all cmd_ functions. -** This function simply prints an event message. -** Increments the command accept counter. -** The msg parameter is ignored in this one. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdNoop + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdNoop(CFE_SB_Buffer_t *msg) { CFE_EVS_SendEvent(CF_EID_INF_CMD_NOOP, CFE_EVS_EventType_INFORMATION, "CF: No-Op received, Version %d.%d.%d", @@ -63,19 +57,14 @@ void CF_CmdNoop(CFE_SB_Buffer_t *msg) CF_CmdAcc(); } -/************************************************************************/ -/** \brief The reset counters command. -** -** \par Description -** This function has a signature the same of all cmd_ functions. -** Resets the given counter, or all. -** Increments the command accept or reject counter. If the command -** counters are reset, then there is no increment. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdReset + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdReset(CFE_SB_Buffer_t *msg) { static const int counters_command = 1; @@ -141,17 +130,14 @@ void CF_CmdReset(CFE_SB_Buffer_t *msg) err_out:; } -/************************************************************************/ -/** \brief Ground command to start a file transfer. -** -** \par Description -** This function has a signature the same of all cmd_ functions. -** Increments the command accept or reject counter. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdTxFile + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdTxFile(CFE_SB_Buffer_t *msg) { CF_TxFileCmd_t *tx = (CF_TxFileCmd_t *)msg; @@ -164,17 +150,14 @@ void CF_CmdTxFile(CFE_SB_Buffer_t *msg) tx->dest_id)); } -/************************************************************************/ -/** \brief Ground command to start directory playback. -** -** \par Description -** This function has a signature the same of all cmd_ functions. -** Increments the command accept or reject counter. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdPlaybackDir + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdPlaybackDir(CFE_SB_Buffer_t *msg) { CF_PlaybackDirCmd_t *tx = (CF_PlaybackDirCmd_t *)msg; @@ -187,23 +170,14 @@ void CF_CmdPlaybackDir(CFE_SB_Buffer_t *msg) tx->priority, tx->dest_id)); } -/************************************************************************/ -/** \brief Common logic for all channel-based commands. -** -** \par Description -** All the commands that act on channels or have the special -** "all channels" parameter come through this function. This puts -** all common logic in one place. It does not handle the command -** accept or reject counters. -** -** \par Assumptions, External Events, and Notes: -** cmd must not be NULL. errstr must not be NULL. fn must be a valid function. context may be NULL. -** -** \returns -** \retstmt The return value from the given function. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_DoChanAction + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_DoChanAction(CF_UnionArgsCmd_t *cmd, const char *errstr, CF_ChanActionFn_t fn, void *context) { int ret = 0; @@ -233,17 +207,14 @@ int CF_DoChanAction(CF_UnionArgsCmd_t *cmd, const char *errstr, CF_ChanActionFn_ return ret; } -/************************************************************************/ -/** \brief Channel action to set the frozen bit for a channel. -** -** \par Assumptions, External Events, and Notes: -** context must not be NULL. -** -** \returns -** \retstmt Always succeeds, so returns 0. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_DoFreezeThaw + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_DoFreezeThaw(uint8 chan_num, const CF_ChanAction_BoolArg_t *context) { /* no need to bounds check chan_num, done in caller */ @@ -251,43 +222,42 @@ int CF_DoFreezeThaw(uint8 chan_num, const CF_ChanAction_BoolArg_t *context) return 0; } -/************************************************************************/ -/** \brief Freeze a channel. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdFreeze + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdFreeze(CFE_SB_Buffer_t *msg) { CF_ChanAction_BoolArg_t barg = {1}; /* param is frozen, so 1 means freeze */ CF_CmdCond(CF_DoChanAction((CF_UnionArgsCmd_t *)msg, "freeze", (CF_ChanActionFn_t)CF_DoFreezeThaw, &barg)); } -/************************************************************************/ -/** \brief Thaw a channel. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdThaw + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdThaw(CFE_SB_Buffer_t *msg) { CF_ChanAction_BoolArg_t barg = {0}; /* param is frozen, so 0 means thawed */ CF_CmdCond(CF_DoChanAction((CF_UnionArgsCmd_t *)msg, "thaw", (CF_ChanActionFn_t)CF_DoFreezeThaw, &barg)); } -/************************************************************************/ -/** \brief Search for a transaction across all channels. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retstmt The transaction, if found. Otherwise NULL. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_FindTransactionBySequenceNumberAllChannels + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_Transaction_t *CF_FindTransactionBySequenceNumberAllChannels(CF_TransactionSeq_t ts, CF_EntityId_t eid) { int i; @@ -310,24 +280,14 @@ CF_Transaction_t *CF_FindTransactionBySequenceNumberAllChannels(CF_TransactionSe return ret; } -/* CF_TsnChanAction() returns the number of transactions acted upon */ -/************************************************************************/ -/** \brief Common logic for all transaction sequence number and channel commands. -** -** \par Description -** All the commands that on a transaction on a particular channel come -** through this function. This puts all common logic in one place. It -** does handle the command accept or reject counters. -** -** \par Assumptions, External Events, and Notes: -** cmd must not be NULL. fn must be a valid function. context may be NULL. -** -** \returns -** \retcode #CFE_SUCCESS \retdesc \copydoc CFE_SUCCESSS \endcode -** \retstmt Returns anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_TsnChanAction + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_TsnChanAction(CF_TransactionCmd_t *cmd, const char *cmdstr, CF_TsnChanAction_fn_t fn, void *context) { int ret = -1; @@ -367,13 +327,14 @@ int CF_TsnChanAction(CF_TransactionCmd_t *cmd, const char *cmdstr, CF_TsnChanAct return ret; } -/************************************************************************/ -/** \brief Set the suspended bit in a transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. context must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_DoSuspRes_Txn + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_DoSuspRes_Txn(CF_Transaction_t *t, CF_ChanAction_SuspResArg_t *context) { CF_Assert(t); @@ -387,17 +348,14 @@ void CF_DoSuspRes_Txn(CF_Transaction_t *t, CF_ChanAction_SuspResArg_t *context) } } -/************************************************************************/ -/** \brief Handle transaction suspend and resume commands. -** -** \par Description -** This is called for both suspend and resume ground commands. -** It uses the CF_TsnChanAction() function to perform the command. -** -** \par Assumptions, External Events, and Notes: -** cmd must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_DoSuspRes + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_DoSuspRes(CF_TransactionCmd_t *cmd, uint8 action) { /* ok to not bounds check action, because the caller is using it in two places with constant values 0 or 1 */ @@ -423,89 +381,92 @@ void CF_DoSuspRes(CF_TransactionCmd_t *cmd, uint8 action) } } -/************************************************************************/ -/** \brief Handle transaction suspend command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdSuspend + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdSuspend(CFE_SB_Buffer_t *msg) { CF_DoSuspRes((CF_TransactionCmd_t *)msg, 1); } -/************************************************************************/ -/** \brief Handle transaction resume command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdResume + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdResume(CFE_SB_Buffer_t *msg) { CF_DoSuspRes((CF_TransactionCmd_t *)msg, 0); } -/************************************************************************/ -/** \brief tsn chan action to cancel a transaction. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdCancel_Txn + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdCancel_Txn(CF_Transaction_t *t, void *ignored) { CF_CFDP_CancelTransaction(t); } -/************************************************************************/ -/** \brief Handle a cancel ground command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdCancel + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdCancel(CFE_SB_Buffer_t *msg) { CF_CmdCond(CF_TsnChanAction((CF_TransactionCmd_t *)msg, "cancel", CF_CmdCancel_Txn, NULL)); } -/************************************************************************/ -/** \brief tsn chan action to abandon a transaction. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdAbandon_Txn + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdAbandon_Txn(CF_Transaction_t *t, void *ignored) { CF_CFDP_ResetTransaction(t, 0); } -/************************************************************************/ -/** \brief Handle an abandon ground command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdAbandon + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdAbandon(CFE_SB_Buffer_t *msg) { CF_CmdCond(CF_TsnChanAction((CF_TransactionCmd_t *)msg, "abandon", CF_CmdAbandon_Txn, NULL)); } -/************************************************************************/ -/** \brief Sets the dequeue enable/disable flag for a channel. -** -** \par Assumptions, External Events, and Notes: -** context must not be NULL. -** -** \returns -** \retstmt Always succeeds, so returns 0. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_DoEnableDisableDequeue + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_DoEnableDisableDequeue(uint8 chan_num, const CF_ChanAction_BoolArg_t *context) { /* no need to bounds check chan_num, done in caller */ @@ -513,13 +474,14 @@ int CF_DoEnableDisableDequeue(uint8 chan_num, const CF_ChanAction_BoolArg_t *con return 0; } -/************************************************************************/ -/** \brief Handle an enable dequeue ground command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdEnableDequeue + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdEnableDequeue(CFE_SB_Buffer_t *msg) { CF_ChanAction_BoolArg_t barg = {1}; @@ -527,13 +489,14 @@ void CF_CmdEnableDequeue(CFE_SB_Buffer_t *msg) &barg)); } -/************************************************************************/ -/** \brief Handle a disable dequeue ground command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdDisableDequeue + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdDisableDequeue(CFE_SB_Buffer_t *msg) { CF_ChanAction_BoolArg_t barg = {0}; @@ -541,13 +504,14 @@ void CF_CmdDisableDequeue(CFE_SB_Buffer_t *msg) (CF_ChanActionFn_t)CF_DoEnableDisableDequeue, &barg)); } -/************************************************************************/ -/** \brief Sets the enable/disable flag for the specified polling directory. -** -** \par Assumptions, External Events, and Notes: -** context must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_DoEnableDisablePolldir + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_DoEnableDisablePolldir(uint8 chan_num, const CF_ChanAction_BoolMsgArg_t *context) { int ret = 0; @@ -574,13 +538,14 @@ int CF_DoEnableDisablePolldir(uint8 chan_num, const CF_ChanAction_BoolMsgArg_t * return ret; } -/************************************************************************/ -/** \brief Enable a polling dir ground command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdEnablePolldir + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdEnablePolldir(CFE_SB_Buffer_t *msg) { CF_ChanAction_BoolMsgArg_t barg = {(CF_UnionArgsCmd_t *)msg, 1}; @@ -588,13 +553,14 @@ void CF_CmdEnablePolldir(CFE_SB_Buffer_t *msg) &barg)); } -/************************************************************************/ -/** \brief Disable a polling dir ground command. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdDisablePolldir + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdDisablePolldir(CFE_SB_Buffer_t *msg) { CF_ChanAction_BoolMsgArg_t barg = {(CF_UnionArgsCmd_t *)msg, 0}; @@ -602,13 +568,14 @@ void CF_CmdDisablePolldir(CFE_SB_Buffer_t *msg) (CF_ChanActionFn_t)CF_DoEnableDisablePolldir, &barg)); } -/************************************************************************/ -/** \brief Purge the history queue for the given channel. -** -** \par Assumptions, External Events, and Notes: -** n must not be NULL. c must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_PurgeHistory + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_PurgeHistory(CF_CListNode_t *n, CF_Channel_t *c) { CF_History_t *h = container_of(n, CF_History_t, cl_node); @@ -616,13 +583,14 @@ int CF_PurgeHistory(CF_CListNode_t *n, CF_Channel_t *c) return CF_CLIST_CONT; } -/************************************************************************/ -/** \brief Purge the pending transaction queue. -** -** \par Assumptions, External Events, and Notes: -** n must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_PurgeTransaction + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_PurgeTransaction(CF_CListNode_t *n, void *ignored) { CF_Transaction_t *t = container_of(n, CF_Transaction_t, cl_node); @@ -630,21 +598,14 @@ int CF_PurgeTransaction(CF_CListNode_t *n, void *ignored) return CF_CLIST_CONT; } -/************************************************************************/ -/** \brief Channel action command to perform purge queue operations. -** -** \par Description -** Determines from the command parameters which queues to traverse -** and purge state. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retstmt 0 on success; anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_DoPurgeQueue + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_DoPurgeQueue(uint8 chan_num, CF_UnionArgsCmd_t *cmd) { int ret = 0; @@ -689,25 +650,27 @@ int CF_DoPurgeQueue(uint8 chan_num, CF_UnionArgsCmd_t *cmd) return ret; } -/************************************************************************/ -/** \brief Ground command to purge either the history or pending queues. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdPurgeQueue + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdPurgeQueue(CFE_SB_Buffer_t *msg) { CF_CmdCond(CF_DoChanAction((CF_UnionArgsCmd_t *)msg, "purge_queue", (CF_ChanActionFn_t)CF_DoPurgeQueue, msg)); } -/************************************************************************/ -/** \brief Ground command to write a file with queue information. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdWriteQueue + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdWriteQueue(CFE_SB_Buffer_t *msg) { /* a type value of 0 means to process both type_up and type_down */ @@ -829,13 +792,14 @@ void CF_CmdWriteQueue(CFE_SB_Buffer_t *msg) CF_CmdRej(); } -/************************************************************************/ -/** \brief Ground command to send configuration parameters. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdSendCfgParams + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdSendCfgParams(CFE_SB_Buffer_t *msg) { CF_AppData.cfg.ticks_per_second = CF_AppData.config_table->ticks_per_second; @@ -854,17 +818,14 @@ void CF_CmdSendCfgParams(CFE_SB_Buffer_t *msg) CF_CmdAcc(); } -/************************************************************************/ -/** \brief Checks if the value is less than or equal to the max pdu size. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retstmt 0 if success, 1 if failed. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdValidateChunkSize + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CmdValidateChunkSize(uint32 val, uint8 chan_num /* ignored */) { int ret = 0; @@ -875,17 +836,14 @@ int CF_CmdValidateChunkSize(uint32 val, uint8 chan_num /* ignored */) return ret; } -/************************************************************************/ -/** \brief Checks if the value is -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retstmt 0 if success, 1 if failed. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdValidateMaxOutgoing + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_CmdValidateMaxOutgoing(uint32 val, uint8 chan_num) { int ret = 0; @@ -899,18 +857,14 @@ int CF_CmdValidateMaxOutgoing(uint32 val, uint8 chan_num) return ret; } -/************************************************************************/ -/** \brief Perform a configuration get/set operation. -** -** \par Description -** Combine get and set in one function with common logic. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ -/* combine getset into a single function with a branch to avoid wasted memory footprint with duplicate - * logic for finding the parameter */ +/*---------------------------------------------------------------- + * + * Function: CF_CmdGetSetParam + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdGetSetParam(uint8 is_set, CF_GetSet_ValueID_t param_id, uint32 value, uint8 chan_num) { CF_ConfigTable_t *config; @@ -1066,39 +1020,42 @@ void CF_CmdGetSetParam(uint8 is_set, CF_GetSet_ValueID_t param_id, uint32 value, CF_CmdCond(acc); } -/************************************************************************/ -/** \brief Ground command to set a configuration parameter. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdSetParam + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdSetParam(CFE_SB_Buffer_t *msg) { CF_SetParamCmd_t *cmd = (CF_SetParamCmd_t *)msg; CF_CmdGetSetParam(1, cmd->key, cmd->value, cmd->chan_num); } -/************************************************************************/ -/** \brief Ground command to set a configuration parameter. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdGetParam + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdGetParam(CFE_SB_Buffer_t *msg) { CF_GetParamCmd_t *cmd = (CF_GetParamCmd_t *)msg; CF_CmdGetSetParam(0, cmd->key, 0, cmd->chan_num); } -/************************************************************************/ -/** \brief Ground command enable engine. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdEnableEngine + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdEnableEngine(CFE_SB_Buffer_t *msg) { if (!CF_AppData.engine.enabled) @@ -1122,13 +1079,14 @@ void CF_CmdEnableEngine(CFE_SB_Buffer_t *msg) } } -/************************************************************************/ -/** \brief Ground command disable engine. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CmdDisableEngine + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CmdDisableEngine(CFE_SB_Buffer_t *msg) { if (CF_AppData.engine.enabled) @@ -1144,13 +1102,14 @@ void CF_CmdDisableEngine(CFE_SB_Buffer_t *msg) } } -/************************************************************************/ -/** \brief Process any ground command contained in the given message. -** -** \par Assumptions, External Events, and Notes: -** msg must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ProcessGroundCommand + * + * Application-scope internal function + * See description in cf_cmd.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_ProcessGroundCommand(CFE_SB_Buffer_t *msg) { static void (*const fns[CF_NUM_COMMANDS])(CFE_SB_Buffer_t *) = { diff --git a/fsw/src/cf_cmd.h b/fsw/src/cf_cmd.h index 701cdeb68..9e5c66763 100644 --- a/fsw/src/cf_cmd.h +++ b/fsw/src/cf_cmd.h @@ -1,23 +1,27 @@ /************************************************************************ -** File: cf_cmd.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * CF command processing function declarations + */ #ifndef CF_CMD_H #define CF_CMD_H @@ -26,21 +30,46 @@ #include "cf_app.h" #include "cf_utils.h" +/** + * @brief A callback function for use with CF_DoChanAction() + * + * @param chan_num The CF channel number, for statistics purposes + * @param context Opaque object passed through from initial call + */ typedef int (*CF_ChanActionFn_t)(uint8 chan_num, void *context); +/** + * @brief An object to use with channel-scope actions requiring only a boolean argument + */ typedef struct CF_ChanAction_BoolArg { bool barg; } CF_ChanAction_BoolArg_t; +/** + * @brief A callback to use with transaction actions + * + * For now this is the same as CF_TraverseAllTransactions_fn_t + */ typedef CF_TraverseAllTransactions_fn_t CF_TsnChanAction_fn_t; +/** + * @brief An object to use with channel-scope actions for suspend/resume + * + * This combines a boolean action arg with an output that indicates if it + * was a change or not. + */ typedef struct CF_ChanAction_SuspResArg { - int same; /* out param -- indicates at least one action was set to its current value */ + int same; /**< out param -- indicates at least one action was set to its current value */ bool action; } CF_ChanAction_SuspResArg_t; +/** + * @brief An object to use with channel-scope actions that require the message value + * + * This combines a boolean action arg with the command message value + */ typedef struct CF_ChanAction_BoolMsgArg { const CF_UnionArgsCmd_t *msg; @@ -48,79 +77,533 @@ typedef struct CF_ChanAction_BoolMsgArg } CF_ChanAction_BoolMsgArg_t; /************************************************************************/ -/** \brief Increment the command accepted counter. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/** @brief Increment the command accepted counter. + * + * @par Assumptions, External Events, and Notes: + * None + */ static inline void CF_CmdAcc(void) { ++CF_AppData.hk.counters.cmd; } /************************************************************************/ -/** \brief Increment the command rejected counter. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/** @brief Increment the command rejected counter. + * + * @par Assumptions, External Events, and Notes: + * None + * + */ static inline void CF_CmdRej(void) { ++CF_AppData.hk.counters.err; } /************************************************************************/ -/** \brief Conditionally increment the command accept or reject counters. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/** @brief Conditionally increment the command accept or reject counters. + * + * @par Assumptions, External Events, and Notes: + * None + * + */ static inline void CF_CmdCond(int cond) { static void (*const fns[])(void) = {CF_CmdAcc, CF_CmdRej}; fns[!!cond](); } -void CF_CmdNoop(CFE_SB_Buffer_t *msg); -void CF_CmdReset(CFE_SB_Buffer_t *msg); -void CF_CmdTxFile(CFE_SB_Buffer_t *msg); -void CF_CmdPlaybackDir(CFE_SB_Buffer_t *msg); -int CF_DoChanAction(CF_UnionArgsCmd_t *cmd, const char *errstr, CF_ChanActionFn_t fn, void *context); -int CF_DoFreezeThaw(uint8 chan_num, const CF_ChanAction_BoolArg_t *context); -void CF_CmdFreeze(CFE_SB_Buffer_t *msg); -void CF_CmdThaw(CFE_SB_Buffer_t *msg); +/************************************************************************/ +/** @brief The no-operation command. + * + * @par Description + * This function has a signature the same of all cmd_ functions. + * This function simply prints an event message. + * Increments the command accept counter. + * The msg parameter is ignored in this one. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param msg Pointer to command message + */ +void CF_CmdNoop(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief The reset counters command. + * + * @par Description + * This function has a signature the same of all cmd_ functions. + * Resets the given counter, or all. + * Increments the command accept or reject counter. If the command + * counters are reset, then there is no increment. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ +void CF_CmdReset(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Ground command to start a file transfer. + * + * @par Description + * This function has a signature the same of all cmd_ functions. + * Increments the command accept or reject counter. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + * + */ +void CF_CmdTxFile(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Ground command to start directory playback. + * + * @par Description + * This function has a signature the same of all cmd_ functions. + * Increments the command accept or reject counter. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ +void CF_CmdPlaybackDir(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Common logic for all channel-based commands. + * + * @par Description + * All the commands that act on channels or have the special + * "all channels" parameter come through this function. This puts + * all common logic in one place. It does not handle the command + * accept or reject counters. + * + * @par Assumptions, External Events, and Notes: + * cmd must not be NULL. errstr must not be NULL. fn must be a valid function. context may be NULL. + * + * @param cmd Pointer to command being processed + * @param errstr String to be included in the EVS event if command should fail + * @param fn Callback action function to invoke for each affected channel + * @param context Opaque pointer to pass through to callback (not used in this function) + * + * @returns The return value from the given action function. + * + */ +int CF_DoChanAction(CF_UnionArgsCmd_t *cmd, const char *errstr, CF_ChanActionFn_t fn, void *context); + +/************************************************************************/ +/** @brief Channel action to set the frozen bit for a channel. + * + * @par Assumptions, External Events, and Notes: + * context must not be NULL. + * + * @param chan_num channel number + * @param context Pointer to object passed through from initial call + * + * @returns Always succeeds, so returns 0. + */ +int CF_DoFreezeThaw(uint8 chan_num, const CF_ChanAction_BoolArg_t *context); + +/************************************************************************/ +/** @brief Freeze a channel. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ +void CF_CmdFreeze(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Thaw a channel. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ +void CF_CmdThaw(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Search for a transaction across all channels. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param ts Transaction sequence number to find + * @param eid Entity ID of the transaction + * + * @returns Pointer to the transaction, if found + * @retval NULL if transaction not found + * + */ CF_Transaction_t *CF_FindTransactionBySequenceNumberAllChannels(CF_TransactionSeq_t ts, CF_EntityId_t eid); -int CF_TsnChanAction(CF_TransactionCmd_t *cmd, const char *cmdstr, CF_TsnChanAction_fn_t fn, void *context); + +/************************************************************************/ +/** @brief Common logic for all transaction sequence number and channel commands. + * + * @par Description + * All the commands that on a transaction on a particular channel come + * through this function. This puts all common logic in one place. It + * does handle the command accept or reject counters. + * + * @par Assumptions, External Events, and Notes: + * cmd must not be NULL. fn must be a valid function. context may be NULL. + * + * @param cmd Pointer to the command message + * @param cmdstr String to include in any generated EVS events + * @param fn Callback function to invoke for each matched transaction + * @param context Opaque object to pass through to the callback + * + * @returns returns the number of transactions acted upon + * + */ +int CF_TsnChanAction(CF_TransactionCmd_t *cmd, const char *cmdstr, CF_TsnChanAction_fn_t fn, void *context); + +/************************************************************************/ +/** @brief Set the suspended bit in a transaction. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. context must not be NULL. + * + * @param t Pointer to the transaction object + * @param context Pointer to CF_ChanAction_SuspResArg_t structure from initial call + */ void CF_DoSuspRes_Txn(CF_Transaction_t *t, CF_ChanAction_SuspResArg_t *context); + +/************************************************************************/ +/** @brief Handle transaction suspend and resume commands. + * + * @par Description + * This is called for both suspend and resume ground commands. + * It uses the CF_TsnChanAction() function to perform the command. + * + * @par Assumptions, External Events, and Notes: + * cmd must not be NULL. + * + * @param cmd Pointer to the command message + * @param action Action to take (suspend or resume) + */ void CF_DoSuspRes(CF_TransactionCmd_t *cmd, uint8 action); + +/************************************************************************/ +/** @brief Handle transaction suspend command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdSuspend(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Handle transaction resume command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdResume(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief tsn chan action to cancel a transaction. + * + * This helper function is used with CF_TsnChanAction() to cancel matched transactions + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to transaction object + * @param ignored Not used by this function + */ void CF_CmdCancel_Txn(CF_Transaction_t *t, void *ignored); + +/************************************************************************/ +/** @brief Handle a cancel ground command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdCancel(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief tsn chan action to abandon a transaction. + * + * This helper function is used with CF_TsnChanAction() to abandon matched transactions + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param t Pointer to transaction object + * @param ignored Not used by this function + */ void CF_CmdAbandon_Txn(CF_Transaction_t *t, void *ignored); + +/************************************************************************/ +/** @brief Handle an abandon ground command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdAbandon(CFE_SB_Buffer_t *msg); -int CF_DoEnableDisableDequeue(uint8 chan_num, const CF_ChanAction_BoolArg_t *context); + +/************************************************************************/ +/** @brief Sets the dequeue enable/disable flag for a channel. + * + * @par Assumptions, External Events, and Notes: + * context must not be NULL. + * + * @param chan_num channel number + * @param context Pointer to object passed through from initial call + * + * @returns Always succeeds, so returns 0. + * + */ +int CF_DoEnableDisableDequeue(uint8 chan_num, const CF_ChanAction_BoolArg_t *context); + +/************************************************************************/ +/** @brief Handle an enable dequeue ground command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdEnableDequeue(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Handle a disable dequeue ground command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdDisableDequeue(CFE_SB_Buffer_t *msg); -int CF_DoEnableDisablePolldir(uint8 chan_num, const CF_ChanAction_BoolMsgArg_t *context); + +/************************************************************************/ +/** @brief Sets the enable/disable flag for the specified polling directory. + * + * @par Assumptions, External Events, and Notes: + * context must not be NULL. + * + * @param chan_num channel number + * @param context Pointer to object passed through from initial call + * + * @returns success/fail status code + * @retval 0 if successful + * @retval -1 if failed + */ +int CF_DoEnableDisablePolldir(uint8 chan_num, const CF_ChanAction_BoolMsgArg_t *context); + +/************************************************************************/ +/** @brief Enable a polling dir ground command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdEnablePolldir(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Disable a polling dir ground command. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdDisablePolldir(CFE_SB_Buffer_t *msg); -int CF_PurgeHistory(CF_CListNode_t *n, CF_Channel_t *c); -int CF_PurgeTransaction(CF_CListNode_t *n, void *ignored); -int CF_DoPurgeQueue(uint8 chan_num, CF_UnionArgsCmd_t *cmd); + +/************************************************************************/ +/** @brief Purge the history queue for the given channel. + * + * This helper function is used in conjunction with CF_CList_Traverse() + * + * @par Assumptions, External Events, and Notes: + * n must not be NULL. c must not be NULL. + * + * @param n Current list node being traversed + * @param c Channel pointer passed through as opaque object + * + * @returns Always #CF_CLIST_CONT to process all entries + */ +int CF_PurgeHistory(CF_CListNode_t *n, CF_Channel_t *c); + +/************************************************************************/ +/** @brief Purge the pending transaction queue. + * + * This helper function is used in conjunction with CF_CList_Traverse() + * + * @par Assumptions, External Events, and Notes: + * n must not be NULL. + * + * @param n Current list node being traversed + * @param ignored Not used by this implementation + * + * @returns Always #CF_CLIST_CONT to process all entries + */ +int CF_PurgeTransaction(CF_CListNode_t *n, void *ignored); + +/************************************************************************/ +/** @brief Channel action command to perform purge queue operations. + * + * @par Description + * Determines from the command parameters which queues to traverse + * and purge state. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param chan_num CF channel number + * @param cmd Pointer to purge queue command + * + * @returns integer status code indicating success or failure + * @retval 0 if successful + * @retval -1 if error occurred + */ +int CF_DoPurgeQueue(uint8 chan_num, CF_UnionArgsCmd_t *cmd); + +/************************************************************************/ +/** @brief Ground command to purge either the history or pending queues. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdPurgeQueue(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Ground command to write a file with queue information. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdWriteQueue(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Ground command to send configuration parameters. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdSendCfgParams(CFE_SB_Buffer_t *msg); -int CF_CmdValidateChunkSize(uint32 val, uint8 chan_num /* ignored */); -int CF_CmdValidateMaxOutgoing(uint32 val, uint8 chan_num); + +/************************************************************************/ +/** @brief Checks if the value is less than or equal to the max pdu size. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param val Size of chunk to test + * @param chan_num Ignored by this implementation + * + * @returns status code indicating if check passed + * @retval 0 if successful (val is less than or equal to max PDU) + * @retval 1 if failed (val is greater than max PDU) + * + */ +int CF_CmdValidateChunkSize(uint32 val, uint8 chan_num); + +/************************************************************************/ +/** @brief Checks if the value is within allowable range as outgoing packets per wakeup + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param val Number to test + * @param chan_num CF channel number + * + * @returns status code indicating if check passed + * @retval 0 if successful (val is allowable as max packets per wakeup) + * @retval 1 if failed (val is not allowed) + * + */ +int CF_CmdValidateMaxOutgoing(uint32 val, uint8 chan_num); + +/************************************************************************/ +/** @brief Perform a configuration get/set operation. + * + * For a set, this sets the value within the CF configuration + * For a get, this generates an EVS event with the requested information + * + * @par Description + * Combine get and set in one function with common logic. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param is_set Whether to get (0) or set (1) + * @param param_id Parameter ID + * @param value Value to get/set + * @param chan_num Channel number to operate on + * + */ void CF_CmdGetSetParam(uint8 is_set, CF_GetSet_ValueID_t param_id, uint32 value, uint8 chan_num); + +/************************************************************************/ +/** @brief Ground command to set a configuration parameter. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdSetParam(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Ground command to set a configuration parameter. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdGetParam(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Ground command enable engine. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdEnableEngine(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Ground command disable engine. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_CmdDisableEngine(CFE_SB_Buffer_t *msg); + +/************************************************************************/ +/** @brief Process any ground command contained in the given message. + * + * @par Assumptions, External Events, and Notes: + * msg must not be NULL. + * + * @param msg Pointer to command message + */ void CF_ProcessGroundCommand(CFE_SB_Buffer_t *msg); #endif diff --git a/fsw/src/cf_codec.c b/fsw/src/cf_codec.c index e6366ee31..fc84a5e1b 100644 --- a/fsw/src/cf_codec.c +++ b/fsw/src/cf_codec.c @@ -1,23 +1,28 @@ /************************************************************************ -** File: cf_codec.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ + +/** + * @file + * + * CFDP protocol data structure encode/decode implementation + */ #define CF_DO_DECLARE_FIELDS @@ -31,12 +36,27 @@ * literal integers as well as variables. So they operate on value, where * the load/get functions operate by reference */ + +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Store_uint8 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Store_uint8(CF_CFDP_uint8_t *pdst, uint8 val) { pdst->octets[0] = val; } #define cfdp_set_uint8(dst, src) CF_Codec_Store_uint8(&(dst), src) +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Store_uint16 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Store_uint16(CF_CFDP_uint16_t *pdst, uint16 val) { pdst->octets[1] = val & 0xFF; @@ -45,6 +65,13 @@ static inline void CF_Codec_Store_uint16(CF_CFDP_uint16_t *pdst, uint16 val) } #define cfdp_set_uint16(dst, src) CF_Codec_Store_uint16(&(dst), src) +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Store_uint32 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Store_uint32(CF_CFDP_uint32_t *pdst, uint32 val) { pdst->octets[3] = val & 0xFF; @@ -57,6 +84,13 @@ static inline void CF_Codec_Store_uint32(CF_CFDP_uint32_t *pdst, uint32 val) } #define cfdp_set_uint32(dst, src) CF_Codec_Store_uint32(&(dst), src) +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Store_uint64 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Store_uint64(CF_CFDP_uint64_t *pdst, uint64 val) { pdst->octets[7] = val & 0xFF; @@ -77,12 +111,26 @@ static inline void CF_Codec_Store_uint64(CF_CFDP_uint64_t *pdst, uint64 val) } #define cfdp_set_uint64(dst, src) CF_Codec_Store_uint64(&(dst), src) +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Load_uint8 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Load_uint8(uint8 *pdst, const CF_CFDP_uint8_t *psrc) { *pdst = psrc->octets[0]; } #define cfdp_get_uint8(dst, src) CF_Codec_Load_uint8(&(dst), &(src)) +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Load_uint16 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Load_uint16(uint16 *pdst, const CF_CFDP_uint16_t *psrc) { uint16 val = 0; @@ -95,6 +143,13 @@ static inline void CF_Codec_Load_uint16(uint16 *pdst, const CF_CFDP_uint16_t *ps } #define cfdp_get_uint16(dst, src) CF_Codec_Load_uint16(&(dst), &(src)) +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Load_uint32 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Load_uint32(uint32 *pdst, const CF_CFDP_uint32_t *psrc) { uint32 val = 0; @@ -111,6 +166,13 @@ static inline void CF_Codec_Load_uint32(uint32 *pdst, const CF_CFDP_uint32_t *ps } #define cfdp_get_uint32(dst, src) CF_Codec_Load_uint32(&(dst), &(src)) +/*---------------------------------------------------------------- + * + * Function: CF_Codec_Load_uint64 + * + * Internal helper routine only, not part of API. + * + *-----------------------------------------------------------------*/ static inline void CF_Codec_Load_uint64(uint64 *pdst, const CF_CFDP_uint64_t *psrc) { uint64 val = 0; @@ -135,6 +197,14 @@ static inline void CF_Codec_Load_uint64(uint64 *pdst, const CF_CFDP_uint64_t *ps } #define cfdp_get_uint64(dst, src) CF_Codec_Load_uint64(&(dst), &(src)) +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_CodecCheckSize + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ bool CF_CFDP_CodecCheckSize(CF_CodecState_t *state, size_t chunksize) { size_t next_offset = state->next_offset + chunksize; @@ -151,6 +221,14 @@ bool CF_CFDP_CodecCheckSize(CF_CodecState_t *state, size_t chunksize) return CF_CFDP_CodecIsOK(state); } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DoEncodeChunk + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void *CF_CFDP_DoEncodeChunk(CF_EncoderState_t *state, size_t chunksize) { uint8 *buf = state->base + CF_CFDP_CodecGetPosition(&state->codec_state); @@ -163,6 +241,14 @@ void *CF_CFDP_DoEncodeChunk(CF_EncoderState_t *state, size_t chunksize) return buf; } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DoDecodeChunk + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ const void *CF_CFDP_DoDecodeChunk(CF_DecoderState_t *state, size_t chunksize) { const uint8 *buf = state->base + CF_CFDP_CodecGetPosition(&state->codec_state); @@ -175,6 +261,14 @@ const void *CF_CFDP_DoDecodeChunk(CF_DecoderState_t *state, size_t chunksize) return buf; } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_GetValueEncodedSize + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ uint8 CF_CFDP_GetValueEncodedSize(uint64 Value) { uint8 MinSize; @@ -189,6 +283,14 @@ uint8 CF_CFDP_GetValueEncodedSize(uint64 Value) return MinSize; } +/*---------------------------------------------------------------- + * + * Function: CF_EncodeIntegerInSize + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_EncodeIntegerInSize(CF_EncoderState_t *state, uint64 value, uint8 encode_size) { uint8 *dptr; @@ -208,18 +310,14 @@ void CF_EncodeIntegerInSize(CF_EncoderState_t *state, uint64 value, uint8 encode } } -/* - * On transmit side, the common/base header must be encoded in two parts, to deal - * with the "total_size" field. The initial encoding of the the basic fields is - * done as soon as it is known that a PDU of this type needs to be sent, but the - * total size may not be yet known, as it depends on the remainder of encoding - * and any additional data that might get added to the variable length sections. - * - * This function encodes all base header fields _except_ total length. There is a - * separate function later to update the total_length to the correct value once the - * remainder of encoding is done. Luckily, the total_length is in the first fixed - * position binary blob so it is easy to update later. - */ +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeHeaderWithoutSize + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeHeaderWithoutSize(CF_EncoderState_t *state, CF_Logical_PduHeader_t *plh) { CF_CFDP_PduHeader_t *peh; /* for encoding fixed sized fields */ @@ -250,6 +348,14 @@ void CF_CFDP_EncodeHeaderWithoutSize(CF_EncoderState_t *state, CF_Logical_PduHea } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeHeaderFinalSize + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeHeaderFinalSize(CF_EncoderState_t *state, CF_Logical_PduHeader_t *plh) { CF_CFDP_PduHeader_t *peh; @@ -274,6 +380,14 @@ void CF_CFDP_EncodeHeaderFinalSize(CF_EncoderState_t *state, CF_Logical_PduHeade CF_CODEC_SET_DONE(state); } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeFileDirectiveHeader + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeFileDirectiveHeader(CF_EncoderState_t *state, CF_Logical_PduFileDirectiveHeader_t *pfdir) { CF_CFDP_PduFileDirectiveHeader_t *peh; /* for encoding fixed sized fields */ @@ -286,6 +400,14 @@ void CF_CFDP_EncodeFileDirectiveHeader(CF_EncoderState_t *state, CF_Logical_PduF } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeLV + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeLV(CF_EncoderState_t *state, CF_Logical_Lv_t *pllv) { CF_CFDP_lv_t *lv; /* for encoding fixed sized fields */ @@ -310,6 +432,14 @@ void CF_CFDP_EncodeLV(CF_EncoderState_t *state, CF_Logical_Lv_t *pllv) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeTLV + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeTLV(CF_EncoderState_t *state, CF_Logical_Tlv_t *pltlv) { CF_CFDP_tlv_t *tlv; /* for encoding fixed sized fields */ @@ -342,6 +472,14 @@ void CF_CFDP_EncodeTLV(CF_EncoderState_t *state, CF_Logical_Tlv_t *pltlv) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeSegmentRequest + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeSegmentRequest(CF_EncoderState_t *state, CF_Logical_SegmentRequest_t *plseg) { CF_CFDP_SegmentRequest_t *sr; /* for encoding fixed sized fields */ @@ -354,6 +492,14 @@ void CF_CFDP_EncodeSegmentRequest(CF_EncoderState_t *state, CF_Logical_SegmentRe } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeAllTlv + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeAllTlv(CF_EncoderState_t *state, CF_Logical_TlvList_t *pltlv) { uint8 i; @@ -364,6 +510,14 @@ void CF_CFDP_EncodeAllTlv(CF_EncoderState_t *state, CF_Logical_TlvList_t *pltlv) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeAllSegments + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeAllSegments(CF_EncoderState_t *state, CF_Logical_SegmentList_t *plseg) { uint8 i; @@ -374,6 +528,14 @@ void CF_CFDP_EncodeAllSegments(CF_EncoderState_t *state, CF_Logical_SegmentList_ } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeMd + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeMd(CF_EncoderState_t *state, CF_Logical_PduMd_t *plmd) { CF_CFDP_PduMd_t *md; /* for encoding fixed sized fields */ @@ -392,6 +554,14 @@ void CF_CFDP_EncodeMd(CF_EncoderState_t *state, CF_Logical_PduMd_t *plmd) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeFileDataHeader + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeFileDataHeader(CF_EncoderState_t *state, bool with_meta, CF_Logical_PduFileDataHeader_t *plfd) { CF_CFDP_PduFileDataHeader_t *fd; @@ -423,6 +593,14 @@ void CF_CFDP_EncodeFileDataHeader(CF_EncoderState_t *state, bool with_meta, CF_L } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeEof + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeEof(CF_EncoderState_t *state, CF_Logical_PduEof_t *pleof) { CF_CFDP_PduEof_t *eof; /* for encoding fixed sized fields */ @@ -439,6 +617,14 @@ void CF_CFDP_EncodeEof(CF_EncoderState_t *state, CF_Logical_PduEof_t *pleof) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeFin + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeFin(CF_EncoderState_t *state, CF_Logical_PduFin_t *plfin) { CF_CFDP_PduFin_t *fin; /* for encoding fixed sized fields */ @@ -455,6 +641,14 @@ void CF_CFDP_EncodeFin(CF_EncoderState_t *state, CF_Logical_PduFin_t *plfin) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeAck + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeAck(CF_EncoderState_t *state, CF_Logical_PduAck_t *plack) { CF_CFDP_PduAck_t *ack; /* for encoding fixed sized fields */ @@ -472,6 +666,14 @@ void CF_CFDP_EncodeAck(CF_EncoderState_t *state, CF_Logical_PduAck_t *plack) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeNak + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeNak(CF_EncoderState_t *state, CF_Logical_PduNak_t *plnak) { CF_CFDP_PduNak_t *nak; /* for encoding fixed sized fields */ @@ -486,6 +688,14 @@ void CF_CFDP_EncodeNak(CF_EncoderState_t *state, CF_Logical_PduNak_t *plnak) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_EncodeCrc + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_EncodeCrc(CF_EncoderState_t *state, uint32 *plcrc) { CF_CFDP_uint32_t *pecrc; /* CFDP CRC values are 32-bit only, per blue book */ @@ -497,6 +707,14 @@ void CF_CFDP_EncodeCrc(CF_EncoderState_t *state, uint32 *plcrc) } } +/*---------------------------------------------------------------- + * + * Function: CF_DecodeIntegerInSize + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ uint64 CF_DecodeIntegerInSize(CF_DecoderState_t *state, uint8 decode_size) { const uint8 *sptr; @@ -519,6 +737,14 @@ uint64 CF_DecodeIntegerInSize(CF_DecoderState_t *state, uint8 decode_size) return temp_val; } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeHeader + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeHeader(CF_DecoderState_t *state, CF_Logical_PduHeader_t *plh) { const CF_CFDP_PduHeader_t *peh; /* for decoding fixed sized fields */ @@ -549,6 +775,14 @@ void CF_CFDP_DecodeHeader(CF_DecoderState_t *state, CF_Logical_PduHeader_t *plh) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeFileDirectiveHeader + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeFileDirectiveHeader(CF_DecoderState_t *state, CF_Logical_PduFileDirectiveHeader_t *pfdir) { const CF_CFDP_PduFileDirectiveHeader_t *peh; @@ -563,6 +797,14 @@ void CF_CFDP_DecodeFileDirectiveHeader(CF_DecoderState_t *state, CF_Logical_PduF } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeLV + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeLV(CF_DecoderState_t *state, CF_Logical_Lv_t *pllv) { const CF_CFDP_lv_t *lv; @@ -575,6 +817,14 @@ void CF_CFDP_DecodeLV(CF_DecoderState_t *state, CF_Logical_Lv_t *pllv) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeTLV + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeTLV(CF_DecoderState_t *state, CF_Logical_Tlv_t *pltlv) { const CF_CFDP_tlv_t *tlv; @@ -601,6 +851,14 @@ void CF_CFDP_DecodeTLV(CF_DecoderState_t *state, CF_Logical_Tlv_t *pltlv) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeSegmentRequest + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeSegmentRequest(CF_DecoderState_t *state, CF_Logical_SegmentRequest_t *plseg) { const CF_CFDP_SegmentRequest_t *sr; /* for decoding fixed sized fields */ @@ -613,6 +871,14 @@ void CF_CFDP_DecodeSegmentRequest(CF_DecoderState_t *state, CF_Logical_SegmentRe } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeMd + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeMd(CF_DecoderState_t *state, CF_Logical_PduMd_t *plmd) { const CF_CFDP_PduMd_t *md; /* for decoding fixed sized fields */ @@ -630,6 +896,14 @@ void CF_CFDP_DecodeMd(CF_DecoderState_t *state, CF_Logical_PduMd_t *plmd) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeFileDataHeader + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeFileDataHeader(CF_DecoderState_t *state, bool with_meta, CF_Logical_PduFileDataHeader_t *plfd) { const CF_CFDP_PduFileDataHeader_t *fd; @@ -686,6 +960,14 @@ void CF_CFDP_DecodeFileDataHeader(CF_DecoderState_t *state, bool with_meta, CF_L } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeCrc + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeCrc(CF_DecoderState_t *state, uint32 *plcrc) { const CF_CFDP_uint32_t *pecrc; /* CFDP CRC values are 32-bit only, per blue book */ @@ -697,6 +979,14 @@ void CF_CFDP_DecodeCrc(CF_DecoderState_t *state, uint32 *plcrc) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeEof + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeEof(CF_DecoderState_t *state, CF_Logical_PduEof_t *pleof) { const CF_CFDP_PduEof_t *eof; /* for decoding fixed sized fields */ @@ -712,6 +1002,14 @@ void CF_CFDP_DecodeEof(CF_DecoderState_t *state, CF_Logical_PduEof_t *pleof) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeFin + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeFin(CF_DecoderState_t *state, CF_Logical_PduFin_t *plfin) { const CF_CFDP_PduFin_t *fin; /* for decoding fixed sized fields */ @@ -727,6 +1025,14 @@ void CF_CFDP_DecodeFin(CF_DecoderState_t *state, CF_Logical_PduFin_t *plfin) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeAck + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeAck(CF_DecoderState_t *state, CF_Logical_PduAck_t *plack) { const CF_CFDP_PduAck_t *ack; /* for decoding fixed sized fields */ @@ -742,6 +1048,14 @@ void CF_CFDP_DecodeAck(CF_DecoderState_t *state, CF_Logical_PduAck_t *plack) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeNak + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeNak(CF_DecoderState_t *state, CF_Logical_PduNak_t *plnak) { const CF_CFDP_PduNak_t *nak; /* for encoding fixed sized fields */ @@ -756,6 +1070,14 @@ void CF_CFDP_DecodeNak(CF_DecoderState_t *state, CF_Logical_PduNak_t *plnak) } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeAllTlv + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeAllTlv(CF_DecoderState_t *state, CF_Logical_TlvList_t *pltlv, uint8 limit) { pltlv->num_tlv = 0; @@ -785,6 +1107,14 @@ void CF_CFDP_DecodeAllTlv(CF_DecoderState_t *state, CF_Logical_TlvList_t *pltlv, } } +/*---------------------------------------------------------------- + * + * Function: CF_CFDP_DecodeAllSegments + * + * Application-scope internal function + * See description in cf_codec.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CFDP_DecodeAllSegments(CF_DecoderState_t *state, CF_Logical_SegmentList_t *plseg, uint8 limit) { plseg->num_segments = 0; diff --git a/fsw/src/cf_codec.h b/fsw/src/cf_codec.h index 314d8c0e1..d0edd4ae1 100644 --- a/fsw/src/cf_codec.h +++ b/fsw/src/cf_codec.h @@ -1,28 +1,27 @@ /************************************************************************ -** File: cf_cfdp.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application cfdp engine and packet parsing header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * CFDP protocol data structure encode/decode API declarations + */ #ifndef CF_CODEC_H #define CF_CODEC_H @@ -31,50 +30,116 @@ #include "cf_cfdp_pdu.h" #include "cf_logical_pdu.h" +/** + * @brief Tracks the current state of an encode or decode operation + * + * This encapsulates the common state between encode and decode + */ typedef struct CF_CodecState { - bool is_valid; - size_t next_offset; - size_t max_size; + bool is_valid; /**< whether decode is valid or not. Set false on end of decode or error condition. */ + size_t next_offset; /**< Offset of next byte to encode/decode, current position in PDU */ + size_t max_size; /**< Maximum number of bytes in the PDU */ } CF_CodecState_t; +/** + * @brief Current state of an encode operation + * + * State structure for encodes + */ typedef struct CF_EncoderState { - CF_CodecState_t codec_state; - uint8 *base; + CF_CodecState_t codec_state; /**< Common state */ + uint8 *base; /**< Pointer to start of encoded PDU data */ } CF_EncoderState_t; +/** + * @brief Current state of an decode operation + * + * State structure for decodes + */ typedef struct CF_DecoderState { - CF_CodecState_t codec_state; - const uint8 *base; + CF_CodecState_t codec_state; /**< Common state */ + const uint8 *base; /**< Pointer to start of encoded PDU data */ } CF_DecoderState_t; +/********************************************************************************* + * + * GENERAL UTILITY FUNCTIONS + * These functions and macros support the encode/decode API + * + *********************************************************************************/ + +/************************************************************************/ +/** + * @brief Checks if the codec is currently valid or not + * + * @param state Encoder/Decoder common state + * @retval true If encoder/decoder is still valid, has not reached end of PDU + * @retval false If encoder/decoder is not valid, has reached end of PDU or an error occurred + */ static inline bool CF_CFDP_CodecIsOK(const CF_CodecState_t *state) { return state->is_valid; } +/************************************************************************/ +/** + * @brief Sets a codec to the "done" state + * + * This may mean end of PDU data is reached, or that an error occurred + * + * @param state Encoder/Decoder common state + */ static inline void CF_CFDP_CodecSetDone(CF_CodecState_t *state) { state->is_valid = false; } +/************************************************************************/ +/** + * @brief Obtains the current position/offset within the PDU + * + * @param state Encoder/Decoder common state + * @return Current offset in PDU + */ static inline size_t CF_CFDP_CodecGetPosition(const CF_CodecState_t *state) { return state->next_offset; } +/************************************************************************/ +/** + * @brief Obtains the maximum size of the PDU being encoded/decoded + * + * @param state Encoder/Decoder common state + * @return Maximum size of PDU + */ static inline size_t CF_CFDP_CodecGetSize(const CF_CodecState_t *state) { return state->max_size; } +/************************************************************************/ +/** + * @brief Obtains the remaining size of the PDU being encoded/decoded + * + * @param state Encoder/Decoder common state + * @return Remaining size of PDU + */ static inline size_t CF_CFDP_CodecGetRemain(const CF_CodecState_t *state) { return (state->max_size - state->next_offset); } +/************************************************************************/ +/** + * @brief Resets a codec state + * + * @param state Encoder/Decoder common state + * @param max_size Maximum size of PDU + */ static inline void CF_CFDP_CodecReset(CF_CodecState_t *state, size_t max_size) { state->is_valid = true; @@ -82,23 +147,215 @@ static inline void CF_CFDP_CodecReset(CF_CodecState_t *state, size_t max_size) state->max_size = max_size; } -bool CF_CFDP_CodecCheckSize(CF_CodecState_t *state, size_t chunksize); -void *CF_CFDP_DoEncodeChunk(CF_EncoderState_t *state, size_t chunksize); -const void *CF_CFDP_DoDecodeChunk(CF_DecoderState_t *state, size_t chunksize); +/************************************************************************/ +/** + * @brief Advances the position by the indicated size, confirming the block will fit into the PDU + * + * On encode, this confirms there is enough available space to hold a block + * of the indicated size. On decode, this confirms that decoding the indicated + * number of bytes will not read beyond the end of data. + * + * If true, then the current position/offset is advanced by the indicated number of bytes + * If false, then the error flag is set, so that future calls to CF_CFDP_CodecIsOK will + * also return false. + * + * @note The error flag is sticky, meaning that if any encode/decode operation fails, + * all future encode/decode requests on the same state will also fail. Each encode/decode + * step must check the flag, and skip the operation if it is false. Reporting the error + * can be deferred to the final stage, and only done once. + * + * @param state Encoder/Decoder common state + * @param chunksize Size of next block to encode/decode + * @retval true If encode/deocde is possible, enough space exists + * @retval false If encode/decode is not possible, not enough space or prior error occurred + */ +bool CF_CFDP_CodecCheckSize(CF_CodecState_t *state, size_t chunksize); -uint8 CF_CFDP_GetValueEncodedSize(uint64 Value); +/************************************************************************/ +/** + * @brief Encode a block of data into the PDU + * + * Adds/Reserves space for a block of the given size in the current PDU + * + * @param state Encoder state object + * @param chunksize Size of block to encode + * @return Pointer to block, if successful + * @retval NULL if not successful (no space or other error). + */ +void *CF_CFDP_DoEncodeChunk(CF_EncoderState_t *state, size_t chunksize); + +/************************************************************************/ +/** + * @brief Decode a block of data from the PDU + * + * Deducts space for a block of the given size from the current PDU + * + * @param state Decoder state object + * @param chunksize Size of block to decode + * @return Pointer to block, if successful + * @retval NULL if not successful (no space or other error). + */ +const void *CF_CFDP_DoDecodeChunk(CF_DecoderState_t *state, size_t chunksize); +/************************************************************************/ +/** + * @brief Macro to encode a block of a given CFDP type into a PDU + * + * This is a wrapper around CF_CFDP_DoEncodeChunk() to encode the given data type, + * rather than a generic size. The sizeof() the type should reflect the _encoded_ + * size within the PDU. Specifically, this must only be used with the "CFDP" data + * types which are specifically designed to match the binary layout of the CFDP-defined + * header structures. + * + * @param state Encoder state object + * @param type Data type to encode, from cf_cfdp_pdu.h + * @return Pointer to block, if successful + * @retval NULL if not successful (no space or other error). + */ #define CF_ENCODE_FIXED_CHUNK(state, type) ((type *)CF_CFDP_DoEncodeChunk(state, sizeof(type))) + +/************************************************************************/ +/** + * @brief Macro to decode a block of a given CFDP type into a PDU + * + * This is a wrapper around CF_CFDP_DoDecodeChunk() to encode the given data type, + * rather than a generic size. The sizeof() the type should reflect the _encoded_ + * size within the PDU. Specifically, this must only be used with the "CFDP" data + * types which are specifically designed to match the binary layout of the CFDP-defined + * header structures. + * + * @param state Decoder state object + * @param type Data type to decode, from cf_cfdp_pdu.h + * @return Pointer to block, if successful + * @retval NULL if not successful (no space or other error). + */ #define CF_DECODE_FIXED_CHUNK(state, type) ((const type *)CF_CFDP_DoDecodeChunk(state, sizeof(type))) -#define CF_CODEC_IS_OK(s) CF_CFDP_CodecIsOK(&((s)->codec_state)) -#define CF_CODEC_SET_DONE(s) CF_CFDP_CodecSetDone(&((s)->codec_state)) +/************************************************************************/ +/** + * @brief Macro wrapper around CF_CFDP_CodecIsOK() + * + * Checks the state of either an encoder or decoder object + * This just simplifies the code, as same macro may be used with either + * an CF_EncoderState_t or CF_DecoderState_t object. + * + * @param s Encoder or Decoder state + */ +#define CF_CODEC_IS_OK(s) CF_CFDP_CodecIsOK(&((s)->codec_state)) + +/************************************************************************/ +/** + * @brief Macro wrapper around CF_CFDP_CodecSetDone() + * + * Sets the state of either an encoder or decoder object + * This just simplifies the code, as same macro may be used with either + * an CF_EncoderState_t or CF_DecoderState_t object. + * + * @param s Encoder or Decoder state + */ +#define CF_CODEC_SET_DONE(s) CF_CFDP_CodecSetDone(&((s)->codec_state)) + +/************************************************************************/ +/** + * @brief Macro wrapper around CF_CFDP_CodecGetPosition() + * + * Checks the position of either an encoder or decoder object + * This just simplifies the code, as same macro may be used with either + * an CF_EncoderState_t or CF_DecoderState_t object. + * + * @param s Encoder or Decoder state + */ #define CF_CODEC_GET_POSITION(s) CF_CFDP_CodecGetPosition(&((s)->codec_state)) -#define CF_CODEC_GET_REMAIN(s) CF_CFDP_CodecGetRemain(&((s)->codec_state)) -#define CF_CODEC_GET_SIZE(s) CF_CFDP_CodecGetSize(&((s)->codec_state)) +/************************************************************************/ +/** + * @brief Macro wrapper around CF_CFDP_CodecGetRemain() + * + * Checks the remainder of either an encoder or decoder object + * This just simplifies the code, as same macro may be used with either + * an CF_EncoderState_t or CF_DecoderState_t object. + * + * @param s Encoder or Decoder state + */ +#define CF_CODEC_GET_REMAIN(s) CF_CFDP_CodecGetRemain(&((s)->codec_state)) + +/************************************************************************/ +/** + * @brief Macro wrapper around CF_CFDP_CodecGetSize() + * + * Checks the size of either an encoder or decoder object + * This just simplifies the code, as same macro may be used with either + * an CF_EncoderState_t or CF_DecoderState_t object. + * + * @param s Encoder or Decoder state + */ +#define CF_CODEC_GET_SIZE(s) CF_CFDP_CodecGetSize(&((s)->codec_state)) + +/************************************************************************/ +/** + * @brief Gets the minimum number of octets that the given integer may be encoded in + * + * Based on the integer value, this computes the minimum number of bytes that must be + * allocated to that integer within a CFDP PDU. This is typically used for entity + * IDs and sequence numbers, where CFDP does not specify a specific size for these + * items. They may be encoded between 1 and 8 bytes, depending on the actual value + * is. + * + * @param Value Integer value that needs to be encoded + * @returns Minimum number of bytes that the value requires (between 1 and 8, inclusive) + */ +uint8 CF_CFDP_GetValueEncodedSize(uint64 Value); + +/************************************************************************/ +/** + * @brief Encodes the given integer value in the given number of octets + * + * This encodes an integer value in the specified number of octets. + * Use CF_CFDP_GetValueEncodedSize() to determine the minimum number of octets required + * for a given value. Using more than the minimum is OK, but will consume extra bytes. + * + * @warning This function does not error check the encode_size parameter, and will encode the + * size given, even if it results in an invalid value. Using fewer octets than the + * minimum reported by CF_CFDP_GetValueEncodedSize() will likely result in incorrect decoding + * at the receiver. + * + * @sa CF_DecodeIntegerInSize() for the inverse operation + * + * @param state Encoder state object + * @param value Integer value that needs to be encoded + * @param encode_size Number of octets to encode the value in (between 1 and 8, inclusive) + */ void CF_EncodeIntegerInSize(CF_EncoderState_t *state, uint64 value, uint8 encode_size); -/* + +/************************************************************************/ +/** + * @brief Decodes an integer value from the specified number of octets + * + * This decodes an integer value in the specified number of octets. The actual number of + * octets must be determined using another field in the PDU before calling this function. + * + * @warning This function will decode exactly the given number of octets. If this does not + * match actual encoded size, the return value will be wrong, and it will likely also + * throw off the decoding of any fields that follow this one. + * + * @sa CF_EncodeIntegerInSize() for the inverse operation + * + * @param state Encoder state object + * @param decode_size Number of octets that the value is encoded in (between 1 and 8, inclusive) + * @returns Decoded value + */ +uint64 CF_DecodeIntegerInSize(CF_DecoderState_t *state, uint8 decode_size); + +/********************************************************************************* + * + * ENCODE API + * + *********************************************************************************/ + +/************************************************************************/ +/** + * @brief Encodes a CFDP PDU base header block, bypassing the size field + * * On transmit side, the common/base header must be encoded in two parts, to deal * with the "total_size" field. The initial encoding of the the basic fields is * done as soon as it is known that a PDU of this type needs to be sent, but the @@ -109,37 +366,458 @@ void CF_EncodeIntegerInSize(CF_EncoderState_t *state, uint64 value, uint8 encode * separate function later to update the total_length to the correct value once the * remainder of encoding is done. Luckily, the total_length is in the first fixed * position binary blob so it is easy to update later. + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @sa CF_CFDP_EncodeHeaderFinalSize() for updating the length field once it is known + * + * @param state Encoder state object + * @param plh Pointer to logical PDU header data */ void CF_CFDP_EncodeHeaderWithoutSize(CF_EncoderState_t *state, CF_Logical_PduHeader_t *plh); + +/************************************************************************/ +/** + * @brief Updates an already-encoded PDU base header block with the final PDU size + * + * This function encodes the "data_encoded_length" field from the logical PDU structure + * into the encoded header block. The PDU will also be closed (set done) to indicate that + * no more data should be added. + * + * @note Unlike other encode operations, this function does not add any new blocks to the + * PDU. It only updates the already-encoded block at the beginning of the PDU, which must + * have been done by a prior call to CF_CFDP_EncodeHeaderWithoutSize(). + * + * @sa CF_CFDP_EncodeHeaderWithoutSize() for initially encoding the PDU header block + * + * @param state Encoder state object + * @param plh Pointer to logical PDU header data + */ void CF_CFDP_EncodeHeaderFinalSize(CF_EncoderState_t *state, CF_Logical_PduHeader_t *plh); + +/************************************************************************/ +/** + * @brief Encodes a CFDP file directive header block + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param pfdir Pointer to logical PDU file directive header data + */ void CF_CFDP_EncodeFileDirectiveHeader(CF_EncoderState_t *state, CF_Logical_PduFileDirectiveHeader_t *pfdir); + +/************************************************************************/ +/** + * @brief Encodes a single CFDP Length+Value (LV) pair + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param pllv Pointer to logical PDU LV header data + */ void CF_CFDP_EncodeLV(CF_EncoderState_t *state, CF_Logical_Lv_t *pllv); + +/************************************************************************/ +/** + * @brief Encodes a single CFDP Type+Length+Value (TLV) tuple + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @note Only the CF_CFDP_TLV_TYPE_ENTITY_ID TLV type is currently supported by this function, + * but other TLV types may be added in future versions as needed. + * + * @param state Encoder state object + * @param pltlv Pointer to single logical PDU TLV header data + */ void CF_CFDP_EncodeTLV(CF_EncoderState_t *state, CF_Logical_Tlv_t *pltlv); + +/************************************************************************/ +/** + * @brief Encodes a single CFDP Segment Request block + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param plseg Pointer to single logical PDU segment request header data + */ void CF_CFDP_EncodeSegmentRequest(CF_EncoderState_t *state, CF_Logical_SegmentRequest_t *plseg); + +/************************************************************************/ +/** + * @brief Encodes a list of CFDP Type+Length+Value tuples + * + * This invokes CF_CFDP_EncodeTLV() for all TLV values in the given list. + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param pltlv Pointer to logical PDU TLV header data + */ void CF_CFDP_EncodeAllTlv(CF_EncoderState_t *state, CF_Logical_TlvList_t *pltlv); + +/************************************************************************/ +/** + * @brief Encodes a list of CFDP Segment Request blocks + * + * This invokes CF_CFDP_EncodeSegmentRequest() for all segments in the given list. + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param plseg Pointer to logical PDU segment request header data + */ void CF_CFDP_EncodeAllSegments(CF_EncoderState_t *state, CF_Logical_SegmentList_t *plseg); + +/************************************************************************/ +/** + * @brief Encodes a CFDP Metadata (MD) header block + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @note this encode includes the LV pairs for source and destination file names, which are + * logically part of the overall MD block. + * + * @param state Encoder state object + * @param plmd Pointer to logical PDU metadata header data + */ void CF_CFDP_EncodeMd(CF_EncoderState_t *state, CF_Logical_PduMd_t *plmd); + +/************************************************************************/ +/** + * @brief Encodes a CFDP File Data (FD) header block + * + * This only encodes the FD header fields, specifically the data offset (required) and any + * metadata fields, if indicated. This does _not_ encode any actual file data. + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param with_meta Whether to include optional continuation and segment request fields (always false currently) + * @param plfd Pointer to logical PDU file header data + */ void CF_CFDP_EncodeFileDataHeader(CF_EncoderState_t *state, bool with_meta, CF_Logical_PduFileDataHeader_t *plfd); + +/************************************************************************/ +/** + * @brief Encodes a CFDP End-of-File (EOF) header block + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @note this encode includes any TLV values which are indicated in the logical data structure + * + * @param state Encoder state object + * @param pleof Pointer to logical PDU EOF header data + */ void CF_CFDP_EncodeEof(CF_EncoderState_t *state, CF_Logical_PduEof_t *pleof); + +/************************************************************************/ +/** + * @brief Encodes a CFDP Final (FIN) header block + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @note this encode includes any TLV values which are indicated in the logical data structure + * + * @param state Encoder state object + * @param plfin Pointer to logical PDU FIN header data + */ void CF_CFDP_EncodeFin(CF_EncoderState_t *state, CF_Logical_PduFin_t *plfin); + +/************************************************************************/ +/** + * @brief Encodes a CFDP Acknowledge (ACK) header block + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param plack Pointer to logical PDU ACK header data + */ void CF_CFDP_EncodeAck(CF_EncoderState_t *state, CF_Logical_PduAck_t *plack); + +/************************************************************************/ +/** + * @brief Encodes a CFDP Non-Acknowledge (NAK) header block + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @note this encode includes any Segment Request values which are indicated in the logical data structure + * + * @param state Encoder state object + * @param plnak Pointer to logical PDU NAK header data + */ void CF_CFDP_EncodeNak(CF_EncoderState_t *state, CF_Logical_PduNak_t *plnak); + +/************************************************************************/ +/** + * @brief Encodes a CFDP CRC/Checksum + * + * The data in the logical header will be appended to the encoded PDU at the current position + * + * If the encoder is in an error state, nothing is encoded, and the state of the + * encoder is not changed. + * + * @param state Encoder state object + * @param plcrc Pointer to logical CRC value + */ void CF_CFDP_EncodeCrc(CF_EncoderState_t *state, uint32 *plcrc); -uint64 CF_DecodeIntegerInSize(CF_DecoderState_t *state, uint8 decode_size); -void CF_CFDP_DecodeHeader(CF_DecoderState_t *state, CF_Logical_PduHeader_t *plh); -void CF_CFDP_DecodeFileDirectiveHeader(CF_DecoderState_t *state, CF_Logical_PduFileDirectiveHeader_t *pfdir); -void CF_CFDP_DecodeLV(CF_DecoderState_t *state, CF_Logical_Lv_t *pllv); -void CF_CFDP_DecodeTLV(CF_DecoderState_t *state, CF_Logical_Tlv_t *pltlv); -void CF_CFDP_DecodeSegmentRequest(CF_DecoderState_t *state, CF_Logical_SegmentRequest_t *plseg); -void CF_CFDP_DecodeAllTlv(CF_DecoderState_t *state, CF_Logical_TlvList_t *pltlv, uint8 limit); -void CF_CFDP_DecodeAllSegments(CF_DecoderState_t *state, CF_Logical_SegmentList_t *plseg, uint8 limit); -void CF_CFDP_DecodeMd(CF_DecoderState_t *state, CF_Logical_PduMd_t *plmd); -void CF_CFDP_DecodeFileDataHeader(CF_DecoderState_t *state, bool with_meta, CF_Logical_PduFileDataHeader_t *plfd); -void CF_CFDP_DecodeEof(CF_DecoderState_t *state, CF_Logical_PduEof_t *pleof); -void CF_CFDP_DecodeFin(CF_DecoderState_t *state, CF_Logical_PduFin_t *plfin); -void CF_CFDP_DecodeAck(CF_DecoderState_t *state, CF_Logical_PduAck_t *plack); -void CF_CFDP_DecodeNak(CF_DecoderState_t *state, CF_Logical_PduNak_t *plnak); -void CF_CFDP_DecodeCrc(CF_DecoderState_t *state, uint32 *pcrc); +/********************************************************************************* + * + * DECODE API + * + *********************************************************************************/ + +/************************************************************************/ +/** + * @brief Decodes a CFDP base PDU header + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @note On decode the entire base header is decoded in a single call, the size + * will be decoded like any other field. + * + * @param state Decoder state object + * @param plh Pointer to logical PDU base header data + */ +void CF_CFDP_DecodeHeader(CF_DecoderState_t *state, CF_Logical_PduHeader_t *plh); + +/************************************************************************/ +/** + * @brief Decodes a CFDP file directive header block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param pfdir Pointer to logical PDU file directive header data + */ +void CF_CFDP_DecodeFileDirectiveHeader(CF_DecoderState_t *state, CF_Logical_PduFileDirectiveHeader_t *pfdir); + +/************************************************************************/ +/** + * @brief Decodes a single CFDP Length+Value (LV) pair + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param pllv Pointer to single logical PDU LV data + */ +void CF_CFDP_DecodeLV(CF_DecoderState_t *state, CF_Logical_Lv_t *pllv); + +/************************************************************************/ +/** + * @brief Decodes a single CFDP Type+Length+Value (TLV) tuple + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param pltlv Pointer to single logical PDU TLV data + */ +void CF_CFDP_DecodeTLV(CF_DecoderState_t *state, CF_Logical_Tlv_t *pltlv); + +/************************************************************************/ +/** + * @brief Decodes a single CFDP Segment Request block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param plseg Pointer to single logical PDU segment request header data + */ +void CF_CFDP_DecodeSegmentRequest(CF_DecoderState_t *state, CF_Logical_SegmentRequest_t *plseg); + +/************************************************************************/ +/** + * @brief Decodes a list of CFDP Type+Length+Value tuples + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param pltlv Pointer to logical PDU TLV header data + * @param limit Maximum number of TLV objects to decode + */ +void CF_CFDP_DecodeAllTlv(CF_DecoderState_t *state, CF_Logical_TlvList_t *pltlv, uint8 limit); + +/************************************************************************/ +/** + * @brief Decodes a list of CFDP Segment Request blocks + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param plseg Pointer to logical PDU segment request header data + * @param limit Maximum number of Segment Request objects to decode + */ +void CF_CFDP_DecodeAllSegments(CF_DecoderState_t *state, CF_Logical_SegmentList_t *plseg, uint8 limit); + +/************************************************************************/ +/** + * @brief Decodes a CFDP Metadata (MD) header block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param plmd Pointer to logical PDU metadata header data + */ +void CF_CFDP_DecodeMd(CF_DecoderState_t *state, CF_Logical_PduMd_t *plmd); + +/************************************************************************/ +/** + * @brief Decodes a CFDP File Data (FD) header block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param with_meta Whether to include optional continuation and segment request fields (always false currently) + * @param plfd Pointer to logical PDU file header data + */ +void CF_CFDP_DecodeFileDataHeader(CF_DecoderState_t *state, bool with_meta, CF_Logical_PduFileDataHeader_t *plfd); + +/************************************************************************/ +/** + * @brief Decodes a CFDP End-of-File (EOF) header block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param pleof Pointer to logical PDU EOF header data + */ +void CF_CFDP_DecodeEof(CF_DecoderState_t *state, CF_Logical_PduEof_t *pleof); + +/************************************************************************/ +/** + * @brief Decodes a CFDP Final (FIN) header block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param plfin Pointer to logical PDU FIN header data + */ +void CF_CFDP_DecodeFin(CF_DecoderState_t *state, CF_Logical_PduFin_t *plfin); + +/************************************************************************/ +/** + * @brief Decodes a CFDP Acknowledge (ACK) header block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param plack Pointer to logical PDU ACK header data + */ +void CF_CFDP_DecodeAck(CF_DecoderState_t *state, CF_Logical_PduAck_t *plack); + +/************************************************************************/ +/** + * @brief Decodes a CFDP Non-Acknowledge (NAK) header block + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param plnak Pointer to logical PDU NAK header data + */ +void CF_CFDP_DecodeNak(CF_DecoderState_t *state, CF_Logical_PduNak_t *plnak); + +/************************************************************************/ +/** + * @brief Decodes a CFDP CRC/Checksum + * + * The data will be decoded from the encoded PDU at the current position and + * the logical fields will be saved to the given data structure + * + * If the encoder is in an error state, nothing is decoded, and the state of the + * decoder is not changed. + * + * @param state Decoder state object + * @param plcrc Pointer to logical CRC value + */ +void CF_CFDP_DecodeCrc(CF_DecoderState_t *state, uint32 *pcrc); #endif /* !CF_CODEC_H */ diff --git a/fsw/src/cf_crc.c b/fsw/src/cf_crc.c index 94a395a8b..0ced9b5cd 100644 --- a/fsw/src/cf_crc.c +++ b/fsw/src/cf_crc.c @@ -1,62 +1,59 @@ /************************************************************************ -** File: cf_crc.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application CRC calculation source file -** -** This is a streaming CRC calculator. Data can all be given at once for -** a result or it can trickle in. -** -** This file is intended to be generic and usable by other apps. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application CRC calculation source file + * + * This is a streaming CRC calculator. Data can all be given at once for + * a result or it can trickle in. + * + * This file is intended to be generic and usable by other apps. + */ #include "cfe.h" #include "cf_verify.h" #include "cf_crc.h" #include -/************************************************************************/ -/** \brief Start a CRC streamable digest. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CRC_Start + * + * Application-scope internal function + * See description in cf_crc.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CRC_Start(CF_Crc_t *c) { memset(c, 0, sizeof(*c)); } -/************************************************************************/ -/** \brief Digest a chunk for crc calculation. -** -** \par Description -** Does the CRC calculation, and stores an index into the given -** 4-byte word in case the input was not evenly divisible for 4. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CRC_Digest + * + * Application-scope internal function + * See description in cf_crc.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CRC_Digest(CF_Crc_t *c, const uint8 *data, int len) { int i = 0; @@ -74,18 +71,14 @@ void CF_CRC_Digest(CF_Crc_t *c, const uint8 *data, int len) } } -/************************************************************************/ -/** \brief Finalize a crc calculation. -** -** \par Description -** Checks the index and if it isn't 0, does the final calculations -** on the bytes in the shift register. After this call is made, the -** result field of the structure holds the result. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_CRC_Finalize + * + * Application-scope internal function + * See description in cf_crc.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_CRC_Finalize(CF_Crc_t *c) { if (c->index) diff --git a/fsw/src/cf_crc.h b/fsw/src/cf_crc.h index 2bf49f743..5fd14f78b 100644 --- a/fsw/src/cf_crc.h +++ b/fsw/src/cf_crc.h @@ -1,34 +1,36 @@ /************************************************************************ -** File: cf_crc.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application CRC calculation header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application CRC calculation header file + */ #ifndef CF_CRC_H #define CF_CRC_H #include "cfe.h" +/** + * @brief CRC state object + */ typedef struct CF_Crc { uint32 working; @@ -36,8 +38,47 @@ typedef struct CF_Crc uint8 index; } CF_Crc_t; -extern void CF_CRC_Start(CF_Crc_t *c); -extern void CF_CRC_Digest(CF_Crc_t *c, const uint8 *data, int len); -extern void CF_CRC_Finalize(CF_Crc_t *c); +/************************************************************************/ +/** @brief Start a CRC streamable digest. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param c CRC object to operate on + */ +void CF_CRC_Start(CF_Crc_t *c); + +/************************************************************************/ +/** @brief Digest a chunk for crc calculation. + * + * @par Description + * Does the CRC calculation, and stores an index into the given + * 4-byte word in case the input was not evenly divisible for 4. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param c CRC object to operate on + * @param data Pointer to data to digest + * @param len Length of data to digest + * + */ +void CF_CRC_Digest(CF_Crc_t *c, const uint8 *data, int len); + +/************************************************************************/ +/** @brief Finalize a crc calculation. + * + * @par Description + * Checks the index and if it isn't 0, does the final calculations + * on the bytes in the shift register. After this call is made, the + * result field of the structure holds the result. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param c CRC object to operate on + * + */ +void CF_CRC_Finalize(CF_Crc_t *c); #endif /* !CF_CRC_H */ diff --git a/fsw/src/cf_events.h b/fsw/src/cf_events.h index 79ab0d3fc..11c20bea7 100644 --- a/fsw/src/cf_events.h +++ b/fsw/src/cf_events.h @@ -1,31 +1,31 @@ /************************************************************************ -** File: cf_events.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application event id definition header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ -#ifndef _CF_EVENTS_H_ -#define _CF_EVENTS_H_ +/** + * @file + * + * The CF Application event id definition header file + */ + +#ifndef CF_EVENTS_H +#define CF_EVENTS_H #define CF_EID_ERR_ASSERT 1 @@ -148,4 +148,4 @@ #define CF_EID_ERR_CMD_GCMD_CC 137 #define CF_EID_ERR_CMD_WHIST_WRITE 138 -#endif /* !_CF_EVENTS_H_ */ +#endif /* !CF_EVENTS_H */ diff --git a/fsw/src/cf_field.h b/fsw/src/cf_field.h index 66b8e5b84..047708ae2 100644 --- a/fsw/src/cf_field.h +++ b/fsw/src/cf_field.h @@ -1,30 +1,30 @@ /************************************************************************ -** File: cf_fields.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application field macro header file -** -** -** -*************************************************************************/ -#ifndef CF_FIELD_COMMON__H -#define CF_FIELD_COMMON__H + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application field macro header file + */ + +#ifndef CF_FIELD_COMMON_H +#define CF_FIELD_COMMON_H #define xstr(s) str(s) #define str(s) #s @@ -68,4 +68,4 @@ static inline void CF_FieldSetVal(uint8 *dest, uint8 shift, uint8 mask, uint8 va #define FGV(SRC, NAME) CF_FieldGetVal((SRC).octets, (NAME).shift, (NAME).mask) #define FSV(DEST, NAME, VAL) CF_FieldSetVal((DEST).octets, (NAME).shift, (NAME).mask, VAL) -#endif /* !CF_FIELD_COMMON__H */ +#endif /* !CF_FIELD_COMMON_H */ diff --git a/fsw/src/cf_logical_pdu.h b/fsw/src/cf_logical_pdu.h index 7692b14d8..40ef94a04 100644 --- a/fsw/src/cf_logical_pdu.h +++ b/fsw/src/cf_logical_pdu.h @@ -1,23 +1,21 @@ /************************************************************************ -** File: cf_logical_pdu.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file diff --git a/fsw/src/cf_msg.h b/fsw/src/cf_msg.h index 77a3a6958..398c8289a 100644 --- a/fsw/src/cf_msg.h +++ b/fsw/src/cf_msg.h @@ -1,28 +1,27 @@ /************************************************************************ -** File: cf_msg.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application message definitions header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application message definitions header file + */ #ifndef CF_MSG_H #define CF_MSG_H @@ -123,8 +122,8 @@ typedef struct CF_ConfigPacket } CF_ConfigPacket_t; /**************************************** -** CF app command packet command codes -****************************************/ + * CF app command packet command codes + ***************************************/ /* NOTE: these are what was in the original app (may have slightly different names) * Not sure that we need to implement all these for cf 3.0 */ @@ -159,8 +158,8 @@ typedef enum } CF_CMDS; /**************************** -** CF Command Formats ** -*****************************/ + * CF Command Formats ** + ****************************/ typedef struct CF_NoArgsCmd { CFE_MSG_CommandHeader_t cmd_header; @@ -254,5 +253,4 @@ typedef struct CF_TransactionCmd uint8 spare[3]; /* To make structure a multiple of uint32 */ } CF_TransactionCmd_t; - #endif /* !CF_MSG_H */ diff --git a/fsw/src/cf_timer.c b/fsw/src/cf_timer.c index 2cf664119..a266a95fb 100644 --- a/fsw/src/cf_timer.c +++ b/fsw/src/cf_timer.c @@ -1,33 +1,32 @@ /************************************************************************ -** File: cf_timer.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application timer source file -** -** A timer in CF is really just a structure that holds a counter that -** indicates the timer expired when it reaches 0. The goal is that -** any timer is driven by the scheduler ticks. There is no reason -** we need any finer grained resolution than this for CF. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application timer source file + * + * A timer in CF is really just a structure that holds a counter that + * indicates the timer expired when it reaches 0. The goal is that + * any timer is driven by the scheduler ticks. There is no reason + * we need any finer grained resolution than this for CF. + */ #include "cfe.h" #include "cf_verify.h" @@ -35,59 +34,53 @@ #include "cf_app.h" #include "cf_assert.h" -/* NOTE: sub-second resolution is not required */ - -/************************************************************************/ -/** \brief Converts seconds into scheduler ticks. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retstmt Number of ticks for the given seconds. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Timer_Sec2Ticks + * + * Application-scope internal function + * See description in cf_timer.h for argument/return detail + * + *-----------------------------------------------------------------*/ uint32 CF_Timer_Sec2Ticks(CF_Timer_Seconds_t sec) { return sec * CF_AppData.config_table->ticks_per_second; } -/************************************************************************/ -/** \brief Initialize a timer with a relative number of seconds. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Timer_InitRelSec + * + * Application-scope internal function + * See description in cf_timer.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_Timer_InitRelSec(CF_Timer_t *t, uint32 rel_sec) { t->tick = CF_Timer_Sec2Ticks(rel_sec); } -/************************************************************************/ -/** \brief Check if a timer has expired. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -** \returns -** \retstmt 1 if expired; otherwise 0. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Timer_Expired + * + * Application-scope internal function + * See description in cf_timer.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_Timer_Expired(const CF_Timer_t *t) { return !t->tick; } -/************************************************************************/ -/** \brief Notify a timer object a tick has occurred. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_Timer_Tick + * + * Application-scope internal function + * See description in cf_timer.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_Timer_Tick(CF_Timer_t *t) { CF_Assert(t->tick); diff --git a/fsw/src/cf_timer.h b/fsw/src/cf_timer.h index 77b0dd0b1..421b41e19 100644 --- a/fsw/src/cf_timer.h +++ b/fsw/src/cf_timer.h @@ -1,56 +1,100 @@ /************************************************************************ -** File: cf_timer.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application timer header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application timer header file + */ #ifndef CF_TIMER_H #define CF_TIMER_H #include "cfe.h" -/* NOTE: We expect ticks to be 100/sec, so using uint32 for sec could have a bounds condition +/** + * @brief Type for a timer tick count + * + * @note We expect ticks to be 100/sec, so using uint32 for sec could have a bounds condition * with uint32. But, we don't expect to use more than 400,000,000 seconds for any reason so - * let's just live with it. */ + * let's just live with it. + */ typedef uint32 CF_Timer_Ticks_t; + +/** + * @brief Type for a timer number of seconds + */ typedef uint32 CF_Timer_Seconds_t; +/** + * @brief Basic CF timer object + */ typedef struct CF_Timer { CF_Timer_Ticks_t tick; /* expires when reaches 0 */ } CF_Timer_t; -/* initialize a timer +/************************************************************************/ +/** @brief Initialize a timer with a relative number of seconds. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. * - * If the abs_sec value is greater than current time, then the timer will - * be immediately expired. */ -void CF_Timer_InitRelSec(CF_Timer_t *c, CF_Timer_Seconds_t rel_sec); + * @param t Timer object to initialize + * @param rel_sec Relative number of seconds + */ +void CF_Timer_InitRelSec(CF_Timer_t *t, CF_Timer_Seconds_t rel_sec); -/* returns 1 if expired */ +/************************************************************************/ +/** @brief Check if a timer has expired. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Timer object to check + * + * @returns status code indicating whether timer has expired + * @retval 1 if expired + * @retval 0 if not expired + */ int CF_Timer_Expired(const CF_Timer_t *t); +/************************************************************************/ +/** @brief Notify a timer object a tick has occurred. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Timer object to tick + */ void CF_Timer_Tick(CF_Timer_t *t); +/************************************************************************/ +/** @brief Converts seconds into scheduler ticks. + * + * @par Assumptions, External Events, and Notes: + * sub-second resolution is not required + * + * @param sec Number of seconds + * + * @returns Number of ticks for the given seconds. + */ uint32 CF_Timer_Sec2Ticks(CF_Timer_Seconds_t sec); #endif /* !CF_TIMER_H */ diff --git a/fsw/src/cf_utils.c b/fsw/src/cf_utils.c index 04912526c..69195f4f9 100644 --- a/fsw/src/cf_utils.c +++ b/fsw/src/cf_utils.c @@ -1,30 +1,29 @@ /************************************************************************ -** File: cf_utils.c -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application general utility functions source file -** -** Various odds and ends are put here. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application general utility functions source file + * + * Various odds and ends are put here. + */ #include "cf_app.h" #include "cf_verify.h" @@ -37,18 +36,14 @@ #define LINEBUF_LEN ((CF_FILENAME_MAX_LEN * 2) + 128) -/************************************************************************/ -/** \brief Find an unused transaction on a channel. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retstmt Returns a free transaction, or NULL if none are available. \endcode -** \endreturns -** -*************************************************************************/ -/* finds an unused transaction and returns with it on no Q */ +/*---------------------------------------------------------------- + * + * Function: CF_FindUnusedTransaction + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_Transaction_t *CF_FindUnusedTransaction(CF_Channel_t *c) { CF_Assert(c); @@ -87,30 +82,28 @@ CF_Transaction_t *CF_FindUnusedTransaction(CF_Channel_t *c) } } -/************************************************************************/ -/** \brief Returns a history structure back to its unused state. -** -** \par Description -** There's nothing to do currently other than remove the history -** from its current queue and put it back on CF_QueueIdx_HIST_FREE. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. h must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_ResetHistory + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_ResetHistory(CF_Channel_t *c, CF_History_t *h) { CF_CList_Remove_Ex(c, CF_QueueIdx_HIST, &h->cl_node); CF_CList_InsertBack_Ex(c, CF_QueueIdx_HIST_FREE, &h->cl_node); } -/************************************************************************/ -/** \brief Frees and resets a transaction and returns it for later use. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_FreeTransaction + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_FreeTransaction(CF_Transaction_t *t) { uint8 c = t->chan_num; @@ -123,18 +116,14 @@ void CF_FreeTransaction(CF_Transaction_t *t) CF_CList_InsertBack_Ex(&CF_AppData.engine.channels[c], CF_QueueIdx_FREE, &t->cl_node); } -/************************************************************************/ -/** \brief List traversal function to check if the desired sequence number matches. -** -** \par Assumptions, External Events, and Notes: -** context must not be NULL. n must not be NULL. -** -** \returns -** \retcode 1 when it's found, which terminates list traversal \endcode -** \retcode 0 when it isn't found, which causes list traversal to continue \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_FindTransactionBySequenceNumber_Impl + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_FindTransactionBySequenceNumber_Impl(CF_CListNode_t *n, CF_Traverse_TransSeqArg_t *context) { CF_Transaction_t *t = container_of(n, CF_Transaction_t, cl_node); @@ -149,21 +138,14 @@ int CF_FindTransactionBySequenceNumber_Impl(CF_CListNode_t *n, CF_Traverse_Trans return ret; } -/************************************************************************/ -/** \brief Finds an active transaction by sequence number. -** -** \par Description -** This function traverses the active rx, pending, txa, and txw -** transaction and looks for the requested transaction. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retstmt The given transaction is returned if found, otherwise NULL. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_FindTransactionBySequenceNumber + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ CF_Transaction_t *CF_FindTransactionBySequenceNumber(CF_Channel_t *c, CF_TransactionSeq_t transaction_sequence_number, CF_EntityId_t src_eid) { @@ -190,22 +172,14 @@ CF_Transaction_t *CF_FindTransactionBySequenceNumber(CF_Channel_t *c, CF_Transac return ret; } -/************************************************************************/ -/** \brief Walks through a history queue and builds a human readable representation of it. -** -** \par Description -** This function is used as both a list traversal function and a direct -** function call. -** -** \par Assumptions, External Events, and Notes: -** n must not be NULL. context must not be NULL. -** -** \returns -** \retcode 1 when it's found, which terminates list traversal \endcode -** \retcode 0 when it isn't found, which causes list traversal to continue \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_TraverseHistory + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_TraverseHistory(CF_CListNode_t *n, CF_Traverse_WriteFileArg_t *context) { static const char *dstr[] = {"RX", "TX"}; @@ -236,18 +210,14 @@ int CF_TraverseHistory(CF_CListNode_t *n, CF_Traverse_WriteFileArg_t *context) return CF_CLIST_CONT; } -/************************************************************************/ -/** \brief Walk over all transactions and print information from their history. -** -** \par Assumptions, External Events, and Notes: -** None -** -** \returns -** \retcode 1 when it's found, which terminates list traversal \endcode -** \retcode 0 when it isn't found, which causes list traversal to continue \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_TraverseTransactions + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_TraverseTransactions(CF_CListNode_t *n, CF_Traverse_WriteFileArg_t *context) { CF_Transaction_t *t = container_of(n, CF_Transaction_t, cl_node); @@ -266,17 +236,14 @@ int CF_TraverseTransactions(CF_CListNode_t *n, CF_Traverse_WriteFileArg_t *conte return CF_CLIST_CONT; } -/************************************************************************/ -/** \brief Write a transaction-based queue's transaction history to a file. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retstmt 0 on success; 1 on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WriteQueueDataToFile + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_WriteQueueDataToFile(int32 fd, CF_Channel_t *c, CF_QueueIdx_t q) { CF_Traverse_WriteFileArg_t arg = {fd, 0, 0}; @@ -284,17 +251,14 @@ int32 CF_WriteQueueDataToFile(int32 fd, CF_Channel_t *c, CF_QueueIdx_t q) return arg.result; } -/************************************************************************/ -/** \brief Write a history-based queue's transaction history to a file. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retstmt 0 on success; 1 on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WriteHistoryQueueDataToFile + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_WriteHistoryQueueDataToFile(int32 fd, CF_Channel_t *c, CF_Direction_t dir) { CF_Traverse_WriteFileArg_t arg = {fd, 0, 0}; @@ -302,21 +266,14 @@ int32 CF_WriteHistoryQueueDataToFile(int32 fd, CF_Channel_t *c, CF_Direction_t d return arg.result; } -/************************************************************************/ -/** \brief Searches for the first transaction with a lower priority than given. -** -** \par Description -** that the config table being loaded has correct data. -** -** \par Assumptions, External Events, and Notes: -** node must not be NULL. context must not be NULL. -** -** \returns -** \retcode 1 when it's found, which terminates list traversal \endcode -** \retcode 0 when it isn't found, which causes list traversal to continue \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_PrioSearch + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_PrioSearch(CF_CListNode_t *node, void *context) { CF_Transaction_t *t = container_of(node, CF_Transaction_t, cl_node); @@ -335,19 +292,14 @@ int CF_PrioSearch(CF_CListNode_t *node, void *context) return CF_CLIST_CONT; } -/************************************************************************/ -/** \brief Insert a transaction into a priority sorted transaction queue. -** -** \par Description -** This function works by walking the queue in reverse to find a -** transaction with a higher priority than the given transaction. -** The given transaction is then inserted after that one, since it -** would be the next lower priority. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_InsertSortPrio + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_InsertSortPrio(CF_Transaction_t *t, CF_QueueIdx_t q) { int insert_back = 0; @@ -384,21 +336,14 @@ void CF_InsertSortPrio(CF_Transaction_t *t, CF_QueueIdx_t q) t->flags.com.q_index = q; } -/************************************************************************/ -/** \brief List traversal function performs operation on every active transaction. -** -** \par Description -** Called on every transaction via list traversal. Calls another function -** on that transaction. -** -** \par Assumptions, External Events, and Notes: -** n must not be NULL. args must not be NULL. -** -** \returns -** \retstmt Always 0 for do not exit early. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_TraverseAllTransactions_Impl + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_TraverseAllTransactions_Impl(CF_CListNode_t *n, CF_TraverseAll_Arg_t *args) { CF_Transaction_t *t = container_of(n, CF_Transaction_t, cl_node); @@ -407,17 +352,14 @@ int CF_TraverseAllTransactions_Impl(CF_CListNode_t *n, CF_TraverseAll_Arg_t *arg return CF_CLIST_CONT; } -/************************************************************************/ -/** \brief Traverses all transactions on all active queues and performs an operation on them. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. fn must be a valid function. context must not be NULL. -** -** \returns -** \retstmt Number of transactions traversed, or anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_TraverseAllTransactions + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_TraverseAllTransactions(CF_Channel_t *c, CF_TraverseAllTransactions_fn_t fn, void *context) { CF_TraverseAll_Arg_t args = {fn, context, 0}; @@ -428,17 +370,14 @@ int CF_TraverseAllTransactions(CF_Channel_t *c, CF_TraverseAllTransactions_fn_t return args.counter; } -/************************************************************************/ -/** \brief Traverses all transactions on all channels and performs an operation on them. -** -** \par Assumptions, External Events, and Notes: -** fn must be a valid function. context must not be NULL. -** -** \returns -** \retstmt Number of transactions traversed, or anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_TraverseAllTransactions_All_Channels + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int CF_TraverseAllTransactions_All_Channels(CF_TraverseAllTransactions_fn_t fn, void *context) { int i; @@ -448,17 +387,14 @@ int CF_TraverseAllTransactions_All_Channels(CF_TraverseAllTransactions_fn_t fn, return ret; } -/************************************************************************/ -/** \brief Wrap the filesystem open call with a perf counter. -** -** \par Assumptions, External Events, and Notes: -** fname must not be NULL. -** -** \returns -** \retstmt Valid file descriptor, or anything else on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WrappedOpenCreate + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_WrappedOpenCreate(osal_id_t *fd, const char *fname, int32 flags, int32 access) { int32 ret; @@ -469,13 +405,14 @@ int32 CF_WrappedOpenCreate(osal_id_t *fd, const char *fname, int32 flags, int32 return ret; } -/************************************************************************/ -/** \brief Wrap the filesystem close call with a perf counter. -** -** \par Assumptions, External Events, and Notes: -** None -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WrappedClose + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ void CF_WrappedClose(osal_id_t fd) { int32 ret; @@ -491,18 +428,14 @@ void CF_WrappedClose(osal_id_t fd) } } -/************************************************************************/ -/** \brief Wrap the filesystem read call with a perf counter. -** -** \par Assumptions, External Events, and Notes: -** buf must not be NULL. -** -** \returns -** \retstmt >=0 number of bytes read on success \endcode -** \retstmt <0 on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WrappedRead + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_WrappedRead(osal_id_t fd, void *buf, size_t read_size) { int32 ret; @@ -513,18 +446,14 @@ int32 CF_WrappedRead(osal_id_t fd, void *buf, size_t read_size) return ret; } -/************************************************************************/ -/** \brief Wrap the filesystem write call with a perf counter. -** -** \par Assumptions, External Events, and Notes: -** buf must not be NULL. -** -** \returns -** \retstmt >=0 number of bytes read on success \endcode -** \retstmt <0 on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WrappedWrite + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_WrappedWrite(osal_id_t fd, const void *buf, size_t write_size) { int32 ret; @@ -535,18 +464,14 @@ int32 CF_WrappedWrite(osal_id_t fd, const void *buf, size_t write_size) return ret; } -/************************************************************************/ -/** \brief Wrap the filesystem lseek call with a perf counter. -** -** \par Assumptions, External Events, and Notes: -** fname must not be NULL. -** -** \returns -** \retstmt >=0 the current file position in bytes. \endcode -** \retstmt <0 on error. \endcode -** \endreturns -** -*************************************************************************/ +/*---------------------------------------------------------------- + * + * Function: CF_WrappedLseek + * + * Application-scope internal function + * See description in cf_utils.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 CF_WrappedLseek(osal_id_t fd, off_t offset, int mode) { int ret; diff --git a/fsw/src/cf_utils.h b/fsw/src/cf_utils.h index 9a98c13f9..830991324 100644 --- a/fsw/src/cf_utils.h +++ b/fsw/src/cf_utils.h @@ -1,28 +1,27 @@ /************************************************************************ -** File: cf_utils.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application utils header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application utils header file + */ #ifndef CF_UTILS_H #define CF_UTILS_H @@ -31,13 +30,25 @@ #include "cf_app.h" #include "cf_assert.h" +/** + * @brief Argument structure for use with CList_Traverse() + * + * This identifies a specific transaction sequence number and entity ID + * The transaction pointer is set by the implementation + */ typedef struct CF_Traverse_TransSeqArg { CF_TransactionSeq_t transaction_sequence_number; CF_EntityId_t src_eid; - CF_Transaction_t *t; /* out param */ + CF_Transaction_t *t; /**< output transaction pointer */ } CF_Traverse_TransSeqArg_t; +/** + * @brief Argument structure for use with CList_Traverse() + * + * This is used for writing status files. It contains a designated + * file descriptor for output and counters. + */ typedef struct CF_Traverse_WriteFileArg { osal_id_t fd; @@ -45,19 +56,35 @@ typedef struct CF_Traverse_WriteFileArg int32 counter; } CF_Traverse_WriteFileArg_t; +/** + * @brief Callback function type for use with CF_TraverseAllTransactions() + * + * @param t Pointer to current transaction being traversed + * @param context Opaque object passed from initial call + */ typedef void (*CF_TraverseAllTransactions_fn_t)(CF_Transaction_t *t, void *context); +/** + * @brief Argument structure for use with CF_TraverseAllTransactions() + * + * This basically allows for running a CF_Traverse on several lists at once + */ typedef struct CF_TraverseAll_Arg { - CF_TraverseAllTransactions_fn_t fn; - void *context; - int counter; + CF_TraverseAllTransactions_fn_t fn; /**< internal callback to use for each CList_Traverse */ + void *context; /**< opaque object to pass to internal callback */ + int counter; /**< Running tally of all nodes traversed from all lists */ } CF_TraverseAll_Arg_t; +/** + * @brief Argument structure for use with CF_CList_Traverse_R() + * + * This is for searching for transactions of a specific priority + */ typedef struct CF_Traverse_PriorityArg { - CF_Transaction_t *t; /* OUT: holds value of transaction with which to call CF_CList_InsertAfter on */ - uint8 priority; /* seeking this priority */ + CF_Transaction_t *t; /**< OUT: holds value of transaction with which to call CF_CList_InsertAfter on */ + uint8 priority; /**< seeking this priority */ } CF_Traverse_PriorityArg_t; /* free a transaction from the queue it's on. @@ -109,82 +136,292 @@ static inline void CF_CList_InsertBack_Ex(CF_Channel_t *c, CF_QueueIdx_t index, } /************************************************************************/ -/** \brief Find an unused transaction on a channel. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retstmt Returns a free transaction, or NULL if none are available. \endcode -** \endreturns -** -*************************************************************************/ -/* finds an unused transaction and returns with it on no Q */ +/** @brief Find an unused transaction on a channel. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param c Pointer to the CF channel + * + * @returns Pointer to a free transaction + * @retval NULL if no free transactions available. + */ CF_Transaction_t *CF_FindUnusedTransaction(CF_Channel_t *c); /************************************************************************/ -/** \brief Returns a history structure back to its unused state. -** -** \par Description -** There's nothing to do currently other than remove the history -** from its current queue and put it back on CF_QueueIdx_HIST_FREE. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. h must not be NULL. -** -*************************************************************************/ +/** @brief Returns a history structure back to its unused state. + * + * @par Description + * There's nothing to do currently other than remove the history + * from its current queue and put it back on CF_QueueIdx_HIST_FREE. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. h must not be NULL. + * + * @param c Pointer to the CF channel + * @param h Pointer to the history entry + */ void CF_ResetHistory(CF_Channel_t *c, CF_History_t *h); /************************************************************************/ -/** \brief Frees and resets a transaction and returns it for later use. -** -** \par Assumptions, External Events, and Notes: -** t must not be NULL. -** -*************************************************************************/ +/** @brief Frees and resets a transaction and returns it for later use. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + */ void CF_FreeTransaction(CF_Transaction_t *t); /************************************************************************/ -/** \brief Finds an active transaction by sequence number. -** -** \par Description -** This function traverses the active rx, pending, txa, and txw -** transaction and looks for the requested transaction. -** -** \par Assumptions, External Events, and Notes: -** c must not be NULL. -** -** \returns -** \retstmt The given transaction is returned if found, otherwise NULL. \endcode -** \endreturns -** -*************************************************************************/ +/** @brief Finds an active transaction by sequence number. + * + * @par Description + * This function traverses the active rx, pending, txa, and txw + * transaction and looks for the requested transaction. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param c Pointer to the CF channel + * @param transaction_sequence_number Sequence number to find + * @param src_eid Entity ID associated with sequence number + * + * @returns Pointer to the given transaction if found + * @retval NULL if the transaction is not found + */ CF_Transaction_t *CF_FindTransactionBySequenceNumber(CF_Channel_t *c, CF_TransactionSeq_t transaction_sequence_number, CF_EntityId_t src_eid); +/************************************************************************/ +/** @brief List traversal function to check if the desired sequence number matches. + * + * @par Assumptions, External Events, and Notes: + * context must not be NULL. n must not be NULL. + * + * @param n Pointer to node currently being traversed + * @param context Pointer to state object passed through from initial call + * + * @retval 1 when it's found, which terminates list traversal + * @retval 0 when it isn't found, which causes list traversal to continue + * + */ int CF_FindTransactionBySequenceNumber_Impl(CF_CListNode_t *n, CF_Traverse_TransSeqArg_t *context); +/************************************************************************/ +/** @brief Write a transaction-based queue's transaction history to a file. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param fd Open File descriptor to write to + * @param c Pointer to associated CF channel object + * @param q Queue Index to write + * + * @retval 0 on success + * @retval 1 on error + */ int32 CF_WriteQueueDataToFile(int32 fd, CF_Channel_t *c, CF_QueueIdx_t q); + +/************************************************************************/ +/** @brief Write a history-based queue's transaction history to a file. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. + * + * @param fd Open File descriptor to write to + * @param c Pointer to associated CF channel object + * @param dir Direction to match/filter + * + * @retval 0 on success + * @retval 1 on error + */ int32 CF_WriteHistoryQueueDataToFile(int32 fd, CF_Channel_t *c, CF_Direction_t dir); +/************************************************************************/ +/** @brief Insert a transaction into a priority sorted transaction queue. + * + * @par Description + * This function works by walking the queue in reverse to find a + * transaction with a higher priority than the given transaction. + * The given transaction is then inserted after that one, since it + * would be the next lower priority. + * + * @par Assumptions, External Events, and Notes: + * t must not be NULL. + * + * @param t Pointer to the transaction object + * @param q Index of queue to insert into + */ void CF_InsertSortPrio(CF_Transaction_t *t, CF_QueueIdx_t q); -/* these return the number of transactions traversed */ +/************************************************************************/ +/** @brief Traverses all transactions on all active queues and performs an operation on them. + * + * @par Assumptions, External Events, and Notes: + * c must not be NULL. fn must be a valid function. context must not be NULL. + * + * @param c Channel to operate on + * @param fn Callback to invoke for all traversed transactions + * @param context Opaque object to pass to all callbacks + * + * @returns Number of transactions traversed + */ int CF_TraverseAllTransactions(CF_Channel_t *c, CF_TraverseAllTransactions_fn_t fn, void *context); + +/************************************************************************/ +/** @brief Traverses all transactions on all channels and performs an operation on them. + * + * @par Assumptions, External Events, and Notes: + * fn must be a valid function. context must not be NULL. + * + * @param fn Callback to invoke for all traversed transactions + * @param context Opaque object to pass to all callbacks + * + * @returns Number of transactions traversed + */ int CF_TraverseAllTransactions_All_Channels(CF_TraverseAllTransactions_fn_t fn, void *context); +/************************************************************************/ +/** @brief List traversal function performs operation on every active transaction. + * + * @par Description + * Called on every transaction via list traversal. Calls another function + * on that transaction. + * + * @par Assumptions, External Events, and Notes: + * n must not be NULL. args must not be NULL. + * + * @param n Node being currently traversed + * @param args Intermediate context object from initial call + * + * @retval 0 for do not exit early (always continue) + */ int CF_TraverseAllTransactions_Impl(CF_CListNode_t *n, CF_TraverseAll_Arg_t *args); + +/************************************************************************/ +/** @brief Walks through a history queue and builds a human readable representation of it. + * + * @par Description + * This function is used as both a list traversal function and a direct + * function call. + * + * @par Assumptions, External Events, and Notes: + * n must not be NULL. context must not be NULL. + * + * @param n Node being currently traversed + * @param context Pointer to object indicating the file descriptor and related information + * + * @retval CF_CLIST_CONT if everything is going well + * @retval CF_CLIST_EXIT if a write error occurred, which means traversal should stop + */ int CF_TraverseHistory(CF_CListNode_t *n, CF_Traverse_WriteFileArg_t *context); + +/************************************************************************/ +/** @brief Walk over all transactions and print information from their history. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @param n Node being currently traversed + * @param context Pointer to object indicating the file descriptor and related information + * + * @retval CF_CLIST_CONT if everything is going well + * @retval CF_CLIST_EXIT if a write error occurred, which means traversal should stop + */ int CF_TraverseTransactions(CF_CListNode_t *n, CF_Traverse_WriteFileArg_t *context); -int32 CF_WriteQueueDataToFile(int32 fd, CF_Channel_t *c, CF_QueueIdx_t q); -int32 CF_WriteHistoryQueueDataToFile(int32 fd, CF_Channel_t *c, CF_Direction_t dir); -int CF_PrioSearch(CF_CListNode_t *node, void *context); +/************************************************************************/ +/** @brief Searches for the first transaction with a lower priority than given. + * + * @par Assumptions, External Events, and Notes: + * node must not be NULL. context must not be NULL. + * + * @param n Node being currently traversed + * @param context Pointer to CF_Traverse_PriorityArg_t object indicating the priority to search for + * + * @retval CF_CLIST_EXIT when it's found, which terminates list traversal + * @retval CF_CLIST_CONT when it isn't found, which causes list traversal to continue + * + */ +int CF_PrioSearch(CF_CListNode_t *node, void *context); +/************************************************************************/ +/** @brief Wrap the filesystem open call with a perf counter. + * + * @par Assumptions, External Events, and Notes: + * fname must not be NULL. + * + * @sa OS_OpenCreate() for parameter descriptions + * + * @param fd Passed directly to underlying OSAL call + * @param fname Passed directly to underlying OSAL call + * @param flags Passed directly to underlying OSAL call + * @param access Passed directly to underlying OSAL call + * + * @returns Status code from OSAL + */ int32 CF_WrappedOpenCreate(osal_id_t *fd, const char *fname, int32 flags, int32 access); -void CF_WrappedClose(osal_id_t fd); + +/************************************************************************/ +/** @brief Wrap the filesystem close call with a perf counter. + * + * @par Assumptions, External Events, and Notes: + * None + * + * @sa OS_close() for parameter descriptions + * + * @param fd Passed directly to underlying OSAL call + * + */ +void CF_WrappedClose(osal_id_t fd); + +/************************************************************************/ +/** @brief Wrap the filesystem read call with a perf counter. + * + * @par Assumptions, External Events, and Notes: + * buf must not be NULL. + * + * @sa OS_read() for parameter descriptions + * + * @param fd Passed directly to underlying OSAL call + * @param buf Passed directly to underlying OSAL call + * @param read_size Passed directly to underlying OSAL call + * + * @returns Status code from OSAL (byte count or error code) + */ int32 CF_WrappedRead(osal_id_t fd, void *buf, size_t read_size); + +/************************************************************************/ +/** @brief Wrap the filesystem write call with a perf counter. + * + * @par Assumptions, External Events, and Notes: + * buf must not be NULL. + * + * @sa OS_write() for parameter descriptions + * + * @param fd Passed directly to underlying OSAL call + * @param buf Passed directly to underlying OSAL call + * @param write_size Passed directly to underlying OSAL call + * + * @returns Status code from OSAL (byte count or error code) + */ int32 CF_WrappedWrite(osal_id_t fd, const void *buf, size_t write_size); + +/************************************************************************/ +/** @brief Wrap the filesystem lseek call with a perf counter. + * + * @par Assumptions, External Events, and Notes: + * fname must not be NULL. + * + * @sa OS_lseek() for parameter descriptions + * + * @param fd Passed directly to underlying OSAL call + * @param offset Passed directly to underlying OSAL call + * @param mode Passed directly to underlying OSAL call + * + * @returns Status code from OSAL (byte count or error code) + */ int32 CF_WrappedLseek(osal_id_t fd, off_t offset, int mode); #endif /* !CF_UTILS_H */ diff --git a/fsw/src/cf_verify.h b/fsw/src/cf_verify.h index 0e4adcc68..114b64422 100644 --- a/fsw/src/cf_verify.h +++ b/fsw/src/cf_verify.h @@ -1,28 +1,27 @@ /************************************************************************ -** File: cf_verify.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application configuration verification header -** -** Revision 1.0 2020/07/16 sseeger -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CF Application configuration verification header + */ #ifndef CF_VERIFY_H #define CF_VERIFY_H diff --git a/fsw/src/cf_version.h b/fsw/src/cf_version.h index 209284c4c..803371626 100644 --- a/fsw/src/cf_version.h +++ b/fsw/src/cf_version.h @@ -1,28 +1,28 @@ /************************************************************************ -** File: cf_version.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** Purpose: -** The CFS CFDP (CF) Application header file containing version number -** -** Notes: -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ + +/** + * @file + * + * The CFS CFDP (CF) Application header file containing version number + */ + #ifndef CF_VERSION_H #define CF_VERSION_H @@ -31,7 +31,3 @@ #define CF_REVISION 0 #endif /* CF_VERSION_H */ - -/************************/ -/* End of File Comment */ -/************************/ diff --git a/unit-test/cf_chunk_tests.c b/unit-test/cf_chunk_tests.c index f46fcaedd..1adee502c 100644 --- a/unit-test/cf_chunk_tests.c +++ b/unit-test/cf_chunk_tests.c @@ -361,7 +361,7 @@ void Test_CF_Chunks_EraseChunk_ErasesLastChunkFrom_chunks_AndDecrements_count(vo /* NOTE: memmove should be wrapped for stubbing, but proving problematic. * CF_Chunks_InsertChunk tests will use the memmove call for now */ -void Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_CF_max_chunks(void) +void Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_max_chunks(void) { // /* Arrange */ // CF_ChunkList_t dummy_chunks; @@ -370,18 +370,18 @@ void Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_ // CF_Chunk_t arg_chunk = {0}; // arg_chunks->count = Any_uint32(); - // arg_chunks->CF_max_chunks = arg_chunks->count; + // arg_chunks->max_chunks = arg_chunks->count; // /* Act */ // CF_Chunks_InsertChunk(arg_chunks, arg_index_before, arg_chunk); // /* Assert */ UtAssert_MIR("JIRA: GSFCCFS-1733 CF_Assert"); -} /* end Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_CF_max_chunks */ +} /* end Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_max_chunks */ -/* NOTE: Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_CF_max_chunks not required +/* NOTE: Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_max_chunks not required * but desired */ -// void Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_CF_max_chunks(void) +// void Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_max_chunks(void) // { // /* Arrange */ // CF_ChunkList_t dummy_chunks; @@ -391,14 +391,14 @@ void Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_ // CF_Chunk_t* arg_chunk = &dummy_chunk; // arg_chunks->count = Any_uint32_Except(UINT32_MAX); -// arg_chunks->CF_max_chunks = Any_uint32_GreaterThan(arg_chunks->count); +// arg_chunks->max_chunks = Any_uint32_GreaterThan(arg_chunks->count); // /* Act */ // //CF_Chunks_InsertChunk(arg_chunks, arg_index_before, arg_chunk); // /* Assert */ // UtAssert_MIR("JIRA: GSFCCFS-1733 CF_Assert"); -// } /* end Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_CF_max_chunks */ +// } /* end Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_max_chunks */ void Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoEmpty_chunks(void) { @@ -411,7 +411,7 @@ void Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoEmpty_chunks(void) const CF_Chunk_t *arg_chunk; arg_chunks->count = 0; - arg_chunks->CF_max_chunks = + arg_chunks->max_chunks = UINT32_MAX; /* UINT32_MAX maybe unresonable but keeps it out of the way with the CF_Assert */ arg_chunks->chunks = initial_chunks; @@ -447,7 +447,7 @@ void Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoStartOfSingle_chunks(void) initial_chunks[0] = initial_start_chunk; arg_chunks->count = 1; - arg_chunks->CF_max_chunks = + arg_chunks->max_chunks = UINT32_MAX; /* UINT32_MAX maybe unresonable but keeps it out of the way with the CF_Assert */ arg_chunks->chunks = initial_chunks; @@ -487,7 +487,7 @@ void Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoEndOfSingle_chunks(void) initial_chunks[0] = initial_start_chunk; arg_chunks->count = 1; - arg_chunks->CF_max_chunks = + arg_chunks->max_chunks = UINT32_MAX; /* UINT32_MAX maybe unresonable but keeps it out of the way with the CF_Assert */ arg_chunks->chunks = initial_chunks; @@ -544,7 +544,7 @@ void Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoSome_chunks(void) } arg_chunks->count = initial_count; - arg_chunks->CF_max_chunks = + arg_chunks->max_chunks = UINT32_MAX; /* UINT32_MAX maybe unresonable but keeps it out of the way with the CF_Assert */ arg_chunks->chunks = initial_chunks; @@ -749,8 +749,8 @@ void Test_CF_Chunks_CombinePrevious_Asserts_i_GivenIsEqTo_chunks_CF_max_Chunks(v // CF_Chunk_t* arg_chunk = &dummy_chunk; // CF_ChunkIdx_t local_result; - // arg_chunks->CF_max_chunks = Any_uint32_Except(0); - // arg_i = arg_chunks->CF_max_chunks; + // arg_chunks->max_chunks = Any_uint32_Except(0); + // arg_i = arg_chunks->max_chunks; // /* Act */ // local_result = CF_Chunks_CombinePrevious(arg_chunks, arg_i, arg_chunk); @@ -770,8 +770,8 @@ void Test_CF_Chunks_CombinePrevious_Asserts_i_GivenIsEqTo_chunks_CF_max_Chunks(v // CF_Chunk_t* arg_chunk = &dummy_chunk; // CF_ChunkIdx_t local_result; -// arg_chunks->CF_max_chunks = Any_uint32_Except(0); -// arg_i = Any_uint32_GreaterThan(arg_chunks->CF_max_chunks); +// arg_chunks->max_chunks = Any_uint32_Except(0); +// arg_i = Any_uint32_GreaterThan(arg_chunks->max_chunks); // /* Act */ // //local_result = CF_Chunks_CombinePrevious(arg_chunks, arg_i, arg_chunk); @@ -790,9 +790,9 @@ void Test_CF_Chunks_CombinePrevious_Given_i_Is_0_Return_0(void) CF_Chunk_t *arg_chunk = &dummy_chunk; int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_Except(0); - arg_i = 0; - arg_chunks->count = Any_uint32_GreaterThan(0); + arg_chunks->max_chunks = Any_uint32_Except(0); + arg_i = 0; + arg_chunks->count = Any_uint32_GreaterThan(0); /* Act */ local_result = CF_Chunks_CombinePrevious(arg_chunks, arg_i, arg_chunk); @@ -811,9 +811,9 @@ void Test_CF_Chunks_CombinePrevious_Given_chunks_count_Is_0_Return_0(void) CF_Chunk_t *arg_chunk = &dummy_chunk; int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_Except(0); - arg_i = Any_uint32_LessThan(arg_chunks->CF_max_chunks); - arg_chunks->count = 0; + arg_chunks->max_chunks = Any_uint32_Except(0); + arg_i = Any_uint32_LessThan(arg_chunks->max_chunks); + arg_chunks->count = 0; /* Act */ local_result = CF_Chunks_CombinePrevious(arg_chunks, arg_i, arg_chunk); @@ -832,9 +832,9 @@ void Test_CF_Chunks_CombinePrevious_Given_i_Is_0_And_chunks_count_Is_0_Return_0( CF_Chunk_t *arg_chunk = &dummy_chunk; int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_Except(0); - arg_i = 0; - arg_chunks->count = 0; + arg_chunks->max_chunks = Any_uint32_Except(0); + arg_i = 0; + arg_chunks->count = 0; /* Act */ local_result = CF_Chunks_CombinePrevious(arg_chunks, arg_i, arg_chunk); @@ -860,7 +860,7 @@ void Test_CF_Chunks_CombinePrevious_GivenIndexMinusOne_chunks_chunks_ValueFor_pr CF_ChunkSize_t dummy_size = Any_uint32_LessThan(UINT32_MAX / 2); int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); + arg_chunks->max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); arg_chunks->count = dummy_chunks_count; arg_chunks->chunks = dummy_chunks_chunks; arg_chunks->chunks[arg_i - 1].offset = dummy_offset; @@ -894,7 +894,7 @@ void Test_CF_Chunks_CombinePrevious_GivenIndexMinusOne_chunks_chunks_ValueFor_pr CF_ChunkSize_t dummy_size = Any_uint32_LessThan(UINT32_MAX / 2); int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); + arg_chunks->max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); arg_chunks->count = dummy_chunks_count; arg_chunks->chunks = dummy_chunks_chunks; arg_chunks->chunks[arg_i - 1].offset = dummy_offset; @@ -929,7 +929,7 @@ void Test_CF_Chunks_CombinePrevious_GivenIndexMinusOne_chunks_chunks_ValueFor_pr CF_ChunkSize_t dummy_size = Any_uint32_LessThan(UINT32_MAX / 2); int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); + arg_chunks->max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); arg_chunks->count = dummy_chunks_count; arg_chunks->chunks = dummy_chunks_chunks; arg_chunks->chunks[arg_i - 1].offset = dummy_offset; @@ -964,7 +964,7 @@ void Test_CF_Chunks_CombinePrevious_GivenIndexMinusOne_chunks_chunks_ValueFor_pr CF_ChunkSize_t dummy_size = Any_uint32_LessThan(UINT32_MAX / 2); int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); + arg_chunks->max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); arg_chunks->count = dummy_chunks_count; arg_chunks->chunks = dummy_chunks_chunks; arg_chunks->chunks[arg_i - 1].offset = dummy_offset; @@ -999,7 +999,7 @@ void Test_CF_Chunks_CombinePrevious_GivenIndexMinusOne_chunks_chunks_ValueFor_pr CF_ChunkSize_t initial_size = Any_uint32_LessThan(UINT32_MAX / 2); int local_result = Any_int_Except(0); - arg_chunks->CF_max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); + arg_chunks->max_chunks = Any_uint32_GreaterThan(dummy_chunks_count); arg_chunks->count = dummy_chunks_count; arg_chunks->chunks = dummy_chunks_chunks; arg_chunks->chunks[arg_i - 1].offset = dummy_offset; @@ -1353,8 +1353,8 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_non0_CallTo_CF_C CF_Chunk_t dummy_chunks_chunks[10] = {{0}}; /* 10 repeated for dummy_chunks for build ability */ CF_ChunkList_t dummy_chunks; - arg_chunks = &dummy_chunks; - arg_chunks->CF_max_chunks = UINT32_MAX; + arg_chunks = &dummy_chunks; + arg_chunks->max_chunks = UINT32_MAX; arg_chunks->count = dummy_chunks_count; initial_i = Any_uint32_LessThan(arg_chunks->count); @@ -1392,8 +1392,8 @@ void Test_CF_Chunks_Insert_CombinesNextSuccessButCombinePreviousSuccessCalls_CF_ CF_Chunk_t dummy_chunks_chunks[10] = {{0}}; /* 10 repeated for dummy_chunks for build ability */ CF_ChunkList_t dummy_chunks; - arg_chunks = &dummy_chunks; - arg_chunks->CF_max_chunks = UINT32_MAX; + arg_chunks = &dummy_chunks; + arg_chunks->max_chunks = UINT32_MAX; arg_chunks->count = dummy_chunks_count; arg_i = Any_uint32_LessThan(arg_chunks->count - 1) + 1; /* -1 then +1 to ensure at least 1 */ @@ -1429,8 +1429,8 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chun CF_Chunk_t dummy_chunks_chunks[10] = {{0}}; /* 10 repeated for dummy_chunks for build ability */ CF_ChunkList_t dummy_chunks; - arg_chunks = &dummy_chunks; - arg_chunks->CF_max_chunks = UINT32_MAX; + arg_chunks = &dummy_chunks; + arg_chunks->max_chunks = UINT32_MAX; arg_chunks->count = dummy_chunks_count; arg_i = arg_chunks->count; @@ -1468,8 +1468,8 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chun CF_Chunk_t dummy_chunks_chunks[10] = {{0}}; /* 10 repeated for dummy_chunks for build ability */ CF_ChunkList_t dummy_chunks; - arg_chunks = &dummy_chunks; - arg_chunks->CF_max_chunks = UINT32_MAX; + arg_chunks = &dummy_chunks; + arg_chunks->max_chunks = UINT32_MAX; arg_chunks->count = dummy_chunks_count; arg_i = arg_chunks->count; @@ -1494,7 +1494,7 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chun Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsLessThan_chunks_CF_max_Chunks_Call_CF_Chunks_InsertChunk */ -void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing( +void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing( void) { /* Arrange */ @@ -1508,8 +1508,8 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chun CF_Chunk_t dummy_chunks_chunks[10] = {{0}}; /* 10 repeated for dummy_chunks for build ability */ CF_ChunkList_t dummy_chunks; - arg_chunks = &dummy_chunks; - arg_chunks->CF_max_chunks = 3; + arg_chunks = &dummy_chunks; + arg_chunks->max_chunks = 3; arg_chunks->count = dummy_chunks_count; arg_i = arg_chunks->count; @@ -1534,10 +1534,10 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chun UtAssert_True(arg_chunks->count == dummy_chunks_count, "chunks->count is %u and should be %u (value before call)", arg_chunks->count, dummy_chunks_count); } /* end - Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing + Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing */ -void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_And_CF_Chunks_InsertChunk( +void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_And_CF_Chunks_InsertChunk( void) { /* Arrange */ @@ -1551,8 +1551,8 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chun CF_Chunk_t dummy_chunks_chunks[10] = {{0}}; /* 10 repeated for dummy_chunks for build ability */ CF_ChunkList_t dummy_chunks; - arg_chunks = &dummy_chunks; - arg_chunks->CF_max_chunks = 3; + arg_chunks = &dummy_chunks; + arg_chunks->max_chunks = 3; arg_chunks->count = dummy_chunks_count; arg_i = arg_chunks->count; @@ -1579,7 +1579,7 @@ void Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chun UtAssert_True(arg_chunks->count == dummy_chunks_count, "chunks->count is %u and should be %u (value before call)", arg_chunks->count, dummy_chunks_count); } /* end - Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_And_CF_Chunks_InsertChunk + Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_And_CF_Chunks_InsertChunk */ /* end CF_Chunks_Insert tests */ @@ -1891,45 +1891,45 @@ void Test_CF_Chunks_GetFirstChunk_WhenGiven_chunks_count_Is_Any_index_t_ReturnFi ** *******************************************************************************/ -void Test_CF_Chunks_Init_AssertsBecauseGiven_CF_max_chunks_Is_0(void) +void Test_CF_Chunks_Init_AssertsBecauseGiven_max_chunks_Is_0(void) { // /* Arrange */ // CF_ChunkList_t dummy_chunks; // CF_ChunkList_t* arg_chunks = &dummy_chunks; - // CF_ChunkIdx_t arg_CF_max_chunks = Any_uint16() + 2; /* 2-65537, uint16 is used instead of CF_ChunkIdx_t + // CF_ChunkIdx_t arg_max_chunks = Any_uint16() + 2; /* 2-65537, uint16 is used instead of CF_ChunkIdx_t // to have a reasonably decent size for the test without being too large (segfault) */ CF_Chunk_t* arg_chunks_mem; // /* Act */ - // CF_ChunkListInit(arg_chunks, arg_CF_max_chunks, arg_chunks_mem); + // CF_ChunkListInit(arg_chunks, arg_max_chunks, arg_chunks_mem); // /* Assert */ UtAssert_MIR("JIRA: GSFCCFS-1733 CF_Assert"); -} /* end Test_CF_Chunks_Init_AssertsBecauseGiven_CF_max_chunks_Is_0 */ +} /* end Test_CF_Chunks_Init_AssertsBecauseGiven_max_chunks_Is_0 */ -void Test_CF_Chunks_Init_SetGiven_chunks_CF_max_chunks_ToGiven_CF_max_chunks(void) +void Test_CF_Chunks_Init_SetGiven_chunks_max_chunks_ToGiven_max_chunks(void) { /* Arrange */ CF_ChunkList_t dummy_chunks; CF_ChunkList_t *arg_chunks = &dummy_chunks; - CF_ChunkIdx_t arg_CF_max_chunks = + CF_ChunkIdx_t arg_max_chunks = Any_uint16() + 2; /* 2-65537, uint8 is used instead of CF_ChunkIdx_t to have a reasonably decent size for the test without being too large (segfault) */ - CF_Chunk_t arg_chunks_mem[arg_CF_max_chunks]; + CF_Chunk_t arg_chunks_mem[arg_max_chunks]; arg_chunks->count = 0; /* Act */ - CF_ChunkListInit(arg_chunks, arg_CF_max_chunks, arg_chunks_mem); + CF_ChunkListInit(arg_chunks, arg_max_chunks, arg_chunks_mem); /* Assert */ - UtAssert_UINT32_EQ(arg_chunks->CF_max_chunks, arg_CF_max_chunks); + UtAssert_UINT32_EQ(arg_chunks->max_chunks, arg_max_chunks); UtAssert_ADDRESS_EQ(arg_chunks->chunks, arg_chunks_mem); /* Assert Unstubbable - CF_ChunkListReset */ UtAssert_ZERO(arg_chunks->count); - UtAssert_MemCmpValue(arg_chunks->chunks, 0x00, sizeof(*arg_chunks->chunks) * arg_CF_max_chunks, - "The chunks, %lu bytes (sizeof(*chunks->chunks)*chunks->CF_max_chunks), were all set to 0", - sizeof(CF_Chunk_t) * arg_CF_max_chunks); -} /* end Test_CF_Chunks_Init_SetGiven_chunks_CF_max_chunks_ToGiven_CF_max_chunks */ + UtAssert_MemCmpValue(arg_chunks->chunks, 0x00, sizeof(*arg_chunks->chunks) * arg_max_chunks, + "The chunks, %lu bytes (sizeof(*chunks->chunks)*chunks->max_chunks), were all set to 0", + sizeof(CF_Chunk_t) * arg_max_chunks); +} /* end Test_CF_Chunks_Init_SetGiven_chunks_max_chunks_ToGiven_max_chunks */ /* CF_ChunkListInit tests */ @@ -1939,30 +1939,30 @@ void Test_CF_Chunks_Init_SetGiven_chunks_CF_max_chunks_ToGiven_CF_max_chunks(voi ** *******************************************************************************/ -void Test_CF_ChunksReset_Set_count_To_0_Keeps_CF_max_chunks_AndMemsets_chunks_ToAll_0(void) +void Test_CF_ChunksReset_Set_count_To_0_Keeps_max_chunks_AndMemsets_chunks_ToAll_0(void) { /* Arrange */ CF_ChunkList_t dummy_chunks; CF_ChunkList_t *arg_chunks = &dummy_chunks; - CF_ChunkIdx_t initial_CF_max_chunks = + CF_ChunkIdx_t initial_max_chunks = Any_uint16() + 2; /* 2-65537, uint8 is used instead of CF_ChunkIdx_t to have a reasonably decent size for the test without being too large (segfault) */ - CF_Chunk_t dummy_chunks_chunks[initial_CF_max_chunks]; + CF_Chunk_t dummy_chunks_chunks[initial_max_chunks]; - arg_chunks->count = Any_index_t(); - arg_chunks->CF_max_chunks = initial_CF_max_chunks; - arg_chunks->chunks = dummy_chunks_chunks; + arg_chunks->count = Any_index_t(); + arg_chunks->max_chunks = initial_max_chunks; + arg_chunks->chunks = dummy_chunks_chunks; /* Act */ CF_ChunkListReset(arg_chunks); /* Assert */ UtAssert_ZERO(arg_chunks->count); - UtAssert_UINT32_EQ(arg_chunks->CF_max_chunks, initial_CF_max_chunks); - UtAssert_MemCmpValue(arg_chunks->chunks, 0x00, sizeof(CF_Chunk_t) * initial_CF_max_chunks, - "The chunks, %lu bytes (sizeof(CF_Chunk_t)*chunks->CF_max_chunks), were all set to 0", - sizeof(CF_Chunk_t) * initial_CF_max_chunks); -} /* end Test_CF_ChunksReset_Set_count_To_0_Keeps_CF_max_chunks_AndMemsets_chunks_ToAll_0 */ + UtAssert_UINT32_EQ(arg_chunks->max_chunks, initial_max_chunks); + UtAssert_MemCmpValue(arg_chunks->chunks, 0x00, sizeof(CF_Chunk_t) * initial_max_chunks, + "The chunks, %lu bytes (sizeof(CF_Chunk_t)*chunks->max_chunks), were all set to 0", + sizeof(CF_Chunk_t) * initial_max_chunks); +} /* end Test_CF_ChunksReset_Set_count_To_0_Keeps_max_chunks_AndMemsets_chunks_ToAll_0 */ /* CF_ChunkListReset tests */ @@ -2394,12 +2394,12 @@ void add_CF_Chunks_EraseChunk_tests(void) void add_CF_Chunks_InsertChunk_tests(void) { - UtTest_Add(Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_CF_max_chunks, + UtTest_Add(Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_max_chunks, cf_chunk_tests_Setup, cf_chunk_tests_Teardown, - "Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_CF_max_chunks"); - // UtTest_Add(Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_CF_max_chunks, + "Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsEqTo_chunks_max_chunks"); + // UtTest_Add(Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_max_chunks, // cf_chunk_tests_Setup, cf_chunk_tests_Teardown, - // "Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_CF_max_chunks"); + // "Test_CF_Chunks_InsertChunk_AssertsBecause_Given_chunks_count_IsGreaterThan_chunks_max_chunks"); UtTest_Add(Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoEmpty_chunks, cf_chunk_tests_Setup, cf_chunk_tests_Teardown, "Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoEmpty_chunks"); UtTest_Add(Test_CF_Chunks_InsertChunk_PutGiven_chunk_IntoStartOfSingle_chunks, cf_chunk_tests_Setup, @@ -2541,15 +2541,15 @@ void add_CF_Chunks_Insert_tests(void) "Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_" "chunks_count_IsLessThan_chunks_CF_max_Chunks_Call_CF_Chunks_InsertChunk"); UtTest_Add( - Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing, + Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing, cf_chunk_tests_Setup, cf_chunk_tests_Teardown, "Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_" - "chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing"); + "chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsGreaterThan_chunk_size_DoNothing"); UtTest_Add( - Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_And_CF_Chunks_InsertChunk, + Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_And_CF_Chunks_InsertChunk, cf_chunk_tests_Setup, cf_chunk_tests_Teardown, "Test_CF_Chunks_Insert_CallTo_CF_Chunks_CombineNext_Returns_0_CallTo_CF_Chunks_CombinePrevious_Returns_0_And_" - "chunks_count_IsGreaterThan_CF_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_" + "chunks_count_IsGreaterThan_max_chunks_And_smallest_c_size_IsLessThan_chunk_size_Call_CF_Chunks_EraseChunk_" "And_CF_Chunks_InsertChunk"); } /* end add_CF_Chunks_Insert_tests */ @@ -2600,17 +2600,17 @@ void add_CF_Chunks_GetFirstChunk_tests(void) void add_CF_Chunks_Init_tests(void) { - UtTest_Add(Test_CF_Chunks_Init_AssertsBecauseGiven_CF_max_chunks_Is_0, cf_chunk_tests_Setup, - cf_chunk_tests_Teardown, "Test_CF_Chunks_Init_AssertsBecauseGiven_CF_max_chunks_Is_0"); - UtTest_Add(Test_CF_Chunks_Init_SetGiven_chunks_CF_max_chunks_ToGiven_CF_max_chunks, cf_chunk_tests_Setup, - cf_chunk_tests_Teardown, "Test_CF_Chunks_Init_SetGiven_chunks_CF_max_chunks_ToGiven_CF_max_chunks"); + UtTest_Add(Test_CF_Chunks_Init_AssertsBecauseGiven_max_chunks_Is_0, cf_chunk_tests_Setup, cf_chunk_tests_Teardown, + "Test_CF_Chunks_Init_AssertsBecauseGiven_max_chunks_Is_0"); + UtTest_Add(Test_CF_Chunks_Init_SetGiven_chunks_max_chunks_ToGiven_max_chunks, cf_chunk_tests_Setup, + cf_chunk_tests_Teardown, "Test_CF_Chunks_Init_SetGiven_chunks_max_chunks_ToGiven_max_chunks"); } /* end add_CF_Chunks_Init_tests */ void add_CF_ChunksReset_tests(void) { - UtTest_Add(Test_CF_ChunksReset_Set_count_To_0_Keeps_CF_max_chunks_AndMemsets_chunks_ToAll_0, cf_chunk_tests_Setup, + UtTest_Add(Test_CF_ChunksReset_Set_count_To_0_Keeps_max_chunks_AndMemsets_chunks_ToAll_0, cf_chunk_tests_Setup, cf_chunk_tests_Teardown, - "Test_CF_ChunksReset_Set_count_To_0_Keeps_CF_max_chunks_AndMemsets_chunks_ToAll_0"); + "Test_CF_ChunksReset_Set_count_To_0_Keeps_max_chunks_AndMemsets_chunks_ToAll_0"); } /* end add_CF_ChunksReset_tests */ void add_CF_Chunks_ComputeGaps_tests(void) diff --git a/unit-test/stubs/cf_app_stubs.c b/unit-test/stubs/cf_app_stubs.c index 641001241..726cf9af0 100644 --- a/unit-test/stubs/cf_app_stubs.c +++ b/unit-test/stubs/cf_app_stubs.c @@ -1,26 +1,20 @@ /************************************************************************ -** File: cf_app.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application main application header file -** -*************************************************************************/ + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file diff --git a/unit-test/stubs/cf_cfdp_dispatch_stubs.c b/unit-test/stubs/cf_cfdp_dispatch_stubs.c index 49bb1e519..1a3fe45e0 100644 --- a/unit-test/stubs/cf_cfdp_dispatch_stubs.c +++ b/unit-test/stubs/cf_cfdp_dispatch_stubs.c @@ -1,24 +1,22 @@ /************************************************************************ -** File: cf_cfdp_dispatch.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ /** * @file diff --git a/unit-test/stubs/cf_cfdp_r_stubs.c b/unit-test/stubs/cf_cfdp_r_stubs.c index c12e9594b..190d6768a 100644 --- a/unit-test/stubs/cf_cfdp_r_stubs.c +++ b/unit-test/stubs/cf_cfdp_r_stubs.c @@ -1,24 +1,22 @@ /************************************************************************ -** File: cf_cfdp_r.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * + ************************************************************************/ /** * @file diff --git a/unit-test/stubs/cf_cfdp_s_stubs.c b/unit-test/stubs/cf_cfdp_s_stubs.c index cab4a318c..eb26d6923 100644 --- a/unit-test/stubs/cf_cfdp_s_stubs.c +++ b/unit-test/stubs/cf_cfdp_s_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_cfdp.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application cfdp engine and packet parsing header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file diff --git a/unit-test/stubs/cf_cfdp_sbintf_stubs.c b/unit-test/stubs/cf_cfdp_sbintf_stubs.c index 7a6841235..763ee6c48 100644 --- a/unit-test/stubs/cf_cfdp_sbintf_stubs.c +++ b/unit-test/stubs/cf_cfdp_sbintf_stubs.c @@ -1,24 +1,21 @@ /************************************************************************ -** File: cf_cfdp_sbintf.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -29,7 +26,7 @@ #include "cf_cfdp_sbintf.h" #include "utgenstub.h" -extern void UT_DefaultHandler_CF_CFDP_MsgOutGet(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_MsgOutGet(void *, UT_EntryKey_t, const UT_StubContext_t *); /* * ---------------------------------------------------- diff --git a/unit-test/stubs/cf_cfdp_stubs.c b/unit-test/stubs/cf_cfdp_stubs.c index 691d36b69..c703b43fb 100644 --- a/unit-test/stubs/cf_cfdp_stubs.c +++ b/unit-test/stubs/cf_cfdp_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_cfdp.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application cfdp engine and packet parsing header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -33,11 +26,11 @@ #include "cf_cfdp.h" #include "utgenstub.h" -extern void UT_DefaultHandler_CF_CFDP_CancelTransaction(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CFDP_ConstructPduHeader(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CFDP_PlaybackDir(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CFDP_ResetTransaction(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CFDP_TxFile(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_CancelTransaction(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_ConstructPduHeader(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_PlaybackDir(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_ResetTransaction(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_TxFile(void *, UT_EntryKey_t, const UT_StubContext_t *); /* * ---------------------------------------------------- diff --git a/unit-test/stubs/cf_chunk_stubs.c b/unit-test/stubs/cf_chunk_stubs.c index 13c26cc7e..c93e7385c 100644 --- a/unit-test/stubs/cf_chunk_stubs.c +++ b/unit-test/stubs/cf_chunk_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_chunk.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application chunks (spare gap tracking) header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -33,7 +26,7 @@ #include "cf_chunk.h" #include "utgenstub.h" -extern void UT_DefaultHandler_CF_ChunkList_GetFirstChunk(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_ChunkList_GetFirstChunk(void *, UT_EntryKey_t, const UT_StubContext_t *); /* * ---------------------------------------------------- diff --git a/unit-test/stubs/cf_clist_stubs.c b/unit-test/stubs/cf_clist_stubs.c index 8c8e26a79..ab1f9b670 100644 --- a/unit-test/stubs/cf_clist_stubs.c +++ b/unit-test/stubs/cf_clist_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_clist.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application circular list header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -33,12 +26,12 @@ #include "cf_clist.h" #include "utgenstub.h" -extern void UT_DefaultHandler_CF_CList_InitNode(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CList_InsertAfter(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CList_InsertBack(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CList_Remove(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CList_Traverse(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CList_Traverse_R(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CList_InitNode(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CList_InsertAfter(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CList_InsertBack(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CList_Remove(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CList_Traverse(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CList_Traverse_R(void *, UT_EntryKey_t, const UT_StubContext_t *); /* * ---------------------------------------------------- diff --git a/unit-test/stubs/cf_cmd_stubs.c b/unit-test/stubs/cf_cmd_stubs.c index 9e2d8e45c..8791148bb 100644 --- a/unit-test/stubs/cf_cmd_stubs.c +++ b/unit-test/stubs/cf_cmd_stubs.c @@ -1,23 +1,21 @@ /************************************************************************ -** File: cf_cmd.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -28,7 +26,7 @@ #include "cf_cmd.h" #include "utgenstub.h" -extern void UT_DefaultHandler_CF_ProcessGroundCommand(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_ProcessGroundCommand(void *, UT_EntryKey_t, const UT_StubContext_t *); /* * ---------------------------------------------------- diff --git a/unit-test/stubs/cf_codec_stubs.c b/unit-test/stubs/cf_codec_stubs.c index b6a5ecf31..674df290f 100644 --- a/unit-test/stubs/cf_codec_stubs.c +++ b/unit-test/stubs/cf_codec_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_cfdp.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application cfdp engine and packet parsing header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -33,11 +26,11 @@ #include "cf_codec.h" #include "utgenstub.h" -extern void UT_DefaultHandler_CF_CFDP_CodecCheckSize(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CFDP_DoDecodeChunk(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CFDP_DoEncodeChunk(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_CFDP_GetValueEncodedSize(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_DecodeIntegerInSize(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_CodecCheckSize(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_DoDecodeChunk(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_DoEncodeChunk(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_CFDP_GetValueEncodedSize(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_DecodeIntegerInSize(void *, UT_EntryKey_t, const UT_StubContext_t *); /* * ---------------------------------------------------- diff --git a/unit-test/stubs/cf_crc_stubs.c b/unit-test/stubs/cf_crc_stubs.c index ac1e144bb..38c6da15d 100644 --- a/unit-test/stubs/cf_crc_stubs.c +++ b/unit-test/stubs/cf_crc_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_crc.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application CRC calculation header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file diff --git a/unit-test/stubs/cf_timer_stubs.c b/unit-test/stubs/cf_timer_stubs.c index 1b207ffed..c9099148d 100644 --- a/unit-test/stubs/cf_timer_stubs.c +++ b/unit-test/stubs/cf_timer_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_timer.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application timer header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -54,9 +47,9 @@ int CF_Timer_Expired(const CF_Timer_t *t) * Generated stub function for CF_Timer_InitRelSec() * ---------------------------------------------------- */ -void CF_Timer_InitRelSec(CF_Timer_t *c, CF_Timer_Seconds_t rel_sec) +void CF_Timer_InitRelSec(CF_Timer_t *t, CF_Timer_Seconds_t rel_sec) { - UT_GenStub_AddParam(CF_Timer_InitRelSec, CF_Timer_t *, c); + UT_GenStub_AddParam(CF_Timer_InitRelSec, CF_Timer_t *, t); UT_GenStub_AddParam(CF_Timer_InitRelSec, CF_Timer_Seconds_t, rel_sec); UT_GenStub_Execute(CF_Timer_InitRelSec, Basic, NULL); diff --git a/unit-test/stubs/cf_utils_stubs.c b/unit-test/stubs/cf_utils_stubs.c index ad055ff1d..f7ecd2170 100644 --- a/unit-test/stubs/cf_utils_stubs.c +++ b/unit-test/stubs/cf_utils_stubs.c @@ -1,28 +1,21 @@ /************************************************************************ -** File: cf_utils.h -** -** NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) -** Application version 3.0.0” -** Copyright © 2019 United States Government as represented by the -** Administrator of the National Aeronautics and Space Administration. -** All Rights Reserved. -** Licensed under the Apache License, Version 2.0 (the "License"); you may -** not use this file except in compliance with the License. You may obtain -** a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -** -** Unless required by applicable law or agreed to in writing, software -** distributed under the License is distributed on an "AS IS" BASIS, -** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -** See the License for the specific language governing permissions and -** limitations under the License. -** -** -** Purpose: -** The CF Application utils header file -** -** -** -*************************************************************************/ + * + * NASA Docket No. GSC-18,447-1, and identified as “CFS CFDP (CF) + * Application version 3.0.0” + * Copyright © 2019 United States Government as represented by the + * Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ************************************************************************/ /** * @file @@ -33,14 +26,14 @@ #include "cf_utils.h" #include "utgenstub.h" -extern void UT_DefaultHandler_CF_FindTransactionBySequenceNumber(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_FindUnusedTransaction(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_ResetHistory(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_TraverseAllTransactions(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_TraverseAllTransactions_All_Channels(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_WrappedOpenCreate(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_WriteHistoryQueueDataToFile(void *, UT_EntryKey_t, const UT_StubContext_t *); -extern void UT_DefaultHandler_CF_WriteQueueDataToFile(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_FindTransactionBySequenceNumber(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_FindUnusedTransaction(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_ResetHistory(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_TraverseAllTransactions(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_TraverseAllTransactions_All_Channels(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_WrappedOpenCreate(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_WriteHistoryQueueDataToFile(void *, UT_EntryKey_t, const UT_StubContext_t *); +void UT_DefaultHandler_CF_WriteQueueDataToFile(void *, UT_EntryKey_t, const UT_StubContext_t *); /* * ----------------------------------------------------