From 7850ad5c39a40ae14ab37e030357e2ae8252af2b Mon Sep 17 00:00:00 2001 From: David Gibson Date: Wed, 14 Mar 2007 16:32:17 +1100 Subject: [PATCH] [POWERPC] Add documentation for the zImage's gunzip convenience functions This patch adds documenting comments to the gunzip convenience functions added in commit ad9d2716cfc1cda5a7e0d7bc0db45e3af8a4adbb. It also removes a stray newline, and an unused global variable. Signed-off-by: David Gibson Signed-off-by: Paul Mackerras --- arch/powerpc/boot/gunzip_util.c | 81 ++++++++++++++++++++++++++++++++- arch/powerpc/boot/gunzip_util.h | 17 ++++++- 2 files changed, 95 insertions(+), 3 deletions(-) diff --git a/arch/powerpc/boot/gunzip_util.c b/arch/powerpc/boot/gunzip_util.c index 3d9ff8f081..f7c95f24fc 100644 --- a/arch/powerpc/boot/gunzip_util.c +++ b/arch/powerpc/boot/gunzip_util.c @@ -14,14 +14,31 @@ #include "ops.h" #include "gunzip_util.h" -struct gunzip_state state; - #define HEAD_CRC 2 #define EXTRA_FIELD 4 #define ORIG_NAME 8 #define COMMENT 0x10 #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) { char *hdr = src; @@ -73,6 +90,22 @@ void gunzip_start(struct gunzip_state *state, void *src, int srclen) 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 len; @@ -99,6 +132,20 @@ int gunzip_partial(struct gunzip_state *state, void *dst, int dstlen) 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) { int len; @@ -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) { static char discard_buf[128]; @@ -123,6 +185,21 @@ void gunzip_discard(struct gunzip_state *state, int 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 len; diff --git a/arch/powerpc/boot/gunzip_util.h b/arch/powerpc/boot/gunzip_util.h index 950f62fe0a..b3dfa6e87b 100644 --- a/arch/powerpc/boot/gunzip_util.h +++ b/arch/powerpc/boot/gunzip_util.h @@ -12,6 +12,22 @@ #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() */ #define GUNZIP_SCRATCH_SIZE 46912 @@ -27,4 +43,3 @@ void gunzip_discard(struct gunzip_state *state, int len); int gunzip_finish(struct gunzip_state *state, void *dst, int len); #endif /* _PPC_BOOT_GUNZIP_UTIL_H_ */ - -- 2.39.5