~ubuntu-branches/ubuntu/maverick/uboot-imx/maverick

« back to all changes in this revision

Viewing changes to lib_generic/lzma/lzma.txt

  • Committer: Bazaar Package Importer
  • Author(s): Oliver Grawert
  • Date: 2010-01-20 15:41:26 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20100120154126-7bha1jeyjegu7xm5
Tags: 2009.08+really2009.01-0ubuntu1
* revert to the 2009.01 upstream version, 2009.08 has still to 
  many work in progress items in the freescale patchset (MMC and NIC
  dont work at all)
* add the latest patchset from freescale for 2009.01
* add 1002_enable_hush_shell_and_ext2.patch to enable hush shell and ext2 
* add 1003_fix_board_revision_numbers to make sure babbage 2.5 boards have 
  revision 51120 and babbage 3.0 boards have revision 51130 properly set in 
  their cpuinfo

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
LZMA SDK 4.65
 
1
LZMA SDK 4.57
2
2
-------------
3
3
 
 
4
LZMA SDK   Copyright (C) 1999-2007 Igor Pavlov
 
5
 
4
6
LZMA SDK provides the documentation, samples, header files, libraries,
5
7
and tools you need to develop applications that use LZMA compression.
6
8
 
18
20
LICENSE
19
21
-------
20
22
 
21
 
LZMA SDK is written and placed in the public domain by Igor Pavlov.
 
23
LZMA SDK is available under any of the following licenses:
 
24
 
 
25
1) GNU Lesser General Public License (GNU LGPL)
 
26
2) Common Public License (CPL)
 
27
3) Simplified license for unmodified code (read SPECIAL EXCEPTION)
 
28
4) Proprietary license
 
29
 
 
30
It means that you can select one of these four options and follow rules of that license.
 
31
 
 
32
 
 
33
1,2) GNU LGPL and CPL licenses are pretty similar and both these
 
34
licenses are classified as
 
35
 - "Free software licenses" at http://www.gnu.org/
 
36
 - "OSI-approved" at http://www.opensource.org/
 
37
 
 
38
 
 
39
3) SPECIAL EXCEPTION
 
40
 
 
41
Igor Pavlov, as the author of this code, expressly permits you
 
42
to statically or dynamically link your code (or bind by name)
 
43
to the files from LZMA SDK without subjecting your linked
 
44
code to the terms of the CPL or GNU LGPL.
 
45
Any modifications or additions to files from LZMA SDK, however,
 
46
are subject to the GNU LGPL or CPL terms.
 
47
 
 
48
SPECIAL EXCEPTION allows you to use LZMA SDK in applications with closed code,
 
49
while you keep LZMA SDK code unmodified.
 
50
 
 
51
 
 
52
SPECIAL EXCEPTION #2: Igor Pavlov, as the author of this code, expressly permits
 
53
you to use this code under the same terms and conditions contained in the License
 
54
Agreement you have for any previous version of LZMA SDK developed by Igor Pavlov.
 
55
 
 
56
SPECIAL EXCEPTION #2 allows owners of proprietary licenses to use latest version
 
57
of LZMA SDK as update for previous versions.
 
58
 
 
59
 
 
60
SPECIAL EXCEPTION #3: Igor Pavlov, as the author of this code, expressly permits
 
61
you to use code of the following files:
 
62
BranchTypes.h, LzmaTypes.h, LzmaTest.c, LzmaStateTest.c, LzmaAlone.cpp,
 
63
LzmaAlone.cs, LzmaAlone.java
 
64
as public domain code.
 
65
 
 
66
 
 
67
4) Proprietary license
 
68
 
 
69
LZMA SDK also can be available under a proprietary license which
 
70
can include:
 
71
 
 
72
1) Right to modify code without subjecting modified code to the
 
73
terms of the CPL or GNU LGPL
 
74
2) Technical support for code
 
75
 
 
76
To request such proprietary license or any additional consultations,
 
77
send email message from that page:
 
78
http://www.7-zip.org/support.html
 
79
 
 
80
 
 
81
You should have received a copy of the GNU Lesser General Public
 
82
License along with this library; if not, write to the Free Software
 
83
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
84
 
 
85
You should have received a copy of the Common Public License
 
86
along with this library.
22
87
 
23
88
 
24
89
LZMA SDK Contents
26
91
 
27
92
LZMA SDK includes:
28
93
 
29
 
  - ANSI-C/C++/C#/Java source code for LZMA compressing and decompressing
 
94
  - C++ source code of LZMA compressing and decompressing
 
95
  - ANSI-C compatible source code for LZMA decompressing
 
96
  - C# source code for LZMA compressing and decompressing
 
97
  - Java source code for LZMA compressing and decompressing
30
98
  - Compiled file->file LZMA compressing/decompressing program for Windows system
31
99
 
 
100
ANSI-C LZMA decompression code was ported from original C++ sources to C.
 
101
Also it was simplified and optimized for code size.
 
102
But it is fully compatible with LZMA from 7-Zip.
 
103
 
32
104
 
33
105
UNIX/Linux version
34
106
------------------
35
 
To compile C++ version of file->file LZMA encoding, go to directory
36
 
C++/7zip/Compress/LZMA_Alone
37
 
and call make to recompile it:
38
 
  make -f makefile.gcc clean all
 
107
To compile C++ version of file->file LZMA, go to directory
 
108
C/7zip/Compress/LZMA_Alone
 
109
and type "make" or "make clean all" to recompile all.
39
110
 
40
111
In some UNIX/Linux versions you must compile LZMA with static libraries.
41
 
To compile with static libraries, you can use
 
112
To compile with static libraries, change string in makefile
 
113
LIB = -lm
 
114
to string
42
115
LIB = -lm -static
43
116
 
44
117
 
45
118
Files
46
119
---------------------
47
 
lzma.txt     - LZMA SDK description (this file)
 
120
C        - C source code
 
121
CPP      - CPP source code
 
122
CS       - C# source code
 
123
Java     - Java source code
 
124
lzma.txt - LZMA SDK description (this file)
48
125
7zFormat.txt - 7z Format description
49
 
7zC.txt      - 7z ANSI-C Decoder description
 
126
7zC.txt  - 7z ANSI-C Decoder description (this file)
50
127
methods.txt  - Compression method IDs for .7z
51
 
lzma.exe     - Compiled file->file LZMA encoder/decoder for Windows
52
 
history.txt  - history of the LZMA SDK
 
128
LGPL.txt - GNU Lesser General Public License
 
129
CPL.html - Common Public License
 
130
lzma.exe - Compiled file->file LZMA encoder/decoder for Windows
 
131
history.txt - history of the LZMA SDK
53
132
 
54
133
 
55
134
Source code structure
56
135
---------------------
57
136
 
58
 
C/  - C files
59
 
        7zCrc*.*   - CRC code
60
 
        Alloc.*    - Memory allocation functions
61
 
        Bra*.*     - Filters for x86, IA-64, ARM, ARM-Thumb, PowerPC and SPARC code
62
 
        LzFind.*   - Match finder for LZ (LZMA) encoders
63
 
        LzFindMt.* - Match finder for LZ (LZMA) encoders for multithreading encoding
64
 
        LzHash.h   - Additional file for LZ match finder
65
 
        LzmaDec.*  - LZMA decoding
66
 
        LzmaEnc.*  - LZMA encoding
67
 
        LzmaLib.*  - LZMA Library for DLL calling
68
 
        Types.h    - Basic types for another .c files
69
 
        Threads.*  - The code for multithreading.
70
 
 
71
 
    LzmaLib  - LZMA Library (.DLL for Windows)
72
 
 
73
 
    LzmaUtil - LZMA Utility (file->file LZMA encoder/decoder).
 
137
C  - C files
 
138
    Compress - files related to compression/decompression
 
139
      Lz     - files related to LZ (Lempel-Ziv) compression algorithm
 
140
      Lzma   - ANSI-C compatible LZMA decompressor
 
141
 
 
142
        LzmaDecode.h  - interface for LZMA decoding on ANSI-C
 
143
        LzmaDecode.c      - LZMA decoding on ANSI-C (new fastest version)
 
144
        LzmaDecodeSize.c  - LZMA decoding on ANSI-C (old size-optimized version)
 
145
        LzmaTest.c        - test application that decodes LZMA encoded file
 
146
        LzmaTypes.h       - basic types for LZMA Decoder
 
147
        LzmaStateDecode.h - interface for LZMA decoding (State version)
 
148
        LzmaStateDecode.c - LZMA decoding on ANSI-C (State version)
 
149
        LzmaStateTest.c   - test application (State version)
 
150
 
 
151
      Branch       - Filters for x86, IA-64, ARM, ARM-Thumb, PowerPC and SPARC code
74
152
 
75
153
    Archive - files related to archiving
76
 
      7z     - 7z ANSI-C Decoder
77
 
 
78
 
CPP/ -- CPP files
 
154
      7z_C     - 7z ANSI-C Decoder
 
155
 
 
156
 
 
157
CPP -- CPP files
79
158
 
80
159
  Common  - common files for C++ projects
81
160
  Windows - common files for Windows related code
82
 
 
83
 
  7zip    - files related to 7-Zip Project
 
161
  7zip    - files related to 7-Zip Project
84
162
 
85
163
    Common   - common files for 7-Zip
86
164
 
87
165
    Compress - files related to compression/decompression
88
166
 
89
 
      Copy         - Copy coder
 
167
      LZ     - files related to LZ (Lempel-Ziv) compression algorithm
 
168
 
 
169
      Copy         - Copy coder
90
170
      RangeCoder   - Range Coder (special code of compression/decompression)
91
 
      LZMA         - LZMA compression/decompression on C++
 
171
      LZMA         - LZMA compression/decompression on C++
92
172
      LZMA_Alone   - file->file LZMA compression/decompression
93
 
      Branch       - Filters for x86, IA-64, ARM, ARM-Thumb, PowerPC and SPARC code
 
173
 
 
174
      Branch       - Filters for x86, IA-64, ARM, ARM-Thumb, PowerPC and SPARC code
94
175
 
95
176
    Archive - files related to archiving
96
177
 
99
180
 
100
181
    Bundles    - Modules that are bundles of other modules
101
182
 
102
 
      Alone7z           - 7zr.exe: Standalone version of 7z.exe that supports only 7z/LZMA/BCJ/BCJ2
103
 
      Format7zR         - 7zr.dll: Reduced version of 7za.dll: extracting/compressing to 7z/LZMA/BCJ/BCJ2
104
 
      Format7zExtractR  - 7zxr.dll: Reduced version of 7zxa.dll: extracting from 7z/LZMA/BCJ/BCJ2.
105
 
 
106
 
    UI        - User Interface files
107
 
 
108
 
      Client7z - Test application for 7za.dll,  7zr.dll, 7zxr.dll
 
183
      Alone7z           - 7zr.exe: Standalone version of 7z.exe that supports only 7z/LZMA/BCJ/BCJ2
 
184
      Format7zR         - 7zr.dll: Reduced version of 7za.dll: extracting/compressing to 7z/LZMA/BCJ/BCJ2
 
185
      Format7zExtractR  - 7zxr.dll: Reduced version of 7zxa.dll: extracting from 7z/LZMA/BCJ/BCJ2.
 
186
 
 
187
    UI        - User Interface files
 
188
 
 
189
      Client7z - Test application for 7za.dll,  7zr.dll, 7zxr.dll
109
190
      Common   - Common UI files
110
191
      Console  - Code for console archiver
111
192
 
112
193
 
113
194
 
114
 
CS/ - C# files
 
195
CS - C# files
115
196
  7zip
116
197
    Common   - some common files for 7-Zip
117
198
    Compress - files related to compression/decompression
118
199
      LZ     - files related to LZ (Lempel-Ziv) compression algorithm
119
 
      LZMA         - LZMA compression/decompression
 
200
      LZMA         - LZMA compression/decompression
120
201
      LzmaAlone    - file->file LZMA compression/decompression
121
202
      RangeCoder   - Range Coder (special code of compression/decompression)
122
203
 
123
 
Java/  - Java files
 
204
Java  - Java files
124
205
  SevenZip
125
206
    Compression    - files related to compression/decompression
126
 
      LZ           - files related to LZ (Lempel-Ziv) compression algorithm
127
 
      LZMA         - LZMA compression/decompression
 
207
      LZ           - files related to LZ (Lempel-Ziv) compression algorithm
 
208
      LZMA         - LZMA compression/decompression
128
209
      RangeCoder   - Range Coder (special code of compression/decompression)
129
210
 
130
 
 
131
211
C/C++ source code of LZMA SDK is part of 7-Zip project.
 
212
 
 
213
You can find ANSI-C LZMA decompressing code at folder
 
214
  C/7zip/Compress/Lzma
 
215
7-Zip doesn't use that ANSI-C LZMA code and that code was developed
 
216
specially for this SDK. And files from C/7zip/Compress/Lzma do not need
 
217
files from other directories of SDK for compiling.
 
218
 
132
219
7-Zip source code can be downloaded from 7-Zip's SourceForge page:
133
220
 
134
221
  http://sourceforge.net/projects/sevenzip/
135
222
 
136
223
 
137
 
 
138
224
LZMA features
139
225
-------------
140
226
  - Variable dictionary size (up to 1 GB)
141
 
  - Estimated compressing speed: about 2 MB/s on 2 GHz CPU
 
227
  - Estimated compressing speed: about 1 MB/s on 1 GHz CPU
142
228
  - Estimated decompressing speed:
143
 
      - 20-30 MB/s on 2 GHz Core 2 or AMD Athlon 64
144
 
      - 1-2 MB/s on 200 MHz ARM, MIPS, PowerPC or other simple RISC
145
 
  - Small memory requirements for decompressing (16 KB + DictionarySize)
146
 
  - Small code size for decompressing: 5-8 KB
 
229
      - 8-12 MB/s on 1 GHz Intel Pentium 3 or AMD Athlon
 
230
      - 500-1000 KB/s on 100 MHz ARM, MIPS, PowerPC or other simple RISC
 
231
  - Small memory requirements for decompressing (8-32 KB + DictionarySize)
 
232
  - Small code size for decompressing: 2-8 KB (depending from
 
233
    speed optimizations)
147
234
 
148
235
LZMA decoder uses only integer operations and can be
149
236
implemented in any modern 32-bit CPU (or on 16-bit CPU with some conditions).
150
237
 
151
 
Some critical operations that affect the speed of LZMA decompression:
 
238
Some critical operations that affect to speed of LZMA decompression:
152
239
  1) 32*16 bit integer multiply
153
240
  2) Misspredicted branches (penalty mostly depends from pipeline length)
154
241
  3) 32-bit shift and arithmetic operations
155
242
 
156
 
The speed of LZMA decompressing mostly depends from CPU speed.
 
243
Speed of LZMA decompressing mostly depends from CPU speed.
157
244
Memory speed has no big meaning. But if your CPU has small data cache,
158
245
overall weight of memory speed will slightly increase.
159
246
 
164
251
Using LZMA encoder/decoder executable
165
252
--------------------------------------
166
253
 
167
 
Usage:  LZMA <e|d> inputFile outputFile [<switches>...]
 
254
Usage:  LZMA <e|d> inputFile outputFile [<switches>...]
168
255
 
169
256
  e: encode file
170
257
 
173
260
  b: Benchmark. There are two tests: compressing and decompressing
174
261
     with LZMA method. Benchmark shows rating in MIPS (million
175
262
     instructions per second). Rating value is calculated from
176
 
     measured speed and it is normalized with Intel's Core 2 results.
177
 
     Also Benchmark checks possible hardware errors (RAM
 
263
     measured speed and it is normalized with AMD Athlon 64 X2 CPU
 
264
     results. Also Benchmark checks possible hardware errors (RAM
178
265
     errors in most cases). Benchmark uses these settings:
179
 
     (-a1, -d21, -fb32, -mfbt4). You can change only -d parameter.
180
 
     Also you can change the number of iterations. Example for 30 iterations:
 
266
     (-a1, -d21, -fb32, -mfbt4). You can change only -d. Also you
 
267
     can change number of iterations. Example for 30 iterations:
181
268
       LZMA b 30
182
269
     Default number of iterations is 10.
183
270
 
185
272
 
186
273
 
187
274
  -a{N}:  set compression mode 0 = fast, 1 = normal
188
 
          default: 1 (normal)
 
275
          default: 1 (normal)
189
276
 
190
277
  d{N}:   Sets Dictionary size - [0, 30], default: 23 (8MB)
191
 
          The maximum value for dictionary size is 1 GB = 2^30 bytes.
192
 
          Dictionary size is calculated as DictionarySize = 2^N bytes.
193
 
          For decompressing file compressed by LZMA method with dictionary
194
 
          size D = 2^N you need about D bytes of memory (RAM).
 
278
          The maximum value for dictionary size is 1 GB = 2^30 bytes.
 
279
          Dictionary size is calculated as DictionarySize = 2^N bytes.
 
280
          For decompressing file compressed by LZMA method with dictionary
 
281
          size D = 2^N you need about D bytes of memory (RAM).
195
282
 
196
283
  -fb{N}: set number of fast bytes - [5, 273], default: 128
197
 
          Usually big number gives a little bit better compression ratio
198
 
          and slower compression process.
 
284
          Usually big number gives a little bit better compression ratio
 
285
          and slower compression process.
199
286
 
200
287
  -lc{N}: set number of literal context bits - [0, 8], default: 3
201
 
          Sometimes lc=4 gives gain for big files.
 
288
          Sometimes lc=4 gives gain for big files.
202
289
 
203
290
  -lp{N}: set number of literal pos bits - [0, 4], default: 0
204
 
          lp switch is intended for periodical data when period is
205
 
          equal 2^N. For example, for 32-bit (4 bytes)
206
 
          periodical data you can use lp=2. Often it's better to set lc0,
207
 
          if you change lp switch.
 
291
          lp switch is intended for periodical data when period is
 
292
          equal 2^N. For example, for 32-bit (4 bytes)
 
293
          periodical data you can use lp=2. Often it's better to set lc0,
 
294
          if you change lp switch.
208
295
 
209
296
  -pb{N}: set number of pos bits - [0, 4], default: 2
210
 
          pb switch is intended for periodical data
211
 
          when period is equal 2^N.
 
297
          pb switch is intended for periodical data
 
298
          when period is equal 2^N.
212
299
 
213
300
  -mf{MF_ID}: set Match Finder. Default: bt4.
214
 
              Algorithms from hc* group doesn't provide good compression
215
 
              ratio, but they often works pretty fast in combination with
216
 
              fast mode (-a0).
217
 
 
218
 
              Memory requirements depend from dictionary size
219
 
              (parameter "d" in table below).
220
 
 
221
 
               MF_ID     Memory                   Description
222
 
 
223
 
                bt2    d *  9.5 + 4MB  Binary Tree with 2 bytes hashing.
224
 
                bt3    d * 11.5 + 4MB  Binary Tree with 3 bytes hashing.
225
 
                bt4    d * 11.5 + 4MB  Binary Tree with 4 bytes hashing.
226
 
                hc4    d *  7.5 + 4MB  Hash Chain with 4 bytes hashing.
 
301
              Algorithms from hc* group doesn't provide good compression
 
302
              ratio, but they often works pretty fast in combination with
 
303
              fast mode (-a0).
 
304
 
 
305
              Memory requirements depend from dictionary size
 
306
              (parameter "d" in table below).
 
307
 
 
308
               MF_ID     Memory                   Description
 
309
 
 
310
                bt2    d *  9.5 + 4MB  Binary Tree with 2 bytes hashing.
 
311
                bt3    d * 11.5 + 4MB  Binary Tree with 3 bytes hashing.
 
312
                bt4    d * 11.5 + 4MB  Binary Tree with 4 bytes hashing.
 
313
                hc4    d *  7.5 + 4MB  Hash Chain with 4 bytes hashing.
227
314
 
228
315
  -eos:   write End Of Stream marker. By default LZMA doesn't write
229
 
          eos marker, since LZMA decoder knows uncompressed size
230
 
          stored in .lzma file header.
 
316
          eos marker, since LZMA decoder knows uncompressed size
 
317
          stored in .lzma file header.
231
318
 
232
 
  -si:    Read data from stdin (it will write End Of Stream marker).
233
 
  -so:    Write data to stdout
 
319
  -si:    Read data from stdin (it will write End Of Stream marker).
 
320
  -so:    Write data to stdout
234
321
 
235
322
 
236
323
Examples:
258
345
Recommendations
259
346
---------------
260
347
 
261
 
To increase the compression ratio for LZMA compressing it's desirable
 
348
To increase compression ratio for LZMA compressing it's desirable
262
349
to have aligned data (if it's possible) and also it's desirable to locate
263
350
data in such order, where code is grouped in one place and data is
264
351
grouped in other place (it's better than such mixing: code, data, code,
265
352
data, ...).
266
353
 
267
354
 
268
 
Filters
269
 
-------
270
 
You can increase the compression ratio for some data types, using
 
355
Using Filters
 
356
-------------
 
357
You can increase compression ratio for some data types, using
271
358
special filters before compressing. For example, it's possible to
272
 
increase the compression ratio on 5-10% for code for those CPU ISAs:
 
359
increase compression ratio on 5-10% for code for those CPU ISAs:
273
360
x86, IA-64, ARM, ARM-Thumb, PowerPC, SPARC.
274
361
 
275
 
You can find C source code of such filters in C/Bra*.* files
 
362
You can find C/C++ source code of such filters in folder "7zip/Compress/Branch"
276
363
 
277
 
You can check the compression ratio gain of these filters with such
 
364
You can check compression ratio gain of these filters with such
278
365
7-Zip commands (example for ARM code):
279
366
No filter:
280
367
  7z a a1.7z a.bin -m0=lzma
281
368
 
282
369
With filter for little-endian ARM code:
283
 
  7z a a2.7z a.bin -m0=arm -m1=lzma
 
370
  7z a a2.7z a.bin -m0=bc_arm -m1=lzma
 
371
 
 
372
With filter for big-endian ARM code (using additional Swap4 filter):
 
373
  7z a a3.7z a.bin -m0=swap4 -m1=bc_arm -m2=lzma
284
374
 
285
375
It works in such manner:
286
376
Compressing    = Filter_encoding + LZMA_encoding
293
383
 
294
384
These filters convert CALL (calling procedure) instructions
295
385
from relative offsets to absolute addresses, so such data becomes more
296
 
compressible.
 
386
compressible. Source code of these CALL filters is pretty simple
 
387
(about 20 lines of C++), so you can convert it from C++ version yourself.
297
388
 
298
389
For some ISAs (for example, for MIPS) it's impossible to get gain from such filter.
299
390
 
301
392
LZMA compressed file format
302
393
---------------------------
303
394
Offset Size Description
304
 
  0     1   Special LZMA properties (lc,lp, pb in encoded form)
305
 
  1     4   Dictionary size (little endian)
306
 
  5     8   Uncompressed size (little endian). -1 means unknown size
307
 
 13         Compressed data
 
395
  0     1   Special LZMA properties for compressed data
 
396
  1     4   Dictionary size (little endian)
 
397
  5     8   Uncompressed size (little endian). -1 means unknown size
 
398
 13         Compressed data
308
399
 
309
400
 
310
401
ANSI-C LZMA Decoder
311
402
~~~~~~~~~~~~~~~~~~~
312
403
 
313
 
Please note that interfaces for ANSI-C code were changed in LZMA SDK 4.58.
314
 
If you want to use old interfaces you can download previous version of LZMA SDK
315
 
from sourceforge.net site.
316
 
 
317
 
To use ANSI-C LZMA Decoder you need the following files:
318
 
1) LzmaDec.h + LzmaDec.c + Types.h
319
 
LzmaUtil/LzmaUtil.c is example application that uses these files.
 
404
To compile ANSI-C LZMA Decoder you can use one of the following files sets:
 
405
1) LzmaDecode.h + LzmaDecode.c + LzmaTest.c  (fastest version)
 
406
2) LzmaDecode.h + LzmaDecodeSize.c + LzmaTest.c  (old size-optimized version)
 
407
3) LzmaStateDecode.h + LzmaStateDecode.c + LzmaStateTest.c  (zlib-like interface)
320
408
 
321
409
 
322
410
Memory requirements for LZMA decoding
323
411
-------------------------------------
324
412
 
 
413
LZMA decoder doesn't allocate memory itself, so you must
 
414
allocate memory and send it to LZMA.
 
415
 
325
416
Stack usage of LZMA decoding function for local variables is not
326
 
larger than 200-400 bytes.
327
 
 
328
 
LZMA Decoder uses dictionary buffer and internal state structure.
329
 
Internal state structure consumes
330
 
  state_size = (4 + (1.5 << (lc + lp))) KB
331
 
by default (lc=3, lp=0), state_size = 16 KB.
332
 
 
 
417
larger than 200 bytes.
333
418
 
334
419
How To decompress data
335
420
----------------------
336
421
 
337
 
LZMA Decoder (ANSI-C version) now supports 2 interfaces:
 
422
LZMA Decoder (ANSI-C version) now supports 5 interfaces:
338
423
1) Single-call Decompressing
339
 
2) Multi-call State Decompressing (zlib-like interface)
340
 
 
341
 
You must use external allocator:
342
 
Example:
343
 
void *SzAlloc(void *p, size_t size) { p = p; return malloc(size); }
344
 
void SzFree(void *p, void *address) { p = p; free(address); }
345
 
ISzAlloc alloc = { SzAlloc, SzFree };
346
 
 
347
 
You can use p = p; operator to disable compiler warnings.
348
 
 
349
 
 
350
 
Single-call Decompressing
351
 
-------------------------
 
424
2) Single-call Decompressing with input stream callback
 
425
3) Multi-call Decompressing with output buffer
 
426
4) Multi-call Decompressing with input callback and output buffer
 
427
5) Multi-call State Decompressing (zlib-like interface)
 
428
 
 
429
Variant-5 is similar to Variant-4, but Variant-5 doesn't use callback functions.
 
430
 
 
431
Decompressing steps
 
432
-------------------
 
433
 
 
434
1) read LZMA properties (5 bytes):
 
435
   unsigned char properties[LZMA_PROPERTIES_SIZE];
 
436
 
 
437
2) read uncompressed size (8 bytes, little-endian)
 
438
 
 
439
3) Decode properties:
 
440
 
 
441
  CLzmaDecoderState state;  /* it's 24-140 bytes structure, if int is 32-bit */
 
442
 
 
443
  if (LzmaDecodeProperties(&state.Properties, properties, LZMA_PROPERTIES_SIZE) != LZMA_RESULT_OK)
 
444
    return PrintError(rs, "Incorrect stream properties");
 
445
 
 
446
4) Allocate memory block for internal Structures:
 
447
 
 
448
  state.Probs = (CProb *)malloc(LzmaGetNumProbs(&state.Properties) * sizeof(CProb));
 
449
  if (state.Probs == 0)
 
450
    return PrintError(rs, kCantAllocateMessage);
 
451
 
 
452
  LZMA decoder uses array of CProb variables as internal structure.
 
453
  By default, CProb is unsigned_short. But you can define _LZMA_PROB32 to make
 
454
  it unsigned_int. It can increase speed on some 32-bit CPUs, but memory
 
455
  usage will be doubled in that case.
 
456
 
 
457
 
 
458
5) Main Decompressing
 
459
 
 
460
You must use one of the following interfaces:
 
461
 
 
462
5.1 Single-call Decompressing
 
463
-----------------------------
352
464
When to use: RAM->RAM decompressing
353
 
Compile files: LzmaDec.h + LzmaDec.c + Types.h
 
465
Compile files: LzmaDecode.h, LzmaDecode.c
354
466
Compile defines: no defines
355
467
Memory Requirements:
356
468
  - Input buffer: compressed size
357
469
  - Output buffer: uncompressed size
358
 
  - LZMA Internal Structures: state_size (16 KB for default settings)
359
 
 
360
 
Interface:
361
 
  int LzmaDecode(Byte *dest, SizeT *destLen, const Byte *src, SizeT *srcLen,
362
 
      const Byte *propData, unsigned propSize, ELzmaFinishMode finishMode,
363
 
      ELzmaStatus *status, ISzAlloc *alloc);
364
 
  In:
365
 
    dest     - output data
366
 
    destLen  - output data size
367
 
    src      - input data
368
 
    srcLen   - input data size
369
 
    propData - LZMA properties  (5 bytes)
370
 
    propSize - size of propData buffer (5 bytes)
371
 
    finishMode - It has meaning only if the decoding reaches output limit (*destLen).
372
 
         LZMA_FINISH_ANY - Decode just destLen bytes.
373
 
         LZMA_FINISH_END - Stream must be finished after (*destLen).
374
 
                           You can use LZMA_FINISH_END, when you know that
375
 
                           current output buffer covers last bytes of stream.
376
 
    alloc    - Memory allocator.
377
 
 
378
 
  Out:
379
 
    destLen  - processed output size
380
 
    srcLen   - processed input size
381
 
 
382
 
  Output:
383
 
    SZ_OK
384
 
      status:
385
 
        LZMA_STATUS_FINISHED_WITH_MARK
386
 
        LZMA_STATUS_NOT_FINISHED
387
 
        LZMA_STATUS_MAYBE_FINISHED_WITHOUT_MARK
388
 
    SZ_ERROR_DATA - Data error
389
 
    SZ_ERROR_MEM  - Memory allocation error
390
 
    SZ_ERROR_UNSUPPORTED - Unsupported properties
391
 
    SZ_ERROR_INPUT_EOF - It needs more bytes in input buffer (src).
392
 
 
393
 
  If LZMA decoder sees end_marker before reaching output limit, it returns OK result,
394
 
  and output value of destLen will be less than output buffer size limit.
395
 
 
396
 
  You can use multiple checks to test data integrity after full decompression:
397
 
    1) Check Result and "status" variable.
398
 
    2) Check that output(destLen) = uncompressedSize, if you know real uncompressedSize.
399
 
    3) Check that output(srcLen) = compressedSize, if you know real compressedSize.
400
 
       You must use correct finish mode in that case. */
401
 
 
402
 
 
403
 
Multi-call State Decompressing (zlib-like interface)
404
 
----------------------------------------------------
405
 
 
406
 
When to use: file->file decompressing
407
 
Compile files: LzmaDec.h + LzmaDec.c + Types.h
408
 
 
409
 
Memory Requirements:
410
 
 - Buffer for input stream: any size (for example, 16 KB)
411
 
 - Buffer for output stream: any size (for example, 16 KB)
412
 
 - LZMA Internal Structures: state_size (16 KB for default settings)
413
 
 - LZMA dictionary (dictionary size is encoded in LZMA properties header)
414
 
 
415
 
1) read LZMA properties (5 bytes) and uncompressed size (8 bytes, little-endian) to header:
416
 
   unsigned char header[LZMA_PROPS_SIZE + 8];
417
 
   ReadFile(inFile, header, sizeof(header)
418
 
 
419
 
2) Allocate CLzmaDec structures (state + dictionary) using LZMA properties
420
 
 
421
 
  CLzmaDec state;
422
 
  LzmaDec_Constr(&state);
423
 
  res = LzmaDec_Allocate(&state, header, LZMA_PROPS_SIZE, &g_Alloc);
424
 
  if (res != SZ_OK)
425
 
    return res;
426
 
 
427
 
3) Init LzmaDec structure before any new LZMA stream. And call LzmaDec_DecodeToBuf in loop
428
 
 
429
 
  LzmaDec_Init(&state);
430
 
  for (;;)
431
 
  {
432
 
    ...
433
 
    int res = LzmaDec_DecodeToBuf(CLzmaDec *p, Byte *dest, SizeT *destLen,
434
 
        const Byte *src, SizeT *srcLen, ELzmaFinishMode finishMode);
435
 
    ...
436
 
  }
437
 
 
438
 
 
439
 
4) Free all allocated structures
440
 
  LzmaDec_Free(&state, &g_Alloc);
441
 
 
442
 
For full code example, look at C/LzmaUtil/LzmaUtil.c code.
443
 
 
444
 
 
445
 
How To compress data
446
 
--------------------
447
 
 
448
 
Compile files: LzmaEnc.h + LzmaEnc.c + Types.h +
449
 
LzFind.c + LzFind.h + LzFindMt.c + LzFindMt.h + LzHash.h
450
 
 
451
 
Memory Requirements:
452
 
  - (dictSize * 11.5 + 6 MB) + state_size
453
 
 
454
 
Lzma Encoder can use two memory allocators:
455
 
1) alloc - for small arrays.
456
 
2) allocBig - for big arrays.
457
 
 
458
 
For example, you can use Large RAM Pages (2 MB) in allocBig allocator for
459
 
better compression speed. Note that Windows has bad implementation for
460
 
Large RAM Pages.
461
 
It's OK to use same allocator for alloc and allocBig.
462
 
 
463
 
 
464
 
Single-call Compression with callbacks
465
 
--------------------------------------
466
 
 
467
 
Check C/LzmaUtil/LzmaUtil.c as example,
468
 
 
469
 
When to use: file->file decompressing
470
 
 
471
 
1) you must implement callback structures for interfaces:
472
 
ISeqInStream
473
 
ISeqOutStream
474
 
ICompressProgress
475
 
ISzAlloc
476
 
 
477
 
static void *SzAlloc(void *p, size_t size) { p = p; return MyAlloc(size); }
478
 
static void SzFree(void *p, void *address) {  p = p; MyFree(address); }
479
 
static ISzAlloc g_Alloc = { SzAlloc, SzFree };
480
 
 
481
 
  CFileSeqInStream inStream;
482
 
  CFileSeqOutStream outStream;
483
 
 
484
 
  inStream.funcTable.Read = MyRead;
485
 
  inStream.file = inFile;
486
 
  outStream.funcTable.Write = MyWrite;
487
 
  outStream.file = outFile;
488
 
 
489
 
 
490
 
2) Create CLzmaEncHandle object;
491
 
 
492
 
  CLzmaEncHandle enc;
493
 
 
494
 
  enc = LzmaEnc_Create(&g_Alloc);
495
 
  if (enc == 0)
496
 
    return SZ_ERROR_MEM;
497
 
 
498
 
 
499
 
3) initialize CLzmaEncProps properties;
500
 
 
501
 
  LzmaEncProps_Init(&props);
502
 
 
503
 
  Then you can change some properties in that structure.
504
 
 
505
 
4) Send LZMA properties to LZMA Encoder
506
 
 
507
 
  res = LzmaEnc_SetProps(enc, &props);
508
 
 
509
 
5) Write encoded properties to header
510
 
 
511
 
    Byte header[LZMA_PROPS_SIZE + 8];
512
 
    size_t headerSize = LZMA_PROPS_SIZE;
513
 
    UInt64 fileSize;
514
 
    int i;
515
 
 
516
 
    res = LzmaEnc_WriteProperties(enc, header, &headerSize);
517
 
    fileSize = MyGetFileLength(inFile);
518
 
    for (i = 0; i < 8; i++)
519
 
      header[headerSize++] = (Byte)(fileSize >> (8 * i));
520
 
    MyWriteFileAndCheck(outFile, header, headerSize)
521
 
 
522
 
6) Call encoding function:
523
 
      res = LzmaEnc_Encode(enc, &outStream.funcTable, &inStream.funcTable,
524
 
        NULL, &g_Alloc, &g_Alloc);
525
 
 
526
 
7) Destroy LZMA Encoder Object
527
 
  LzmaEnc_Destroy(enc, &g_Alloc, &g_Alloc);
528
 
 
529
 
 
530
 
If callback function return some error code, LzmaEnc_Encode also returns that code.
531
 
 
532
 
 
533
 
Single-call RAM->RAM Compression
534
 
--------------------------------
535
 
 
536
 
Single-call RAM->RAM Compression is similar to Compression with callbacks,
537
 
but you provide pointers to buffers instead of pointers to stream callbacks:
538
 
 
539
 
HRes LzmaEncode(Byte *dest, SizeT *destLen, const Byte *src, SizeT srcLen,
540
 
    CLzmaEncProps *props, Byte *propsEncoded, SizeT *propsSize, int writeEndMark,
541
 
    ICompressProgress *progress, ISzAlloc *alloc, ISzAlloc *allocBig);
542
 
 
543
 
Return code:
544
 
  SZ_OK               - OK
545
 
  SZ_ERROR_MEM        - Memory allocation error
546
 
  SZ_ERROR_PARAM      - Incorrect paramater
547
 
  SZ_ERROR_OUTPUT_EOF - output buffer overflow
548
 
  SZ_ERROR_THREAD     - errors in multithreading functions (only for Mt version)
 
470
  - LZMA Internal Structures (~16 KB for default settings)
 
471
 
 
472
Interface:
 
473
  int res = LzmaDecode(&state,
 
474
      inStream, compressedSize, &inProcessed,
 
475
      outStream, outSize, &outProcessed);
 
476
 
 
477
 
 
478
5.2 Single-call Decompressing with input stream callback
 
479
--------------------------------------------------------
 
480
When to use: File->RAM or Flash->RAM decompressing.
 
481
Compile files: LzmaDecode.h, LzmaDecode.c
 
482
Compile defines: _LZMA_IN_CB
 
483
Memory Requirements:
 
484
  - Buffer for input stream: any size (for example, 16 KB)
 
485
  - Output buffer: uncompressed size
 
486
  - LZMA Internal Structures (~16 KB for default settings)
 
487
 
 
488
Interface:
 
489
  typedef struct _CBuffer
 
490
  {
 
491
    ILzmaInCallback InCallback;
 
492
    FILE *File;
 
493
    unsigned char Buffer[kInBufferSize];
 
494
  } CBuffer;
 
495
 
 
496
  int LzmaReadCompressed(void *object, const unsigned char **buffer, SizeT *size)
 
497
  {
 
498
    CBuffer *bo = (CBuffer *)object;
 
499
    *buffer = bo->Buffer;
 
500
    *size = MyReadFile(bo->File, bo->Buffer, kInBufferSize);
 
501
    return LZMA_RESULT_OK;
 
502
  }
 
503
 
 
504
  CBuffer g_InBuffer;
 
505
 
 
506
  g_InBuffer.File = inFile;
 
507
  g_InBuffer.InCallback.Read = LzmaReadCompressed;
 
508
  int res = LzmaDecode(&state,
 
509
      &g_InBuffer.InCallback,
 
510
      outStream, outSize, &outProcessed);
 
511
 
 
512
 
 
513
5.3 Multi-call decompressing with output buffer
 
514
-----------------------------------------------
 
515
When to use: RAM->File decompressing
 
516
Compile files: LzmaDecode.h, LzmaDecode.c
 
517
Compile defines: _LZMA_OUT_READ
 
518
Memory Requirements:
 
519
 - Input buffer: compressed size
 
520
 - Buffer for output stream: any size (for example, 16 KB)
 
521
 - LZMA Internal Structures (~16 KB for default settings)
 
522
 - LZMA dictionary (dictionary size is encoded in stream properties)
 
523
 
 
524
Interface:
 
525
 
 
526
  state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
 
527
 
 
528
  LzmaDecoderInit(&state);
 
529
  do
 
530
  {
 
531
    LzmaDecode(&state,
 
532
      inBuffer, inAvail, &inProcessed,
 
533
      g_OutBuffer, outAvail, &outProcessed);
 
534
    inAvail -= inProcessed;
 
535
    inBuffer += inProcessed;
 
536
  }
 
537
  while you need more bytes
 
538
 
 
539
  see LzmaTest.c for more details.
 
540
 
 
541
 
 
542
5.4 Multi-call decompressing with input callback and output buffer
 
543
------------------------------------------------------------------
 
544
When to use: File->File decompressing
 
545
Compile files: LzmaDecode.h, LzmaDecode.c
 
546
Compile defines: _LZMA_IN_CB, _LZMA_OUT_READ
 
547
Memory Requirements:
 
548
 - Buffer for input stream: any size (for example, 16 KB)
 
549
 - Buffer for output stream: any size (for example, 16 KB)
 
550
 - LZMA Internal Structures (~16 KB for default settings)
 
551
 - LZMA dictionary (dictionary size is encoded in stream properties)
 
552
 
 
553
Interface:
 
554
 
 
555
  state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
 
556
 
 
557
  LzmaDecoderInit(&state);
 
558
  do
 
559
  {
 
560
    LzmaDecode(&state,
 
561
      &bo.InCallback,
 
562
      g_OutBuffer, outAvail, &outProcessed);
 
563
  }
 
564
  while you need more bytes
 
565
 
 
566
  see LzmaTest.c for more details:
 
567
 
 
568
 
 
569
5.5 Multi-call State Decompressing (zlib-like interface)
 
570
------------------------------------------------------------------
 
571
When to use: file->file decompressing
 
572
Compile files: LzmaStateDecode.h, LzmaStateDecode.c
 
573
Compile defines:
 
574
Memory Requirements:
 
575
 - Buffer for input stream: any size (for example, 16 KB)
 
576
 - Buffer for output stream: any size (for example, 16 KB)
 
577
 - LZMA Internal Structures (~16 KB for default settings)
 
578
 - LZMA dictionary (dictionary size is encoded in stream properties)
 
579
 
 
580
Interface:
 
581
 
 
582
  state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
 
583
 
 
584
 
 
585
  LzmaDecoderInit(&state);
 
586
  do
 
587
  {
 
588
    res = LzmaDecode(&state,
 
589
      inBuffer, inAvail, &inProcessed,
 
590
      g_OutBuffer, outAvail, &outProcessed,
 
591
      finishDecoding);
 
592
    inAvail -= inProcessed;
 
593
    inBuffer += inProcessed;
 
594
  }
 
595
  while you need more bytes
 
596
 
 
597
  see LzmaStateTest.c for more details:
 
598
 
 
599
 
 
600
6) Free all allocated blocks
 
601
 
 
602
 
 
603
Note
 
604
----
 
605
LzmaDecodeSize.c is size-optimized version of LzmaDecode.c.
 
606
But compiled code of LzmaDecodeSize.c can be larger than
 
607
compiled code of LzmaDecode.c. So it's better to use
 
608
LzmaDecode.c in most cases.
 
609
 
 
610
 
 
611
EXIT codes
 
612
-----------
 
613
 
 
614
LZMA decoder can return one of the following codes:
 
615
 
 
616
#define LZMA_RESULT_OK 0
 
617
#define LZMA_RESULT_DATA_ERROR 1
 
618
 
 
619
If you use callback function for input data and you return some
 
620
error code, LZMA Decoder also returns that code.
549
621
 
550
622
 
551
623
 
552
624
LZMA Defines
553
625
------------
554
626
 
555
 
_LZMA_SIZE_OPT - Enable some optimizations in LZMA Decoder to get smaller executable code.
556
 
 
557
 
_LZMA_PROB32   - It can increase the speed on some 32-bit CPUs, but memory usage for
558
 
                 some structures will be doubled in that case.
559
 
 
560
 
_LZMA_UINT32_IS_ULONG  - Define it if int is 16-bit on your compiler and long is 32-bit.
561
 
 
562
 
_LZMA_NO_SYSTEM_SIZE_T  - Define it if you don't want to use size_t type.
 
627
_LZMA_IN_CB    - Use callback for input data
 
628
 
 
629
_LZMA_OUT_READ - Use read function for output data
 
630
 
 
631
_LZMA_LOC_OPT  - Enable local speed optimizations inside code.
 
632
                 _LZMA_LOC_OPT is only for LzmaDecodeSize.c (size-optimized version).
 
633
                 _LZMA_LOC_OPT doesn't affect LzmaDecode.c (speed-optimized version)
 
634
                 and LzmaStateDecode.c
 
635
 
 
636
_LZMA_PROB32   - It can increase speed on some 32-bit CPUs,
 
637
                 but memory usage will be doubled in that case
 
638
 
 
639
_LZMA_UINT32_IS_ULONG  - Define it if int is 16-bit on your compiler
 
640
                         and long is 32-bit.
 
641
 
 
642
_LZMA_SYSTEM_SIZE_T  - Define it if you want to use system's size_t.
 
643
                       You can use it to enable 64-bit sizes supporting
 
644
 
563
645
 
564
646
 
565
647
C++ LZMA Encoder/Decoder
566
648
~~~~~~~~~~~~~~~~~~~~~~~~
567
649
C++ LZMA code use COM-like interfaces. So if you want to use it,
568
650
you can study basics of COM/OLE.
569
 
C++ LZMA code is just wrapper over ANSI-C code.
570
 
 
571
 
 
572
 
C++ Notes
573
 
~~~~~~~~~~~~~~~~~~~~~~~~
574
 
If you use some C++ code folders in 7-Zip (for example, C++ code for .7z handling),
575
 
you must check that you correctly work with "new" operator.
576
 
7-Zip can be compiled with MSVC 6.0 that doesn't throw "exception" from "new" operator.
577
 
So 7-Zip uses "CPP\Common\NewHandler.cpp" that redefines "new" operator:
578
 
operator new(size_t size)
579
 
{
580
 
  void *p = ::malloc(size);
581
 
  if (p == 0)
582
 
    throw CNewException();
583
 
  return p;
584
 
}
585
 
If you use MSCV that throws exception for "new" operator, you can compile without
586
 
"NewHandler.cpp". So standard exception will be used. Actually some code of
587
 
7-Zip catches any exception in internal code and converts it to HRESULT code.
588
 
So you don't need to catch CNewException, if you call COM interfaces of 7-Zip.
 
651
 
 
652
By default, LZMA Encoder contains all Match Finders.
 
653
But for compressing it's enough to have just one of them.
 
654
So for reducing size of compressing code you can define:
 
655
  #define COMPRESS_MF_BT
 
656
  #define COMPRESS_MF_BT4
 
657
and it will use only bt4 match finder.
 
658
 
589
659
 
590
660
---
591
661
 
592
662
http://www.7-zip.org
593
 
http://www.7-zip.org/sdk.html
594
663
http://www.7-zip.org/support.html