Fix #73, compression selectable at source file level

Adds a cmake option for compression sub-component implementation.  This
replaces the FM_INCLUDE_DECOMPRESS option in fm_platform_cfg.h.

Currently available options are:
 - fslib (should be equivalent to FM_INCLUDE_DECOMPRESS set)
 - none (should be equivalent to FM_INCLUDE_DECOMPRESS unset)
 - zlib (stub for future work)

This lays the groundwork to support compression in addition to
decompression, using an external 3rd part library if desired.

CMakeLists.txt

@@ -1,8 +1,14 @@
 project(CFS_FM C)
 
-# Uncomment the below include if decompress functionality is
-# enabled in FM
-# include_directories(${fs_lib_MISSION_DIR}/fsw/public_inc)
+# Type of data compression to link in.  Actual routines to implement compression
+# are expected to be in a separately loaded library.  Bindings are available for:
+#  FALSE or OFF: Do not include compression
+#  TRUE or ON: Use default compression for the platform (TBD)
+#  CFS_FS_LIB: historical unzip implementation from older versions of CFE FS (deprecated)
+#  ZLIB: Use inflate/deflate API from zlib (http://zlib.net) (not yet implemented)
+set(FM_INCLUDE_COMPRESSION FALSE CACHE STRING "Type of data compression/decompression features to include in FM")
+set(FM_DEPENDENCY_LIST)
+set(FM_OPTION_SRC_FILES)
 
 set(APP_SRC_FILES
   fsw/src/fm_cmd_utils.c
@@ -12,12 +18,39 @@ set(APP_SRC_FILES
   fsw/src/fm_tbl.c
 )
 
+# If compression features are enabled, choose the adapter based on the selected implementation
+if (FM_INCLUDE_COMPRESSION)
+
+  if (FM_INCLUDE_COMPRESSION STREQUAL ZLIB)
+    # Using a properly-maintained external implementation should be preferred
+    # This may be the default in a future release.
+    list(APPEND FM_OPTION_SRC_FILES fsw/src/fm_compression_zlib.c)
+  else()
+    # Older versions of FM used a decompression implemented in CFS FS, so this is
+    # what will be assumed if FM_INCLUDE_COMPRESSION is set to a simple
+    # boolean "ON" or "TRUE".  This code now resides in an external "FS_Lib".
+    list(APPEND FM_DEPENDENCY_LIST fs_lib)
+    list(APPEND FM_OPTION_SRC_FILES fsw/src/fm_compression_fslib.c)
+  endif()
+
+else()
+
+  # FM_INCLUDE_COMPRESSION set to "OFF" or "FALSE" - compression features are not enabled
+  list(APPEND FM_OPTION_SRC_FILES fsw/src/fm_compression_none.c)
+
+endif()
+
 # Create the app module
-add_cfe_app(fm ${APP_SRC_FILES})
+add_cfe_app(fm ${APP_SRC_FILES} ${FM_OPTION_SRC_FILES})
 
 # This permits direct access to public headers in the fsw/inc directory
 target_include_directories(fm PUBLIC fsw/inc)
 
+# Add dependencies based on the type of compression algoritm selected (if any)
+if (FM_DEPENDENCY_LIST)
+  add_cfe_app_dependency(fm ${FM_DEPENDENCY_LIST})
+endif()
+
 set(APP_TABLE_FILES
   fsw/tables/fm_monitor.c
 )

docs/dox_src/cfs_fm.dox

@@ -54,10 +54,10 @@
 
   This Doxygen-based User's Guide provides a complete reference for the
   cFS File Manager (FM) application.  The Guide is intended primarily for
-  users of the software (operations personnel, test engineers, and 
+  users of the software (operations personnel, test engineers, and
   maintenance personnel) who prefer a developer-focused document and direct
   references to the source code.  The "deployment guide" section is intended
-  for mission developers when deploying and configuring the FM application 
+  for mission developers when deploying and configuring the FM application
   software for a mission flight software build environment.
 
   \ref cfsfmversion
@@ -109,21 +109,21 @@
   \page cfsfmovr CFS File Manager Overview
 
   The CFS FM application provides onboard file system management services by processing ground commands
-  for copying, moving, and renaming files, decompressing files, creating directories, deleting files and 
-  directories, providing file and directory informational telemetry messages, and providing open file and 
-  directory listings.  The FM software context diagram is shown in Figure FM-1.  
-  
+  for copying, moving, and renaming files, decompressing files, creating directories, deleting files and
+  directories, providing file and directory informational telemetry messages, and providing open file and
+  directory listings.  The FM software context diagram is shown in Figure FM-1.
+
   \image html CFS_FM_Context.jpg "Figure FM-1"
   \image latex CFS_FM_Context.jpg "Figure FM-1"
 
-  The FM application interfaces with the Command Ingest (CI) application to receive ground commands.  
-  See page \ref cfsfmcmdspg for a detailed description of the FM ground commands.  FM utilizes the Operating 
-  System Abstraction Layer (OSAL) API library functions for interfacing with the onboard file systems when 
+  The FM application interfaces with the Command Ingest (CI) application to receive ground commands.
+  See page \ref cfsfmcmdspg for a detailed description of the FM ground commands.  FM utilizes the Operating
+  System Abstraction Layer (OSAL) API library functions for interfacing with the onboard file systems when
   processing ground commands.  The FM application receives messages from the Scheduler (SCH) Application
-  for periodic housekeeping requests.  Upon receipt of a housekeeping request, FM will send its 
+  for periodic housekeeping requests.  Upon receipt of a housekeeping request, FM will send its
   housekeeping telemetry packets on the Software Bus.  Housekeeping telemetry
-  packets are typically subscribed to 
-  by the Housekeeping (HK), Telemetry Output (TO), and Data Storage applications.  See page 
+  packets are typically subscribed to
+  by the Housekeeping (HK), Telemetry Output (TO), and Data Storage applications.  See page
   \ref cfsfmtlm for a detailed description of the contents of the FM housekeeping telemetry packet.
 **/
 
@@ -134,66 +134,66 @@
 
   <B> Power-On and Processor Resets </B>
 
-  Upon a Power-On or Processor reset the FM application initializes all telemetry within its housekeeping 
-  telemetry packet.  The Command and Command Error counters are set to zero, as well as, all other 
-  numerical data within the packet.  In addition to initializing telemetry, FM registers for cFE event 
-  services, creates its software bus message pipe, and subscribes to FM SB housekeeping requests and 
+  Upon a Power-On or Processor reset the FM application initializes all telemetry within its housekeeping
+  telemetry packet.  The Command and Command Error counters are set to zero, as well as, all other
+  numerical data within the packet.  In addition to initializing telemetry, FM registers for cFE event
+  services, creates its software bus message pipe, and subscribes to FM SB housekeeping requests and
   commands.
 
   <B> Normal Operation </B>
 
-  The CFS FM application is a command and telemetry driven application.  FM waits in a command loop 
-  infinitely until the software receives a scheduled housekeeping request, ground command, or stored 
-  command.  Command packets (including housekeeping requests) are processed as they are received.  The 
-  application sends an FM housekeeping telemetry message on the cFE Software Bus upon receipt of a scheduled 
-  housekeeping request produced by the SCH application.  This request is typically performed every 
+  The CFS FM application is a command and telemetry driven application.  FM waits in a command loop
+  infinitely until the software receives a scheduled housekeeping request, ground command, or stored
+  command.  Command packets (including housekeeping requests) are processed as they are received.  The
+  application sends an FM housekeeping telemetry message on the cFE Software Bus upon receipt of a scheduled
+  housekeeping request produced by the SCH application.  This request is typically performed every
   4-5 seconds and these housekeeping messages are usually sent to the ground
   (though this depends on the configuration of the rest of the system).
 
-  Various FM ground commands produce telemetry messages as a result of processing the command.  These 
-  telemetry messages include a directory listing telemetry message, file information telemetry message, 
-  and an open file listing telemetry message. See page \ref cfsfmcmdspg for a detailed description of the 
-  FM directory listing, file information, and open file listing ground commands.  See page \ref cfsfmtlm 
-  for a detailed description of the contents of the FM directory listing, file information, and open file 
+  Various FM ground commands produce telemetry messages as a result of processing the command.  These
+  telemetry messages include a directory listing telemetry message, file information telemetry message,
+  and an open file listing telemetry message. See page \ref cfsfmcmdspg for a detailed description of the
+  FM directory listing, file information, and open file listing ground commands.  See page \ref cfsfmtlm
+  for a detailed description of the contents of the FM directory listing, file information, and open file
   listing telemetry messages.
 
-  Other FM ground commands produce files as a result of processing the command.  These files include a 
-  decompression file, concatenation file, and a directory listing file.  See page \ref cfsfmcmdspg for a 
-  detailed description of the FM decompress file, concatenate files, and directory listing file ground 
-  commands. Note decompression capability is optionally supported via the FM_INCLUDE_DECOMPRESS platform
+  Other FM ground commands produce files as a result of processing the command.  These files include a
+  decompression file, concatenation file, and a directory listing file.  See page \ref cfsfmcmdspg for a
+  detailed description of the FM decompress file, concatenate files, and directory listing file ground
+  commands. Note decompression capability is optionally supported via the FM_INCLUDE_COMPRESSION platform
   configuration option.
-  
-  The decompression file is produced using the cFE API function CFE_FS_Decompress which uses code ported 
-  from the GNU zip sources.  The cFE API function CFE_FS_Decompress produces the decompressed output file.  
-  The output file is comparable to that of a file that has been unzipped using the system utility gunzip.  
-  A compressed file reduces the size of the file by encoding the file.  Compressed files may be used to 
-  reduce uplink time to the spacecraft.  Decompressing the file will restore the file from its encoded 
+
+  The decompression file is produced using the cFE API function CFE_FS_Decompress which uses code ported
+  from the GNU zip sources.  The cFE API function CFE_FS_Decompress produces the decompressed output file.
+  The output file is comparable to that of a file that has been unzipped using the system utility gunzip.
+  A compressed file reduces the size of the file by encoding the file.  Compressed files may be used to
+  reduce uplink time to the spacecraft.  Decompressing the file will restore the file from its encoded
   state to the original state of the file.
 
-  The concatenation file is a direct copy of the contents of the two command specified source files, 
-  with the contents of the first source file specified proceeding the contents of the second source 
-  file specified.  The contents of the second source file are written with no delineation characters 
+  The concatenation file is a direct copy of the contents of the two command specified source files,
+  with the contents of the first source file specified proceeding the contents of the second source
+  file specified.  The contents of the second source file are written with no delineation characters
   such as spaces or returns following the contents of the first source file.
 
-  The directory listing file is written as a binary file and contains a cFE file header at the top of 
-  the file contiguously followed by a directory listing status data structure containing an echo of the 
-  command specified directory name (#OS_MAX_PATH_LEN), directory size in bytes (uint32), total number of 
-  file contained in the directory (uint32), and the number of file names written in the directory listing 
-  file (uint32).  The directory listing is then written contiguously one entry at a time.  Each entry in 
-  the directory listing includes for each file in the directory, the name of the file(#OS_MAX_PATH_LEN), 
-  file size in bytes (uint32), and last modification time of the file (uint32).  File systems use specific 
-  time epochs for their time tagging of files.  Since spacecraft systems rarely use an epoch that matches 
-  a particular file system, a function is used to convert the file system time (in seconds) to spacecraft 
-  time (in seconds).  The conversion is controlled by a cFE configuration parameter which is set equal to 
-  the number of seconds between the spacecraft's epoch and the file system's epoch.  See #CFE_FS_Header_t 
-  for the cFE file header format.  See /FM_DirListFileStat_t for the format of the directory listing 
+  The directory listing file is written as a binary file and contains a cFE file header at the top of
+  the file contiguously followed by a directory listing status data structure containing an echo of the
+  command specified directory name (#OS_MAX_PATH_LEN), directory size in bytes (uint32), total number of
+  file contained in the directory (uint32), and the number of file names written in the directory listing
+  file (uint32).  The directory listing is then written contiguously one entry at a time.  Each entry in
+  the directory listing includes for each file in the directory, the name of the file(#OS_MAX_PATH_LEN),
+  file size in bytes (uint32), and last modification time of the file (uint32).  File systems use specific
+  time epochs for their time tagging of files.  Since spacecraft systems rarely use an epoch that matches
+  a particular file system, a function is used to convert the file system time (in seconds) to spacecraft
+  time (in seconds).  The conversion is controlled by a cFE configuration parameter which is set equal to
+  the number of seconds between the spacecraft's epoch and the file system's epoch.  See #CFE_FS_Header_t
+  for the cFE file header format.  See /FM_DirListFileStat_t for the format of the directory listing
   status structure.  See /FM_DirListFileData_t for the format of a directory listing entry.
 **/
 
 /**
   \page cfsfmdg  CFS File Manager Deployment Guide
-  
-  To integrate the FM application, follow the CFS App Integration Guide. 
+
+  To integrate the FM application, follow the CFS App Integration Guide.
   Also, be sure to set up the configuration parameters and message IDs for
   the platform
 **/

fsw/inc/fm_msgdefs.h

@@ -413,7 +413,9 @@
  *       of command argument verification and being able to place the command on
  *       the child task interface queue.
  *
- *       This command is only valid if FM_INCLUDE_DECOMPRESS is defined.
+ *       This command will only have an effect if FM is compiled with a decompression
+ *       algorithm enabled.  If compression is not enabled, issuing this command
+ *       will generate an error event.
  *
  *  \par Command Packet Structure
  *       #FM_DecompressCmd_t

fsw/inc/fm_platform_cfg.h

@@ -444,19 +444,6 @@
  */
 #define FM_TABLE_VALIDATION_ERR (-1)
 
-/**
- * \brief Include Decompress
- *
- *  \par Description:
- *       If this setting is defined, FM will be built with the Decompress
- *       command.  Otherwise Decompress will not be built into the application.
- *       If this setting is defined, FM will depend on an external FS_Lib.
- *
- *  \par Limits:
- *       N/A
- */
-/* #define FM_INCLUDE_DECOMPRESS */
-
 /**\}*/
 
 #endif

fsw/src/fm_app.c

@@ -236,6 +236,8 @@ int32 FM_AppInit(void)
         }
     }
 
+    FM_CompressionService_Init();
+
     return Result;
 }
 
@@ -313,11 +315,11 @@ void FM_ProcessCmd(const CFE_SB_Buffer_t *BufPtr)
         case FM_DELETE_ALL_CC:
             Result = FM_DeleteAllFilesCmd(BufPtr);
             break;
-#ifdef FM_INCLUDE_DECOMPRESS
+
         case FM_DECOMPRESS_CC:
             Result = FM_DecompressFileCmd(BufPtr);
             break;
-#endif
+
         case FM_CONCAT_CC:
             Result = FM_ConcatFilesCmd(BufPtr);
             break;

fsw/src/fm_app.h

@@ -26,10 +26,7 @@
 
 #include "cfe.h"
 #include "fm_msg.h"
-
-#ifdef FM_INCLUDE_DECOMPRESS
-#include "cfs_fs_lib.h"
-#endif
+#include "fm_compression.h"
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 /*                                                                 */
@@ -103,10 +100,18 @@ typedef struct
 
     FM_ChildQueueEntry_t ChildQueue[FM_CHILD_QUEUE_DEPTH]; /**< \brief Child task command queue */
 
-#ifdef FM_INCLUDE_DECOMPRESS
-    FS_LIB_Decompress_State_t DecompressState;
+    /**
+     * \brief State of the embedded decompression routine
+     * This depends on the decompression option and may be NULL
+     */
+    FM_Decompressor_State_t *DecompressorStatePtr;
+
+    /**
+     * \brief State of the embedded compression routine
+     * This depends on the compression option and may be NULL
+     */
+    FM_Compressor_State_t *CompressorStatePtr;
 
-#endif
 } FM_GlobalData_t;
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

fsw/src/fm_child.c

@@ -37,10 +37,6 @@
 
 #include <string.h>
 
-#ifdef FM_INCLUDE_DECOMPRESS
-#include "cfs_fs_lib.h"
-#endif
-
 /************************************************************************
 ** OSAL Compatibility for directory name access
 ** New OSAL version have an access macro to get the string.  If that
@@ -221,11 +217,11 @@ void FM_ChildProcess(void)
         case FM_DELETE_ALL_CC:
             FM_ChildDeleteAllCmd(CmdArgs);
             break;
-#ifdef FM_INCLUDE_DECOMPRESS
+
         case FM_DECOMPRESS_CC:
             FM_ChildDecompressCmd(CmdArgs);
             break;
-#endif
+
         case FM_CONCAT_CC:
             FM_ChildConcatCmd(CmdArgs);
             break;
@@ -589,8 +585,6 @@ void FM_ChildDeleteAllCmd(FM_ChildQueueEntry_t *CmdArgs)
 /*                                                                 */
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-#ifdef FM_INCLUDE_DECOMPRESS
-
 void FM_ChildDecompressCmd(const FM_ChildQueueEntry_t *CmdArgs)
 {
     const char *CmdText    = "Decompress File";
@@ -600,7 +594,7 @@ void FM_ChildDecompressCmd(const FM_ChildQueueEntry_t *CmdArgs)
     FM_GlobalData.ChildCurrentCC = CmdArgs->CommandCode;
 
     /* Decompress source file into target file */
-    CFE_Status = FS_LIB_Decompress(&FM_GlobalData.DecompressState, CmdArgs->Source1, CmdArgs->Target);
+    CFE_Status = FM_Decompress_Impl(FM_GlobalData.DecompressorStatePtr, CmdArgs->Source1, CmdArgs->Target);
 
     if (CFE_Status != CFE_SUCCESS)
     {
@@ -625,8 +619,6 @@ void FM_ChildDecompressCmd(const FM_ChildQueueEntry_t *CmdArgs)
     FM_GlobalData.ChildCurrentCC  = 0;
 }
 
-#endif
-
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 /*                                                                 */
 /* FM child task command handler -- Concatenate Files              */

fsw/src/fm_child.h

@@ -27,10 +27,6 @@
 #include "cfe.h"
 #include "fm_msg.h"
 
-#ifdef FM_INCLUDE_DECOMPRESS
-#include "cfs_fs_lib.h"
-#endif
-
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 /*                                                                 */
 /* FM child task global function prototypes                        */
@@ -196,8 +192,6 @@ void FM_ChildDeleteCmd(const FM_ChildQueueEntry_t *CmdArgs);
  */
 void FM_ChildDeleteAllCmd(FM_ChildQueueEntry_t *CmdArgs);
 
-#ifdef FM_INCLUDE_DECOMPRESS
-
 /**
  *  \brief Child Task Decompress File Command Handler
  *
@@ -215,8 +209,6 @@ void FM_ChildDeleteAllCmd(FM_ChildQueueEntry_t *CmdArgs);
  */
 void FM_ChildDecompressCmd(const FM_ChildQueueEntry_t *CmdArgs);
 
-#endif
-
 /**
  *  \brief Child Task Concatenate Files Command Handler
  *

fsw/src/fm_cmds.c

@@ -390,7 +390,6 @@ bool FM_DeleteAllFilesCmd(const CFE_SB_Buffer_t *BufPtr)
 /* FM command handler -- Decompress File                           */
 /*                                                                 */
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-#ifdef FM_INCLUDE_DECOMPRESS
 
 bool FM_DecompressFileCmd(const CFE_SB_Buffer_t *BufPtr)
 {
@@ -439,8 +438,6 @@ bool FM_DecompressFileCmd(const CFE_SB_Buffer_t *BufPtr)
     return CommandResult;
 }
 
-#endif
-
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 /*                                                                 */
 /* FM command handler -- Concatenate Files                         */