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