contrib/xz/src/liblzma/api/lzma/subblock.h

   1 /**
   2  * \file        lzma/subblock.h
   3  * \brief       Subblock filter
   4  */
   5
   6 /*
   7  * Author: Lasse Collin
   8  *
   9  * This file has been put into the public domain.
  10  * You can do whatever you want with this file.
  11  *
  12  * See ../lzma.h for information about liblzma as a whole.
  13  */
  14
  15 #ifndef LZMA_H_INTERNAL
  16 #       error Never include this file directly. Use <lzma.h> instead.
  17 #endif
  18
  19
  20 /**
  21  * \brief       Filter ID
  22  *
  23  * Filter ID of the Subblock filter. This is used as lzma_filter.id.
  24  */
  25 #define LZMA_FILTER_SUBBLOCK    LZMA_VLI_C(0x01)
  26
  27
  28 /**
  29  * \brief       Subfilter mode
  30  *
  31  * See lzma_options_subblock.subfilter_mode for details.
  32  */
  33 typedef enum {
  34         LZMA_SUBFILTER_NONE,
  35                 /**<
  36                  * No Subfilter is in use.
  37                  */
  38
  39         LZMA_SUBFILTER_SET,
  40                 /**<
  41                  * New Subfilter has been requested to be initialized.
  42                  */
  43
  44         LZMA_SUBFILTER_RUN,
  45                 /**<
  46                  * Subfilter is active.
  47                  */
  48
  49         LZMA_SUBFILTER_FINISH
  50                 /**<
  51                  * Subfilter has been requested to be finished.
  52                  */
  53 } lzma_subfilter_mode;
  54
  55
  56 /**
  57  * \brief       Options for the Subblock filter
  58  *
  59  * Specifying options for the Subblock filter is optional: if the pointer
  60  * options is NULL, no subfilters are allowed and the default value is used
  61  * for subblock_data_size.
  62  */
  63 typedef struct {
  64         /* Options for encoder and decoder */
  65
  66         /**
  67          * \brief       Allowing subfilters
  68          *
  69          * If this true, subfilters are allowed.
  70          *
  71          * In the encoder, if this is set to false, subfilter_mode and
  72          * subfilter_options are completely ignored.
  73          */
  74         lzma_bool allow_subfilters;
  75
  76         /* Options for encoder only */
  77
  78         /**
  79          * \brief       Alignment
  80          *
  81          * The Subblock filter encapsulates the input data into Subblocks.
  82          * Each Subblock has a header which takes a few bytes of space.
  83          * When the output of the Subblock encoder is fed to another filter
  84          * that takes advantage of the alignment of the input data (e.g. LZMA),
  85          * the Subblock filter can add padding to keep the actual data parts
  86          * in the Subblocks aligned correctly.
  87          *
  88          * The alignment should be a positive integer. Subblock filter will
  89          * add enough padding between Subblocks so that this is true for
  90          * every payload byte:
  91          * input_offset % alignment == output_offset % alignment
  92          *
  93          * The Subblock filter assumes that the first output byte will be
  94          * written to a position in the output stream that is properly
  95          * aligned. This requirement is automatically met when the start
  96          * offset of the Stream or Block is correctly told to Block or
  97          * Stream encoder.
  98          */
  99         uint32_t alignment;
 100 #       define LZMA_SUBBLOCK_ALIGNMENT_MIN 1
 101 #       define LZMA_SUBBLOCK_ALIGNMENT_MAX 32
 102 #       define LZMA_SUBBLOCK_ALIGNMENT_DEFAULT 4
 103
 104         /**
 105          * \brief       Size of the Subblock Data part of each Subblock
 106          *
 107          * This value is re-read every time a new Subblock is started.
 108          *
 109          * Bigger values
 110          *   - save a few bytes of space;
 111          *   - increase latency in the encoder (but no effect for decoding);
 112          *   - decrease memory locality (increased cache pollution) in the
 113          *     encoder (no effect in decoding).
 114          */
 115         uint32_t subblock_data_size;
 116 #       define LZMA_SUBBLOCK_DATA_SIZE_MIN 1
 117 #       define LZMA_SUBBLOCK_DATA_SIZE_MAX (UINT32_C(1) << 28)
 118 #       define LZMA_SUBBLOCK_DATA_SIZE_DEFAULT 4096
 119
 120         /**
 121          * \brief       Run-length encoder remote control
 122          *
 123          * The Subblock filter has an internal run-length encoder (RLE). It
 124          * can be useful when the data includes byte sequences that repeat
 125          * very many times. The RLE can be used also when a Subfilter is
 126          * in use; the RLE will be applied to the output of the Subfilter.
 127          *
 128          * Note that in contrast to traditional RLE, this RLE is intended to
 129          * be used only when there's a lot of data to be repeated. If the
 130          * input data has e.g. 500 bytes of NULs now and then, this RLE
 131          * is probably useless, because plain LZMA should provide better
 132          * results.
 133          *
 134          * Due to above reasons, it was decided to keep the implementation
 135          * of the RLE very simple. When the rle variable is non-zero, it
 136          * subblock_data_size must be a multiple of rle. Once the Subblock
 137          * encoder has got subblock_data_size bytes of input, it will check
 138          * if the whole buffer of the last subblock_data_size can be
 139          * represented with repeats of chunks having size of rle bytes.
 140          *
 141          * If there are consecutive identical buffers of subblock_data_size
 142          * bytes, they will be encoded using a single repeat entry if
 143          * possible.
 144          *
 145          * If need arises, more advanced RLE can be implemented later
 146          * without breaking API or ABI.
 147          */
 148         uint32_t rle;
 149 #       define LZMA_SUBBLOCK_RLE_OFF 0
 150 #       define LZMA_SUBBLOCK_RLE_MIN 1
 151 #       define LZMA_SUBBLOCK_RLE_MAX 256
 152
 153         /**
 154          * \brief       Subfilter remote control
 155          *
 156          * When the Subblock filter is initialized, this variable must be
 157          * LZMA_SUBFILTER_NONE or LZMA_SUBFILTER_SET.
 158          *
 159          * When subfilter_mode is LZMA_SUBFILTER_NONE, the application may
 160          * put Subfilter options to subfilter_options structure, and then
 161          * set subfilter_mode to LZMA_SUBFILTER_SET. No new input data will
 162          * be read until the Subfilter has been enabled. Once the Subfilter
 163          * has been enabled, liblzma will set subfilter_mode to
 164          * LZMA_SUBFILTER_RUN.
 165          *
 166          * When subfilter_mode is LZMA_SUBFILTER_RUN, the application may
 167          * set subfilter_mode to LZMA_SUBFILTER_FINISH. All the input
 168          * currently available will be encoded before unsetting the
 169          * Subfilter. Application must not change the amount of available
 170          * input until the Subfilter has finished. Once the Subfilter has
 171          * finished, liblzma will set subfilter_mode to LZMA_SUBFILTER_NONE.
 172          *
 173          * If the intent is to have Subfilter enabled to the very end of
 174          * the data, it is not needed to separately disable Subfilter with
 175          * LZMA_SUBFILTER_FINISH. Using LZMA_FINISH as the second argument
 176          * of lzma_code() will make the Subblock encoder to disable the
 177          * Subfilter once all the data has been ran through the Subfilter.
 178          *
 179          * After the first call with LZMA_SYNC_FLUSH or LZMA_FINISH, the
 180          * application must not change subfilter_mode until LZMA_STREAM_END.
 181          * Setting LZMA_SUBFILTER_SET/LZMA_SUBFILTER_FINISH and
 182          * LZMA_SYNC_FLUSH/LZMA_FINISH _at the same time_ is fine.
 183          *
 184          * \note        This variable is ignored if allow_subfilters is false.
 185          */
 186         lzma_subfilter_mode subfilter_mode;
 187
 188         /**
 189          * \brief       Subfilter and its options
 190          *
 191          * When no Subfilter is used, the data is copied as is into Subblocks.
 192          * Setting a Subfilter allows encoding some parts of the data with
 193          * an additional filter. It is possible to many different Subfilters
 194          * in the same Block, although only one can be used at once.
 195          *
 196          * \note        This variable is ignored if allow_subfilters is false.
 197          */
 198         lzma_filter subfilter_options;
 199
 200 } lzma_options_subblock;