-
Notifications
You must be signed in to change notification settings - Fork 10
/
puff_README.txt
94 lines (70 loc) · 4.42 KB
/
puff_README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
Puff -- A Simple Inflate
3 Mar 2003
Mark Adler
madler@alumni.caltech.edu
What this is --
puff.c provides the routine puff() to decompress the deflate data format. It
does so more slowly than zlib, but the code is about one-fifth the size of the
inflate code in zlib, and written to be very easy to read.
Why I wrote this --
puff.c was written to document the deflate format unambiguously, by virtue of
being working C code. It is meant to supplement RFC 1951, which formally
describes the deflate format. I have received many questions on details of the
deflate format, and I hope that reading this code will answer those questions.
puff.c is heavily commented with details of the deflate format, especially
those little nooks and cranies of the format that might not be obvious from a
specification.
puff.c may also be useful in applications where code size or memory usage is a
very limited resource, and speed is not as important.
How to use it --
Well, most likely you should just be reading puff.c and using zlib for actual
applications, but if you must ...
Include puff.h in your code, which provides this prototype:
int puff(unsigned char *dest, /* pointer to destination pointer */
unsigned long *destlen, /* amount of output space */
unsigned char *source, /* pointer to source data pointer */
unsigned long *sourcelen); /* amount of input available */
Then you can call puff() to decompress a deflate stream that is in memory in
its entirety at source, to a sufficiently sized block of memory for the
decompressed data at dest. puff() is the only external symbol in puff.c The
only C library functions that puff.c needs are setjmp() and longjmp(), which
are used to simplify error checking in the code to improve readability. puff.c
does no memory allocation, and uses less than 2K bytes off of the stack.
If destlen is not enough space for the uncompressed data, then inflate will
return an error without writing more than destlen bytes. Note that this means
that in order to decompress the deflate data successfully, you need to know
the size of the uncompressed data ahead of time.
If needed, puff() can determine the size of the uncompressed data with no
output space. This is done by passing dest equal to (unsigned char *)0. Then
the initial value of *destlen is ignored and *destlen is set to the length of
the uncompressed data. So if the size of the uncompressed data is not known,
then two passes of puff() can be used--first to determine the size, and second
to do the actual inflation after allocating the appropriate memory. Not
pretty, but it works. (This is one of the reasons you should be using zlib.)
The deflate format is self-terminating. If the deflate stream does not end
in *sourcelen bytes, puff() will return an error without reading at or past
endsource.
On return, *sourcelen is updated to the amount of input data consumed, and
*destlen is updated to the size of the uncompressed data. See the comments
in puff.c for the possible return codes for puff().
--------------
Notes by Tursi for libti99
You must test your data before using it - any decompression error will simply
call halt right now, which just blindly stops your program. I would recommend
downloading zlib and building the command-line puff for your OS of choice, you
can then test the exact code on the exact stream you wish to use very easily.
(It's in the contrib/puff folder).
Other than ripping out the error handling temporarily, I've made no changes to
puff, it seems to work fine.
The easiest way to create the raw deflate stream is to use gzip. I had some strange
issues with streams that didn't work if I used long source filenames, so I recommend
using the -n setting so that gzip doesn't put a filename into the output file.
gzip -n myData
That will give you myData.gz. Now you just need to strip off the header information.
The first 10 bytes (in this case!) will be the gzip header, you can just strip that.
The last 8 bytes are a 32-bit data CRC and 32-bit data size, both big endian. You can
strip or use them at your discretion, but this function won't use them.
The documentation for puff notes that all the data lives on the stack, and it takes
up to about 2k. That's a fair bit for our little machine, especially since stack lives
in the 8k block, but for now I think it's easily livable, so I didn't make any changes.
(I also didn't verify this claim as yet... but my testlib test used about 656 bytes of stack.)