diff options
Diffstat (limited to 'include/sqfs/compress.h')
| -rw-r--r-- | include/sqfs/compress.h | 265 |
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); |