Commit 7850ad5c authored by David Gibson's avatar David Gibson Committed by Paul Mackerras

[POWERPC] Add documentation for the zImage's gunzip convenience functions

This patch adds documenting comments to the gunzip convenience
functions added in commit ad9d2716.
It also removes a stray newline, and an unused global variable.
Signed-off-by: default avatarDavid Gibson <david@gibson.dropbear.id.au>
Signed-off-by: default avatarPaul Mackerras <paulus@samba.org>
parent 0e0293c8
...@@ -14,14 +14,31 @@ ...@@ -14,14 +14,31 @@
#include "ops.h" #include "ops.h"
#include "gunzip_util.h" #include "gunzip_util.h"
struct gunzip_state state;
#define HEAD_CRC 2 #define HEAD_CRC 2
#define EXTRA_FIELD 4 #define EXTRA_FIELD 4
#define ORIG_NAME 8 #define ORIG_NAME 8
#define COMMENT 0x10 #define COMMENT 0x10
#define RESERVED 0xe0 #define RESERVED 0xe0
/**
* gunzip_start - prepare to decompress gzip data
* @state: decompressor state structure to be initialized
* @src: buffer containing gzip compressed or uncompressed data
* @srclen: size in bytes of the buffer at src
*
* If the buffer at @src contains a gzip header, this function
* initializes zlib to decompress the data, storing the decompression
* state in @state. The other functions in this file can then be used
* to decompress data from the gzipped stream.
*
* If the buffer at @src does not contain a gzip header, it is assumed
* to contain uncompressed data. The buffer information is recorded
* in @state and the other functions in this file will simply copy
* data from the uncompressed data stream at @src.
*
* Any errors, such as bad compressed data, cause an error to be
* printed an the platform's exit() function to be called.
*/
void gunzip_start(struct gunzip_state *state, void *src, int srclen) void gunzip_start(struct gunzip_state *state, void *src, int srclen)
{ {
char *hdr = src; char *hdr = src;
...@@ -73,6 +90,22 @@ void gunzip_start(struct gunzip_state *state, void *src, int srclen) ...@@ -73,6 +90,22 @@ void gunzip_start(struct gunzip_state *state, void *src, int srclen)
state->s.avail_in = srclen - hdrlen; state->s.avail_in = srclen - hdrlen;
} }
/**
* gunzip_partial - extract bytes from a gzip data stream
* @state: gzip state structure previously initialized by gunzip_start()
* @dst: buffer to store extracted data
* @dstlen: maximum number of bytes to extract
*
* This function extracts at most @dstlen bytes from the data stream
* previously associated with @state by gunzip_start(), decompressing
* if necessary. Exactly @dstlen bytes are extracted unless the data
* stream doesn't contain enough bytes, in which case the entire
* remainder of the stream is decompressed.
*
* Returns the actual number of bytes extracted. If any errors occur,
* such as a corrupted compressed stream, an error is printed an the
* platform's exit() function is called.
*/
int gunzip_partial(struct gunzip_state *state, void *dst, int dstlen) int gunzip_partial(struct gunzip_state *state, void *dst, int dstlen)
{ {
int len; int len;
...@@ -99,6 +132,20 @@ int gunzip_partial(struct gunzip_state *state, void *dst, int dstlen) ...@@ -99,6 +132,20 @@ int gunzip_partial(struct gunzip_state *state, void *dst, int dstlen)
return len; return len;
} }
/**
* gunzip_exactly - extract a fixed number of bytes from a gzip data stream
* @state: gzip state structure previously initialized by gunzip_start()
* @dst: buffer to store extracted data
* @dstlen: number of bytes to extract
*
* This function extracts exactly @dstlen bytes from the data stream
* previously associated with @state by gunzip_start(), decompressing
* if necessary.
*
* If there are less @dstlen bytes available in the data stream, or if
* any other errors occur, such as a corrupted compressed stream, an
* error is printed an the platform's exit() function is called.
*/
void gunzip_exactly(struct gunzip_state *state, void *dst, int dstlen) void gunzip_exactly(struct gunzip_state *state, void *dst, int dstlen)
{ {
int len; int len;
...@@ -110,6 +157,21 @@ void gunzip_exactly(struct gunzip_state *state, void *dst, int dstlen) ...@@ -110,6 +157,21 @@ void gunzip_exactly(struct gunzip_state *state, void *dst, int dstlen)
} }
} }
/**
* gunzip_discard - discard bytes from a gzip data stream
* @state: gzip state structure previously initialized by gunzip_start()
* @len: number of bytes to discard
*
* This function extracts, then discards exactly @len bytes from the
* data stream previously associated with @state by gunzip_start().
* Subsequent gunzip_partial(), gunzip_exactly() or gunzip_finish()
* calls will extract the data following the discarded bytes in the
* data stream.
*
* If there are less @len bytes available in the data stream, or if
* any other errors occur, such as a corrupted compressed stream, an
* error is printed an the platform's exit() function is called.
*/
void gunzip_discard(struct gunzip_state *state, int len) void gunzip_discard(struct gunzip_state *state, int len)
{ {
static char discard_buf[128]; static char discard_buf[128];
...@@ -123,6 +185,21 @@ void gunzip_discard(struct gunzip_state *state, int len) ...@@ -123,6 +185,21 @@ void gunzip_discard(struct gunzip_state *state, int len)
gunzip_exactly(state, discard_buf, len); gunzip_exactly(state, discard_buf, len);
} }
/**
* gunzip_finish - extract all remaining bytes from a gzip data stream
* @state: gzip state structure previously initialized by gunzip_start()
* @dst: buffer to store extracted data
* @dstlen: maximum number of bytes to extract
*
* This function extracts all remaining data, or at most @dstlen
* bytes, from the stream previously associated with @state by
* gunzip_start(). zlib is then shut down, so it is an error to use
* any of the functions in this file on @state until it is
* re-initialized with another call to gunzip_start().
*
* If any errors occur, such as a corrupted compressed stream, an
* error is printed an the platform's exit() function is called.
*/
int gunzip_finish(struct gunzip_state *state, void *dst, int dstlen) int gunzip_finish(struct gunzip_state *state, void *dst, int dstlen)
{ {
int len; int len;
......
...@@ -12,6 +12,22 @@ ...@@ -12,6 +12,22 @@
#include "zlib.h" #include "zlib.h"
/*
* These functions are designed to make life easy for decompressing
* kernel images, initrd images or any other gzip compressed image,
* particularly if its useful to decompress part of the image (e.g. to
* examine headers) before decompressing the remainder.
*
* To use:
* - declare a gunzip_state structure
* - use gunzip_start() to initialize the state, associating it
* with a stream of compressed data
* - use gunzip_partial(), gunzip_exactly() and gunzip_discard()
* in any combination to extract pieces of data from the stream
* - Finally use gunzip_finish() to extract the tail of the
* compressed stream and wind up zlib
*/
/* scratch space for gunzip; 46912 is from zlib_inflate_workspacesize() */ /* scratch space for gunzip; 46912 is from zlib_inflate_workspacesize() */
#define GUNZIP_SCRATCH_SIZE 46912 #define GUNZIP_SCRATCH_SIZE 46912
...@@ -27,4 +43,3 @@ void gunzip_discard(struct gunzip_state *state, int len); ...@@ -27,4 +43,3 @@ void gunzip_discard(struct gunzip_state *state, int len);
int gunzip_finish(struct gunzip_state *state, void *dst, int len); int gunzip_finish(struct gunzip_state *state, void *dst, int len);
#endif /* _PPC_BOOT_GUNZIP_UTIL_H_ */ #endif /* _PPC_BOOT_GUNZIP_UTIL_H_ */
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment