Bunch of liblzma tweaks, including some API changes.

The API and ABI should now be very close to stable,
although the code behind it isn't yet.

4 files changed, 127 insertions, 61 deletions

diff --git a/src/liblzma/api/lzma.h b/src/liblzma/api/lzma.h
index 7790a089..d19687b7 100644
--- a/src/liblzma/api/lzma.h
+++ b/src/liblzma/api/lzma.h
@@ -127,12 +127,12 @@
 #endif /* ifdef LZMA_MANUAL_HEADERS */
 
 
-/******************
- * GCC extensions *
- ******************/
+/********************
+ * GNU C extensions *
+ ********************/
 
 /*
- * GCC extensions are used conditionally in the public API. It doesn't
+ * GNU C extensions are used conditionally in the public API. It doesn't
  * break anything if these are sometimes enabled and sometimes not, only
  * affects warnings and optimizations.
  */
diff --git a/src/liblzma/api/lzma/block.h b/src/liblzma/api/lzma/block.h
index 2702cd51..a747b145 100644
--- a/src/liblzma/api/lzma/block.h
+++ b/src/liblzma/api/lzma/block.h
@@ -33,6 +33,35 @@
  */
 typedef struct {
 	/**
+	 * \brief       Block format version
+	 *
+	 * To prevent API and ABI breakages if new features are needed in
+	 * Block, a version number is used to indicate which fields in this
+	 * structure are in use. For now, version must always be zero.
+	 * With non-zero version, most Block related functions will return
+	 * LZMA_OPTIONS_ERROR.
+	 *
+	 * The decoding functions will always set this to the lowest value
+	 * that supports all the features indicated by the Block Header field.
+	 * The application must check that the version number set by the
+	 * decoding functions is supported by the application. Otherwise it
+	 * is possible that the application will decode the Block incorrectly.
+	 *
+	 * Read by:
+	 *  - lzma_block_header_size()
+	 *  - lzma_block_header_encode()
+	 *  - lzma_block_compressed_size()
+	 *  - lzma_block_unpadded_size()
+	 *  - lzma_block_total_size()
+	 *  - lzma_block_encoder()
+	 *  - lzma_block_decoder()
+	 *
+	 * Written by:
+	 *  - lzma_block_header_decode()
+	 */
+	uint32_t version;
+
+	/**
 	 * \brief       Size of the Block Header field
 	 *
 	 * This is always a multiple of four.
@@ -168,6 +197,37 @@ typedef struct {
 	 */
 	lzma_filter *filters;
 
+	/*
+	 * Reserved space to allow possible future extensions without
+	 * breaking the ABI. You should not touch these, because the names
+	 * of these variables may change. These are and will never be used
+	 * with the currently supported options, so it is safe to leave these
+	 * uninitialized.
+	 */
+	void *reserved_ptr1;
+	void *reserved_ptr2;
+	void *reserved_ptr3;
+	uint32_t reserved_int1;
+	uint32_t reserved_int2;
+	lzma_vli reserved_int3;
+	lzma_vli reserved_int4;
+	lzma_vli reserved_int5;
+	lzma_vli reserved_int6;
+	lzma_vli reserved_int7;
+	lzma_vli reserved_int8;
+	lzma_reserved_enum reserved_enum1;
+	lzma_reserved_enum reserved_enum2;
+	lzma_reserved_enum reserved_enum3;
+	lzma_reserved_enum reserved_enum4;
+	lzma_bool reserved_bool1;
+	lzma_bool reserved_bool2;
+	lzma_bool reserved_bool3;
+	lzma_bool reserved_bool4;
+	lzma_bool reserved_bool5;
+	lzma_bool reserved_bool6;
+	lzma_bool reserved_bool7;
+	lzma_bool reserved_bool8;
+
 } lzma_block;
 
 
@@ -196,7 +256,8 @@ typedef struct {
  *
  * \return      - LZMA_OK: Size calculated successfully and stored to
  *                block->header_size.
- *              - LZMA_OPTIONS_ERROR: Unsupported filters or filter options.
+ *              - LZMA_OPTIONS_ERROR: Unsupported version, filters or
+ *                filter options.
  *              - LZMA_PROG_ERROR: Invalid values like compressed_size == 0.
  *
  * \note        This doesn't check that all the options are valid i.e. this
diff --git a/src/liblzma/api/lzma/container.h b/src/liblzma/api/lzma/container.h
index 800f2129..ba2c4f8f 100644
--- a/src/liblzma/api/lzma/container.h
+++ b/src/liblzma/api/lzma/container.h
@@ -26,30 +26,42 @@
  ************/
 
 /**
- * \brief       Default compression level for easy encoder
+ * \brief       Default compression preset
  *
- * It's not straightforward to recommend a default level, because in some
+ * It's not straightforward to recommend a default preset, because in some
  * cases keeping the resource usage relatively low is more important that
  * getting the maximum compression ratio.
  */
-#define LZMA_EASY_LEVEL_DEFAULT 6
+#define LZMA_PRESET_DEFAULT     UINT32_C(6)
+
+
+/**
+ * \brief       Mask for preset level
+ *
+ * This is useful only if you need to extract the level from the preset
+ * variable. That should be rare.
+ */
+#define LZMA_PRESET_LEVEL_MASK  UINT32_C(0x1F)
 
 
 /*
- * Flags for easy encoder
+ * Preset flags
  *
  * Currently only one flag is defined.
  */
 
 /**
- * Use significantly slower compression to get marginally better compression
- * ratio. This doesn't affect the memory requirements of the encoder or
- * decoder. This flag is useful when you don't mind wasting time to get as
- * small result as possible.
+ * \brief       Extreme compression preset
+ *
+ * This flag modifies the preset to make the encoding significantly slower
+ * while improving the compression ratio only marginally. This is useful
+ * when you don't mind wasting time to get as small result as possible.
  *
- * FIXME: Not implemented yet.
+ * This flag doesn't affect the memory usage requirements of the decoder (at
+ * least not significantly). The memory usage of the encoder may be increased
+ * a little but only at the lowest preset levels (0-4 or so).
  */
-#define LZMA_EASY_EXTREME       UINT32_C(0x01)
+#define LZMA_PRESET_EXTREME       (UINT32_C(1) << 31)
 
 
 /**
@@ -57,12 +69,9 @@
  *
  * This function is a wrapper for lzma_raw_encoder_memusage().
  *
- * \param       level   Compression level
- * \param       flags   Easy encoder flags (usually zero). This parameter is
- *                      needed, because in future some flags may affect the
- *                      memory requirements.
+ * \param       preset  Compression preset (level and possible flags)
  */
-extern uint64_t lzma_easy_encoder_memusage(uint32_t level, uint32_t flags)
+extern uint64_t lzma_easy_encoder_memusage(uint32_t preset)
 		lzma_attr_pure;
 
 
@@ -71,12 +80,9 @@ extern uint64_t lzma_easy_encoder_memusage(uint32_t level, uint32_t flags)
  *
  * This function is a wrapper for lzma_raw_decoder_memusage().
  *
- * \param       level   Compression level
- * \param       flags   Easy encoder flags (usually zero). This parameter is
- *                      needed, because in future some flags may affect the
- *                      memory requirements.
+ * \param       preset  Compression preset (level and possible flags)
  */
-extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags)
+extern uint64_t lzma_easy_decoder_memusage(uint32_t preset)
 		lzma_attr_pure;
 
 
@@ -88,14 +94,12 @@ extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags)
  *
  * \param       strm    Pointer to lzma_stream that is at least initialized
  *                      with LZMA_STREAM_INIT.
- * \param       level   Compression level to use. This selects a set of
- *                      compression settings from a list of compression
- *                      presets. Currently levels from 1 to 9 are defined,
- *                      which match the options -1 .. -9 of the xz command
- *                      line tool.
- * \param       flags   Flags that can finetune the compression preset.
- *                      In most cases, no flags are wanted, and this
- *                      parameter is zero.
+ * \param       preset  Compression preset to use. A preset consist of level
+ *                      number and zero or more flags. Usually flags aren't
+ *                      used, so preset is simply a number [0, 9] which match
+ *                      the options -0 .. -9 of the xz command line tool.
+ *                      Additional flags can be be set using bitwise-or with
+ *                      the preset level number, e.g. 6 | LZMA_PRESET_EXTREME.
  * \param       check   Integrity check type to use. See check.h for available
  *                      checks. If you are unsure, use LZMA_CHECK_CRC32.
  *
@@ -115,8 +119,8 @@ extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags)
  * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
  * there may be compression levels or flags that don't support LZMA_SYNC_FLUSH.
  */
-extern lzma_ret lzma_easy_encoder(lzma_stream *strm,
-		uint32_t level, uint32_t flags, lzma_check check)
+extern lzma_ret lzma_easy_encoder(
+		lzma_stream *strm, uint32_t preset, lzma_check check)
 		lzma_attr_warn_unused_result;
 
 
@@ -125,10 +129,8 @@ extern lzma_ret lzma_easy_encoder(lzma_stream *strm,
  *
  * \param       strm    Pointer to properly prepared lzma_stream
  * \param       filters Array of filters. This must be terminated with
- *                      filters[n].id = LZMA_VLI_UNKNOWN. There must
- *                      be 1-4 filters, but there are restrictions on how
- *                      multiple filters can be combined. FIXME Tell where
- *                      to find more information.
+ *                      filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for
+ *                      more information.
  * \param       check   Type of the integrity check to calculate from
  *                      uncompressed data.
  *
@@ -153,15 +155,13 @@ extern lzma_ret lzma_stream_encoder(lzma_stream *strm,
  * legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format
  * is strongly recommended.
  *
- * FIXME: Dictionary size limit?
- *
  * The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH.
  * No kind of flushing is supported, because the file format doesn't make
  * it possible.
  *
  * \return      - LZMA_OK
  *              - LZMA_MEM_ERROR
- *              - LZMA_OPTIONS_ERROR // FIXME
+ *              - LZMA_OPTIONS_ERROR
  *              - LZMA_PROG_ERROR
  */
 extern lzma_ret lzma_alone_encoder(
@@ -252,7 +252,7 @@ extern lzma_ret lzma_auto_decoder(
 
 
 /**
- * \brief       Initializes decoder for .lzma file
+ * \brief       Initialize .lzma decoder (legacy file format)
  *
  * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
  * There is no need to use LZMA_FINISH, but allowing it may simplify
diff --git a/src/liblzma/api/lzma/lzma.h b/src/liblzma/api/lzma/lzma.h
index e3db236b..834bf0b0 100644
--- a/src/liblzma/api/lzma/lzma.h
+++ b/src/liblzma/api/lzma/lzma.h
@@ -160,19 +160,20 @@ typedef enum {
  * mode, which the application developer wasn't aware, could require giving
  * additional options to the encoder that the older modes don't need.
  */
-extern lzma_bool lzma_mode_is_available(lzma_mode mode) lzma_attr_const;
+extern lzma_bool lzma_mode_is_supported(lzma_mode mode) lzma_attr_const;
 
 
 /**
  * \brief       Options specific to the LZMA1 and LZMA2 filters
+ *
+ * Since LZMA1 and LZMA2 share most of the code, it's simplest to share
+ * the options structure too. For encoding, all but the reserved variables
+ * need to be initialized unless specifically mentioned otherwise.
+ *
+ * For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and
+ * preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb.
  */
 typedef struct {
-	/**********************************
-	 * LZMA encoding/decoding options *
-	 **********************************/
-
-	/* These options are required in encoder and also with raw decoding. */
-
 	/**
 	 * \brief       Dictionary size in bytes
 	 *
@@ -298,10 +299,6 @@ typedef struct {
 #	define LZMA_PB_MAX      4
 #	define LZMA_PB_DEFAULT  2
 
-	/******************************************
-	 * LZMA options needed only when encoding *
-	 ******************************************/
-
 	/**
 	 * \brief       Indicate if the options structure is persistent
 	 *
@@ -377,6 +374,8 @@ typedef struct {
 	 * with the currently supported options, so it is safe to leave these
 	 * uninitialized.
 	 */
+	void *reserved_ptr1;
+	void *reserved_ptr2;
 	uint32_t reserved_int1;
 	uint32_t reserved_int2;
 	uint32_t reserved_int3;
@@ -385,20 +384,26 @@ typedef struct {
 	uint32_t reserved_int6;
 	uint32_t reserved_int7;
 	uint32_t reserved_int8;
-	void *reserved_ptr1;
-	void *reserved_ptr2;
+	lzma_reserved_enum reserved_enum1;
+	lzma_reserved_enum reserved_enum2;
+	lzma_reserved_enum reserved_enum3;
+	lzma_reserved_enum reserved_enum4;
 
 } lzma_options_lzma;
 
 
 /**
- * \brief       Set a compression level preset to lzma_options_lzma structure
+ * \brief       Set a compression preset to lzma_options_lzma structure
  *
- * level = 1 is the fastest and level = 9 is the slowest. These presets match
- * the switches -1 .. -9 of the command line tool.
+ * 0 is the fastest and 9 is the slowest. These match the switches -0 .. -9
+ * of the xz command line tool. In addition, it is possible to bitwise-or
+ * flags to the preset. Currently only LZMA_PRESET_EXTREME is supported.
+ * The flags are defined in container.h, because the flags are used also
+ * with lzma_easy_encoder().
  *
  * The preset values are subject to changes between liblzma versions.
  *
- * This function is available only if LZMA encoder has been enabled.
+ * This function is available only if LZMA1 or LZMA2 encoder has been enabled
+ * when building liblzma.
  */
-extern lzma_bool lzma_lzma_preset(lzma_options_lzma *options, uint32_t level);
+extern lzma_bool lzma_lzma_preset(lzma_options_lzma *options, uint32_t preset);