summaryrefslogtreecommitdiff
path: root/include/sqfs/compress.h
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 23:11:03 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 23:12:08 +0200
commitc17de5d4c2699c6c5b4759f009ce8cb6560d2f13 (patch)
treeca36c1af536583856360dd6e905fe7143ee5a562 /include/sqfs/compress.h
parent524869a644004b2b5eae9c6cdb14a20c0e877778 (diff)
Add doxygen annotations to all public headers
Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
Diffstat (limited to 'include/sqfs/compress.h')
-rw-r--r--include/sqfs/compress.h265
1 files changed, 245 insertions, 20 deletions
diff --git a/include/sqfs/compress.h b/include/sqfs/compress.h
index eaec2b5..3d99617 100644
--- a/include/sqfs/compress.h
+++ b/include/sqfs/compress.h
@@ -23,88 +23,259 @@
#include "sqfs/predef.h"
#include "sqfs/super.h"
-/* Encapsultes a compressor with a simple interface to compress or
- uncompress/extract blocks of data. */
+/**
+ * @file compress.h
+ *
+ * @brief Contains declarations to everything related to data compression.
+ */
+
+/**
+ * @interface sqfs_compressor_t
+ *
+ * @brief Encapsultes a compressor with a simple interface to compress or
+ * extract chunks of data.
+ */
struct sqfs_compressor_t {
+ /**
+ * @brief Destroy a compressor and free all memory used by it.
+ *
+ * @param cmp A pointer to a compressor object.
+ */
void (*destroy)(sqfs_compressor_t *cmp);
- /* Write compressor options to the output file if necessary.
- Returns the number of bytes written or -1 on failure.
- Internally prints error messages to stderr. */
+ /**
+ * @brief Write compressor options to disk if non-default settings
+ * have been used.
+ *
+ * The options are stored in an uncompressed meta data block directly
+ * after the super block.
+ *
+ * @param cmp A pointer to a compressor object.
+ * @param file A file to write to.
+ *
+ * @return The number of bytes written on success, 0 means default
+ * settings are used. A negative value is an @ref E_SQFS_ERROR
+ * identifier.
+ */
int (*write_options)(sqfs_compressor_t *cmp, sqfs_file_t *file);
- /* Read compressor options to the input file.
- Returns zero on success, -1 on failure.
- Internally prints error messages to stderr. */
+ /**
+ * @brief Read compressor options from disk.
+ *
+ * @param cmp A pointer to a compressor object.
+ * @param file A file to read from.
+ *
+ * @return Zero on success or an @ref E_SQFS_ERROR value.
+ */
int (*read_options)(sqfs_compressor_t *cmp, sqfs_file_t *file);
- /*
- Compress or uncompress a chunk of data.
-
- Returns the number of bytes written to the output buffer, -1 on
- failure or 0 if the output buffer was too small.
- The compressor also returns 0 if the compressed result ends
- up larger than the original input.
-
- Internally prints compressor specific error messages to stderr.
- */
+ /**
+ * @brief Compress or uncompress a chunk of data.
+ *
+ * @param cmp A pointer to a compressor object.
+ * @param in A pointer to the input buffer to read from.
+ * @param size The number of bytes to read from the input and compress.
+ * @param out The destination buffer to write the result to.
+ * @param outsize The available space in the destination buffer.
+ *
+ * @return The number of bytes written to the buffer, a negative
+ * value is an @ref E_SQFS_ERROR value. The value 0 means
+ * the output buffer was too small when extracting or that
+ * the result is larger than the input when compressing.
+ */
ssize_t (*do_block)(sqfs_compressor_t *cmp, const uint8_t *in,
size_t size, uint8_t *out, size_t outsize);
- /* create another compressor just like this one, i.e.
- with the exact same settings */
+ /**
+ * @brief Create an exact copt of agiven compressor
+ *
+ * @param cmp A pointer to a compressor object.
+ *
+ * @return A deep copy of the given compressor.
+ */
sqfs_compressor_t *(*create_copy)(sqfs_compressor_t *cmp);
};
+/**
+ * @struct sqfs_compressor_config_t
+ *
+ * @brief Configuration parameters for instantiating a compressor backend.
+ */
struct sqfs_compressor_config_t {
+ /**
+ * @brief An @ref E_SQFS_COMPRESSOR identifier
+ */
uint16_t id;
+
+ /**
+ * @brief A combination of @ref SQFS_COMP_FLAG flags.
+ */
uint16_t flags;
+
+ /**
+ * @brief The intended data block size.
+ */
uint32_t block_size;
+ /**
+ * @brief Backend specific options for fine tuing.
+ */
union {
+ /**
+ * @brief Options for the zlib compressor.
+ */
struct {
+ /**
+ * @brief Compression level. Value between 1 and 9.
+ *
+ * Default is 9, i.e. best compression.
+ */
uint16_t level;
+
+ /**
+ * @brief Deflate window size. Value between 8 and 15.
+ *
+ * Default is 15, i.e. 32k window.
+ */
uint16_t window_size;
} gzip;
+ /**
+ * @brief Options for the zstd compressor.
+ */
struct {
+ /**
+ * @brief Compression level. Value between 1 and 22.
+ *
+ * Default is 15.
+ */
uint16_t level;
} zstd;
+ /**
+ * @brief Options for the lzo compressor.
+ */
struct {
+ /**
+ * @brief Which variant of lzo should be used.
+ *
+ * An @ref SQFS_LZO_ALGORITHM value. Default is
+ * @ref SQFS_LZO1X_999, i.e. best compression.
+ */
uint16_t algorithm;
+
+ /**
+ * @brief Compression level for @ref SQFS_LZO1X_999.
+ *
+ * If the selected algorithm is @ref SQFS_LZO1X_999,
+ * this can be a value between 0 and 9. For all other
+ * algorithms it has to be 0.
+ *
+ * Defaults to 9, i.e. best compression.
+ */
uint16_t level;
} lzo;
+ /**
+ * @brief Options for the xz compressor.
+ */
struct {
+ /**
+ * @brief LZMA dictionary size.
+ *
+ * This value must either be a power of two or the sumo
+ * of two consecutive powers of two.
+ *
+ * Default is setting this to the same as the
+ * block size.
+ */
uint32_t dict_size;
} xz;
} opt;
};
+/**
+ * @enum SQFS_COMP_FLAG
+ *
+ * @brief Flags for configuring the compressor.
+ */
typedef enum {
+ /**
+ * @brief For LZ4, set this to use high compression mode.
+ */
SQFS_COMP_FLAG_LZ4_HC = 0x0001,
SQFS_COMP_FLAG_LZ4_ALL = 0x0001,
+ /**
+ * @brief For LZMA, set this to select the x86 BCJ filter.
+ */
SQFS_COMP_FLAG_XZ_X86 = 0x0001,
+
+ /**
+ * @brief For LZMA, set this to select the PowerPC BCJ filter.
+ */
SQFS_COMP_FLAG_XZ_POWERPC = 0x0002,
+
+ /**
+ * @brief For LZMA, set this to select the Itanium BCJ filter.
+ */
SQFS_COMP_FLAG_XZ_IA64 = 0x0004,
+
+ /**
+ * @brief For LZMA, set this to select the ARM BCJ filter.
+ */
SQFS_COMP_FLAG_XZ_ARM = 0x0008,
+
+ /**
+ * @brief For LZMA, set this to select the ARM Thumb BCJ filter.
+ */
SQFS_COMP_FLAG_XZ_ARMTHUMB = 0x0010,
+
+ /**
+ * @brief For LZMA, set this to select the Sparc BCJ filter.
+ */
SQFS_COMP_FLAG_XZ_SPARC = 0x0020,
SQFS_COMP_FLAG_XZ_ALL = 0x003F,
+ /**
+ * @brief For zlib deflate, set this to try the default strategy.
+ */
SQFS_COMP_FLAG_GZIP_DEFAULT = 0x0001,
+
+ /**
+ * @brief For zlib deflate, set this to try the "filtered" strategy.
+ */
SQFS_COMP_FLAG_GZIP_FILTERED = 0x0002,
+
+ /**
+ * @brief For zlib deflate, set this to try the huffman only strategy.
+ */
SQFS_COMP_FLAG_GZIP_HUFFMAN = 0x0004,
+
+ /**
+ * @brief For zlib deflate, set this to try the RLE strategy.
+ */
SQFS_COMP_FLAG_GZIP_RLE = 0x0008,
+
+ /**
+ * @brief For zlib deflate, set this to try the fixed strategy.
+ */
SQFS_COMP_FLAG_GZIP_FIXED = 0x0010,
SQFS_COMP_FLAG_GZIP_ALL = 0x001F,
+ /**
+ * @brief Set this if the compressor should actually extract
+ * instead of compress data.
+ */
SQFS_COMP_FLAG_UNCOMPRESS = 0x8000,
SQFS_COMP_FLAG_GENERIC_ALL = 0x8000,
} SQFS_COMP_FLAG;
+/**
+ * @enum SQFS_LZO_ALGORITHM
+ *
+ * @brief The available LZO algorithms.
+ */
typedef enum {
SQFS_LZO1X_1 = 0,
SQFS_LZO1X_1_11 = 1,
@@ -137,17 +308,71 @@ typedef enum {
extern "C" {
#endif
+/**
+ * @brief Initialize a compressor configuration
+ *
+ * The detail configuration options are all initialized to the defaults for
+ * the compressor in question.
+ *
+ * @param cfg A pointer to a compressor configuration to initialize
+ * @param id The compressor id to set.
+ * @param block_size The block size to set.
+ * @param flags The compressor flags to set.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value if some of the options
+ * don't make sense (e.g. unknown flags are used).
+ */
SQFS_API int sqfs_compressor_config_init(sqfs_compressor_config_t *cfg,
E_SQFS_COMPRESSOR id,
size_t block_size, uint16_t flags);
+/**
+ * @brief Check if a specified compressor implementation is available.
+ *
+ * @param id An @ref E_SQFS_COMPRESSOR identifier.
+ *
+ * @return true if the implementation is available and can be instantiated
+ * through @ref sqfs_compressor_create.
+ */
SQFS_API bool sqfs_compressor_exists(E_SQFS_COMPRESSOR id);
+/**
+ * @brief Create an instance of a compressor implementation.
+ *
+ * @param cfg A pointer to a compressor configuration.
+ *
+ * @return A pointer to a compressor object on success, NULL on allocation
+ * failure or if initializing the compressor failed.
+ */
SQFS_API
sqfs_compressor_t *sqfs_compressor_create(const sqfs_compressor_config_t *cfg);
+/**
+ * @brief Get the name of a compressor backend from its ID.
+ *
+ * This function will even resolve compressor names that are not built in, so
+ * use @ref sqfs_compressor_exists to check if a compressor is actually
+ * available.
+ *
+ * @param id An @ref E_SQFS_COMPRESSOR identifier.
+ *
+ * @return A string holding the name of the compressor, NULL if the compressor
+ * ID is not known.
+ */
SQFS_API const char *sqfs_compressor_name_from_id(E_SQFS_COMPRESSOR id);
+/**
+ * @brief Get the compressor ID using just the name of the backend.
+ *
+ * This function will even resolve compressor names that are not built in, so
+ * use @ref sqfs_compressor_exists to check if a compressor is actually
+ * available.
+ *
+ * @param name The name of the compressor backend.
+ * @param out Returns the coresponding @ref E_SQFS_COMPRESSOR identifier.
+ *
+ * @return Zero on success, -1 if the backend is unknown.
+ */
SQFS_API
int sqfs_compressor_id_from_name(const char *name, E_SQFS_COMPRESSOR *out);