diff options
Diffstat (limited to 'roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs')
5 files changed, 1250 insertions, 0 deletions
diff --git a/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/brotli-comparison-study-2015-09-22.pdf b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/brotli-comparison-study-2015-09-22.pdf Binary files differnew file mode 100644 index 000000000..040f179e2 --- /dev/null +++ b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/brotli-comparison-study-2015-09-22.pdf diff --git a/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/brotli.1 b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/brotli.1 new file mode 100644 index 000000000..7242a3255 --- /dev/null +++ b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/brotli.1 @@ -0,0 +1,132 @@ +.TH "BROTLI" "1" "February 2018" "brotli 1.0.0" "User commands" +.SH "NAME" +\fBbrotli\fR \- brotli, unbrotli \- compress or decompress files +.SH SYNOPSIS +.P +\fBbrotli\fP [\fIOPTION|FILE\fR]\.\.\. +.P +\fBunbrotli\fP is equivalent to \fBbrotli \-\-decompress\fP +.SH DESCRIPTION +.P +\fBbrotli\fP is a generic\-purpose lossless compression algorithm that compresses +data using a combination of a modern variant of the \fBLZ77\fR algorithm, Huffman +coding and 2\-nd order context modeling, with a compression ratio comparable to +the best currently available general\-purpose compression methods\. It is similar +in speed with deflate but offers more dense compression\. +.P +\fBbrotli\fP command line syntax similar to \fBgzip (1)\fP and \fBzstd (1)\fP\|\. +Unlike \fBgzip (1)\fP, source files are preserved by default\. It is possible to +remove them after processing by using the \fB\-\-rm\fP \fIoption\fR\|\. +.P +Arguments that look like "\fB\-\-name\fP" or "\fB\-\-name=value\fP" are \fIoptions\fR\|\. Every +\fIoption\fR has a short form "\fB\-x\fP" or "\fB\-x value\fP"\. Multiple short form \fIoptions\fR +could be coalesced: +.RS 0 +.IP \(bu 2 +"\fB\-\-decompress \-\-stdout \-\-suffix=\.b\fP" works the same as +.IP \(bu 2 +"\fB\-d \-s \-S \.b\fP" and +.IP \(bu 2 +"\fB\-dsS \.b\fP" + +.RE +.P +\fBbrotli\fP has 3 operation modes: +.RS 0 +.IP \(bu 2 +default mode is compression; +.IP \(bu 2 +\fB\-\-decompress\fP option activates decompression mode; +.IP \(bu 2 +\fB\-\-test\fP option switches to integrity test mode; this option is equivalent to +"\fB\-\-decompress \-\-stdout\fP" except that the decompressed data is discarded +instead of being written to standard output\. + +.RE +.P +Every non\-option argument is a \fIfile\fR entry\. If no \fIfiles\fR are given or \fIfile\fR +is "\fB\-\fP", \fBbrotli\fP reads from standard input\. All arguments after "\fB\-\-\fP" are +\fIfile\fR entries\. +.P +Unless \fB\-\-stdout\fP or \fB\-\-output\fP is specified, \fIfiles\fR are written to a new file +whose name is derived from the source \fIfile\fR name: +.RS 0 +.IP \(bu 2 +when compressing, a suffix is appended to the source filename to +get the target filename +.IP \(bu 2 +when decompressing, a suffix is removed from the source filename to +get the target filename + +.RE +.P +Default suffix is \fB\|\.br\fP, but it could be specified with \fB\-\-suffix\fP option\. +.P +Conflicting or duplicate \fIoptions\fR are not allowed\. +.SH OPTIONS +.RS 0 +.IP \(bu 2 +\fB\-#\fP: + compression level (0\-9); bigger values cause denser, but slower compression +.IP \(bu 2 +\fB\-c\fP, \fB\-\-stdout\fP: + write on standard output +.IP \(bu 2 +\fB\-d\fP, \fB\-\-decompress\fP: + decompress mode +.IP \(bu 2 +\fB\-f\fP, \fB\-\-force\fP: + force output file overwrite +.IP \(bu 2 +\fB\-h\fP, \fB\-\-help\fP: + display this help and exit +.IP \(bu 2 +\fB\-j\fP, \fB\-\-rm\fP: + remove source file(s); \fBgzip (1)\fP\-like behaviour +.IP \(bu 2 +\fB\-k\fP, \fB\-\-keep\fP: + keep source file(s); \fBzstd (1)\fP\-like behaviour +.IP \(bu 2 +\fB\-n\fP, \fB\-\-no\-copy\-stat\fP: + do not copy source file(s) attributes +.IP \(bu 2 +\fB\-o FILE\fP, \fB\-\-output=FILE\fP + output file; valid only if there is a single input entry +.IP \(bu 2 +\fB\-q NUM\fP, \fB\-\-quality=NUM\fP: + compression level (0\-11); bigger values cause denser, but slower compression +.IP \(bu 2 +\fB\-t\fP, \fB\-\-test\fP: + test file integrity mode +.IP \(bu 2 +\fB\-v\fP, \fB\-\-verbose\fP: + increase output verbosity +.IP \(bu 2 +\fB\-w NUM\fP, \fB\-\-lgwin=NUM\fP: + set LZ77 window size (0, 10\-24) (default: 22); window size is + \fB(2**NUM \- 16)\fP; 0 lets compressor decide over the optimal value; bigger + windows size improve density; decoder might require up to window size + memory to operate +.IP \(bu 2 +\fB\-S SUF\fP, \fB\-\-suffix=SUF\fP: + output file suffix (default: \fB\|\.br\fP) +.IP \(bu 2 +\fB\-V\fP, \fB\-\-version\fP: + display version and exit +.IP \(bu 2 +\fB\-Z\fP, \fB\-\-best\fP: + use best compression level (default); same as "\fB\-q 11\fP" + +.RE +.SH SEE ALSO +.P +\fBbrotli\fP file format is defined in +RFC 7932 \fIhttps://www\.ietf\.org/rfc/rfc7932\.txt\fR\|\. +.P +\fBbrotli\fP is open\-sourced under the +MIT License \fIhttps://opensource\.org/licenses/MIT\fR\|\. +.P +Mailing list: https://groups\.google\.com/forum/#!forum/brotli +.SH BUGS +.P +Report bugs at: https://github\.com/google/brotli/issues diff --git a/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/decode.h.3 b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/decode.h.3 new file mode 100644 index 000000000..7b8581cc2 --- /dev/null +++ b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/decode.h.3 @@ -0,0 +1,415 @@ +.TH "decode.h" 3 "Thu Feb 22 2018" "Brotli" \" -*- nroff -*- +.ad l +.nh +.SH NAME +decode.h \- API for Brotli decompression\&. + +.SH SYNOPSIS +.br +.PP +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBBROTLI_DECODER_ERROR_CODES_LIST\fP(BROTLI_ERROR_CODE, SEPARATOR) " +.br +.RI "\fITemplate that evaluates items of \fBBrotliDecoderErrorCode\fP\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_LAST_ERROR_CODE\fP BROTLI_DECODER_ERROR_UNREACHABLE" +.br +.RI "\fIThe value of the last error code, negative integer\&. \fP" +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef enum \fBBrotliDecoderParameter\fP \fBBrotliDecoderParameter\fP" +.br +.RI "\fIOptions to be used with \fBBrotliDecoderSetParameter\fP\&. \fP" +.ti -1c +.RI "typedef struct BrotliDecoderStateStruct \fBBrotliDecoderState\fP" +.br +.RI "\fIOpaque structure that holds decoder state\&. \fP" +.in -1c +.SS "Enumerations" +.SS "Functions" + +.in +1c +.ti -1c +.RI "\fBBrotliDecoderState\fP * \fBBrotliDecoderCreateInstance\fP (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)" +.br +.RI "\fICreates an instance of \fBBrotliDecoderState\fP and initializes it\&. \fP" +.ti -1c +.RI "\fBBrotliDecoderResult\fP \fBBrotliDecoderDecompress\fP (size_t encoded_size, const uint8_t encoded_buffer[encoded_size], size_t *decoded_size, uint8_t decoded_buffer[*decoded_size])" +.br +.RI "\fIPerforms one-shot memory-to-memory decompression\&. \fP" +.ti -1c +.RI "\fBBrotliDecoderResult\fP \fBBrotliDecoderDecompressStream\fP (\fBBrotliDecoderState\fP *state, size_t *available_in, const uint8_t **next_in, size_t *available_out, uint8_t **next_out, size_t *total_out)" +.br +.RI "\fIDecompresses the input stream to the output stream\&. \fP" +.ti -1c +.RI "void \fBBrotliDecoderDestroyInstance\fP (\fBBrotliDecoderState\fP *state)" +.br +.RI "\fIDeinitializes and frees \fBBrotliDecoderState\fP instance\&. \fP" +.ti -1c +.RI "const char * \fBBrotliDecoderErrorString\fP (\fBBrotliDecoderErrorCode\fP c)" +.br +.RI "\fIConverts error code to a c-string\&. \fP" +.ti -1c +.RI "\fBBrotliDecoderErrorCode\fP \fBBrotliDecoderGetErrorCode\fP (const \fBBrotliDecoderState\fP *state)" +.br +.RI "\fIAcquires a detailed error code\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderHasMoreOutput\fP (const \fBBrotliDecoderState\fP *state)" +.br +.RI "\fIChecks if decoder has more output\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderIsFinished\fP (const \fBBrotliDecoderState\fP *state)" +.br +.RI "\fIChecks if decoder instance reached the final state\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderIsUsed\fP (const \fBBrotliDecoderState\fP *state)" +.br +.RI "\fIChecks if instance has already consumed input\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderSetParameter\fP (\fBBrotliDecoderState\fP *state, \fBBrotliDecoderParameter\fP param, uint32_t value)" +.br +.RI "\fISets the specified parameter to the given decoder instance\&. \fP" +.ti -1c +.RI "const uint8_t * \fBBrotliDecoderTakeOutput\fP (\fBBrotliDecoderState\fP *state, size_t *size)" +.br +.RI "\fIAcquires pointer to internal output buffer\&. \fP" +.ti -1c +.RI "uint32_t \fBBrotliDecoderVersion\fP (void)" +.br +.RI "\fIGets a decoder library version\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +API for Brotli decompression\&. + + +.SH "Macro Definition Documentation" +.PP +.SS "#define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR)" + +.PP +Template that evaluates items of \fBBrotliDecoderErrorCode\fP\&. Example: +.PP +.nf +// Log Brotli error code\&. +switch (brotliDecoderErrorCode) { +#define CASE_(PREFIX, NAME, CODE) \ + case BROTLI_DECODER ## PREFIX ## NAME: \ + LOG(INFO) << "error code:" << #NAME; \ + break; +#define NEWLINE_ +BROTLI_DECODER_ERROR_CODES_LIST(CASE_, NEWLINE_) +#undef CASE_ +#undef NEWLINE_ + default: LOG(FATAL) << "unknown brotli error code"; +} + +.fi +.PP + +.SS "#define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE" + +.PP +The value of the last error code, negative integer\&. All other error code values are in the range from \fBBROTLI_LAST_ERROR_CODE\fP to \fC-1\fP\&. There are also 4 other possible non-error codes \fC0\fP \&.\&. \fC3\fP in \fBBrotliDecoderErrorCode\fP enumeration\&. +.SH "Typedef Documentation" +.PP +.SS "typedef enum \fBBrotliDecoderParameter\fP \fBBrotliDecoderParameter\fP" + +.PP +Options to be used with \fBBrotliDecoderSetParameter\fP\&. +.SS "typedef struct BrotliDecoderStateStruct \fBBrotliDecoderState\fP" + +.PP +Opaque structure that holds decoder state\&. Allocated and initialized with \fBBrotliDecoderCreateInstance\fP\&. Cleaned up and deallocated with \fBBrotliDecoderDestroyInstance\fP\&. +.SH "Enumeration Type Documentation" +.PP +.SS "enum \fBBrotliDecoderErrorCode\fP" + +.PP +Error code for detailed logging / production debugging\&. See \fBBrotliDecoderGetErrorCode\fP and \fBBROTLI_LAST_ERROR_CODE\fP\&. +.SS "enum \fBBrotliDecoderParameter\fP" + +.PP +Options to be used with \fBBrotliDecoderSetParameter\fP\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION \fP\fP +Disable 'canny' ring buffer allocation strategy\&. Ring buffer is allocated according to window size, despite the real size of the content\&. +.TP +\fB\fIBROTLI_DECODER_PARAM_LARGE_WINDOW \fP\fP +Flag that determines if 'Large Window Brotli' is used\&. +.SS "enum \fBBrotliDecoderResult\fP" + +.PP +Result type for \fBBrotliDecoderDecompress\fP and \fBBrotliDecoderDecompressStream\fP functions\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBROTLI_DECODER_RESULT_ERROR \fP\fP +Decoding error, e\&.g\&. corrupted input or memory allocation problem\&. +.TP +\fB\fIBROTLI_DECODER_RESULT_SUCCESS \fP\fP +Decoding successfully completed\&. +.TP +\fB\fIBROTLI_DECODER_RESULT_NEEDS_MORE_INPUT \fP\fP +Partially done; should be called again with more input\&. +.TP +\fB\fIBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT \fP\fP +Partially done; should be called again with more output\&. +.SH "Function Documentation" +.PP +.SS "\fBBrotliDecoderState\fP* BrotliDecoderCreateInstance (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)" + +.PP +Creates an instance of \fBBrotliDecoderState\fP and initializes it\&. The instance can be used once for decoding and should then be destroyed with \fBBrotliDecoderDestroyInstance\fP, it cannot be reused for a new decoding session\&. +.PP +\fCalloc_func\fP and \fCfree_func\fP \fBMUST\fP be both zero or both non-zero\&. In the case they are both zero, default memory allocators are used\&. \fCopaque\fP is passed to \fCalloc_func\fP and \fCfree_func\fP when they are called\&. \fCfree_func\fP has to return without doing anything when asked to free a NULL pointer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIalloc_func\fP custom memory allocation function +.br +\fIfree_func\fP custom memory free function +.br +\fIopaque\fP custom memory manager handle +.RE +.PP +\fBReturns:\fP +.RS 4 +\fC0\fP if instance can not be allocated or initialized +.PP +pointer to initialized \fBBrotliDecoderState\fP otherwise +.RE +.PP + +.SS "\fBBrotliDecoderResult\fP BrotliDecoderDecompress (size_t encoded_size, const uint8_t encoded_buffer[encoded_size], size_t * decoded_size, uint8_t decoded_buffer[*decoded_size])" + +.PP +Performs one-shot memory-to-memory decompression\&. Decompresses the data in \fCencoded_buffer\fP into \fCdecoded_buffer\fP, and sets \fC*decoded_size\fP to the decompressed length\&. +.PP +\fBParameters:\fP +.RS 4 +\fIencoded_size\fP size of \fCencoded_buffer\fP +.br +\fIencoded_buffer\fP compressed data buffer with at least \fCencoded_size\fP addressable bytes +.br +\fIdecoded_size\fP \fBin:\fP size of \fCdecoded_buffer\fP; +.br + \fBout:\fP length of decompressed data written to \fCdecoded_buffer\fP +.br +\fIdecoded_buffer\fP decompressed data destination buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_DECODER_RESULT_ERROR\fP if input is corrupted, memory allocation failed, or \fCdecoded_buffer\fP is not large enough; +.PP +\fBBROTLI_DECODER_RESULT_SUCCESS\fP otherwise +.RE +.PP + +.SS "\fBBrotliDecoderResult\fP BrotliDecoderDecompressStream (\fBBrotliDecoderState\fP * state, size_t * available_in, const uint8_t ** next_in, size_t * available_out, uint8_t ** next_out, size_t * total_out)" + +.PP +Decompresses the input stream to the output stream\&. The values \fC*available_in\fP and \fC*available_out\fP must specify the number of bytes addressable at \fC*next_in\fP and \fC*next_out\fP respectively\&. When \fC*available_out\fP is \fC0\fP, \fCnext_out\fP is allowed to be \fCNULL\fP\&. +.PP +After each call, \fC*available_in\fP will be decremented by the amount of input bytes consumed, and the \fC*next_in\fP pointer will be incremented by that amount\&. Similarly, \fC*available_out\fP will be decremented by the amount of output bytes written, and the \fC*next_out\fP pointer will be incremented by that amount\&. +.PP +\fCtotal_out\fP, if it is not a null-pointer, will be set to the number of bytes decompressed since the last \fCstate\fP initialization\&. +.PP +\fBNote:\fP +.RS 4 +Input is never overconsumed, so \fCnext_in\fP and \fCavailable_in\fP could be passed to the next consumer after decoding is complete\&. +.RE +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance +.br +\fIavailable_in\fP \fBin:\fP amount of available input; +.br + \fBout:\fP amount of unused input +.br +\fInext_in\fP pointer to the next compressed byte +.br +\fIavailable_out\fP \fBin:\fP length of output buffer; +.br + \fBout:\fP remaining size of output buffer +.br +\fInext_out\fP output buffer cursor; can be \fCNULL\fP if \fCavailable_out\fP is \fC0\fP +.br +\fItotal_out\fP number of bytes decompressed so far; can be \fCNULL\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_DECODER_RESULT_ERROR\fP if input is corrupted, memory allocation failed, arguments were invalid, etc\&.; use \fBBrotliDecoderGetErrorCode\fP to get detailed error code +.PP +\fBBROTLI_DECODER_RESULT_NEEDS_MORE_INPUT\fP decoding is blocked until more input data is provided +.PP +\fBBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT\fP decoding is blocked until more output space is provided +.PP +\fBBROTLI_DECODER_RESULT_SUCCESS\fP decoding is finished, no more input might be consumed and no more output will be produced +.RE +.PP + +.SS "void BrotliDecoderDestroyInstance (\fBBrotliDecoderState\fP * state)" + +.PP +Deinitializes and frees \fBBrotliDecoderState\fP instance\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance to be cleaned up and deallocated +.RE +.PP + +.SS "\fBBrotliDecoderErrorCode\fP BrotliDecoderGetErrorCode (const \fBBrotliDecoderState\fP * state)" + +.PP +Acquires a detailed error code\&. Should be used only after \fBBrotliDecoderDecompressStream\fP returns \fBBROTLI_DECODER_RESULT_ERROR\fP\&. +.PP +See also \fBBrotliDecoderErrorString\fP +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance +.RE +.PP +\fBReturns:\fP +.RS 4 +last saved error code +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliDecoderHasMoreOutput (const \fBBrotliDecoderState\fP * state)" + +.PP +Checks if decoder has more output\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_TRUE\fP, if decoder has some unconsumed output +.PP +\fBBROTLI_FALSE\fP otherwise +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliDecoderIsFinished (const \fBBrotliDecoderState\fP * state)" + +.PP +Checks if decoder instance reached the final state\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_TRUE\fP if decoder is in a state where it reached the end of the input and produced all of the output +.PP +\fBBROTLI_FALSE\fP otherwise +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliDecoderIsUsed (const \fBBrotliDecoderState\fP * state)" + +.PP +Checks if instance has already consumed input\&. Instance that returns \fBBROTLI_FALSE\fP is considered 'fresh' and could be reused\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_TRUE\fP if decoder has already used some input bytes +.PP +\fBBROTLI_FALSE\fP otherwise +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliDecoderSetParameter (\fBBrotliDecoderState\fP * state, \fBBrotliDecoderParameter\fP param, uint32_t value)" + +.PP +Sets the specified parameter to the given decoder instance\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance +.br +\fIparam\fP parameter to set +.br +\fIvalue\fP new parameter value +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_FALSE\fP if parameter is unrecognized, or value is invalid +.PP +\fBBROTLI_TRUE\fP if value is accepted +.RE +.PP + +.SS "const uint8_t* BrotliDecoderTakeOutput (\fBBrotliDecoderState\fP * state, size_t * size)" + +.PP +Acquires pointer to internal output buffer\&. This method is used to make language bindings easier and more efficient: +.IP "1." 4 +push data to \fBBrotliDecoderDecompressStream\fP, until \fBBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT\fP is reported +.IP "2." 4 +use \fBBrotliDecoderTakeOutput\fP to peek bytes and copy to language-specific entity +.PP +.PP +Also this could be useful if there is an output stream that is able to consume all the provided data (e\&.g\&. when data is saved to file system)\&. +.PP +\fBAttention:\fP +.RS 4 +After every call to \fBBrotliDecoderTakeOutput\fP \fC*size\fP bytes of output are considered consumed for all consecutive calls to the instance methods; returned pointer becomes invalidated as well\&. +.RE +.PP +\fBNote:\fP +.RS 4 +Decoder output is not guaranteed to be contiguous\&. This means that after the size-unrestricted call to \fBBrotliDecoderTakeOutput\fP, immediate next call to \fBBrotliDecoderTakeOutput\fP may return more data\&. +.RE +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance +.br +\fIsize\fP \fBin:\fP number of bytes caller is ready to take, \fC0\fP if any amount could be handled; +.br + \fBout:\fP amount of data pointed by returned pointer and considered consumed; +.br + out value is never greater than in value, unless it is \fC0\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +pointer to output data +.RE +.PP + +.SS "uint32_t BrotliDecoderVersion (void)" + +.PP +Gets a decoder library version\&. Look at BROTLI_VERSION for more information\&. +.SH "Author" +.PP +Generated automatically by Doxygen for Brotli from the source code\&. diff --git a/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/encode.h.3 b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/encode.h.3 new file mode 100644 index 000000000..0cab81668 --- /dev/null +++ b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/encode.h.3 @@ -0,0 +1,586 @@ +.TH "encode.h" 3 "Thu Feb 22 2018" "Brotli" \" -*- nroff -*- +.ad l +.nh +.SH NAME +encode.h \- API for Brotli compression\&. + +.SH SYNOPSIS +.br +.PP +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBBROTLI_DEFAULT_MODE\fP \fBBROTLI_MODE_GENERIC\fP" +.br +.RI "\fIDefault value for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_DEFAULT_QUALITY\fP 11" +.br +.RI "\fIDefault value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_DEFAULT_WINDOW\fP 22" +.br +.RI "\fIDefault value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_LARGE_MAX_WINDOW_BITS\fP 30" +.br +.RI "\fIMaximal value for \fBBROTLI_PARAM_LGWIN\fP parameter in 'Large Window Brotli' (32-bit)\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP 24" +.br +.RI "\fIMaximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_MAX_QUALITY\fP 11" +.br +.RI "\fIMaximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_MAX_WINDOW_BITS\fP 24" +.br +.RI "\fIMaximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP 16" +.br +.RI "\fIMinimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_MIN_QUALITY\fP 0" +.br +.RI "\fIMinimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_MIN_WINDOW_BITS\fP 10" +.br +.RI "\fIMinimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP" +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP" +.br +.RI "\fIOptions for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP" +.ti -1c +.RI "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP" +.br +.RI "\fIOperations that can be performed by streaming encoder\&. \fP" +.ti -1c +.RI "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP" +.br +.RI "\fIOptions to be used with \fBBrotliEncoderSetParameter\fP\&. \fP" +.ti -1c +.RI "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP" +.br +.RI "\fIOpaque structure that holds encoder state\&. \fP" +.in -1c +.SS "Enumerations" +.SS "Functions" + +.in +1c +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderCompress\fP (int quality, int lgwin, \fBBrotliEncoderMode\fP mode, size_t input_size, const uint8_t input_buffer[input_size], size_t *encoded_size, uint8_t encoded_buffer[*encoded_size])" +.br +.RI "\fIPerforms one-shot memory-to-memory compression\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderCompressStream\fP (\fBBrotliEncoderState\fP *state, \fBBrotliEncoderOperation\fP op, size_t *available_in, const uint8_t **next_in, size_t *available_out, uint8_t **next_out, size_t *total_out)" +.br +.RI "\fICompresses input stream to output stream\&. \fP" +.ti -1c +.RI "\fBBrotliEncoderState\fP * \fBBrotliEncoderCreateInstance\fP (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)" +.br +.RI "\fICreates an instance of \fBBrotliEncoderState\fP and initializes it\&. \fP" +.ti -1c +.RI "void \fBBrotliEncoderDestroyInstance\fP (\fBBrotliEncoderState\fP *state)" +.br +.RI "\fIDeinitializes and frees \fBBrotliEncoderState\fP instance\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderHasMoreOutput\fP (\fBBrotliEncoderState\fP *state)" +.br +.RI "\fIChecks if encoder has more output\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderIsFinished\fP (\fBBrotliEncoderState\fP *state)" +.br +.RI "\fIChecks if encoder instance reached the final state\&. \fP" +.ti -1c +.RI "size_t \fBBrotliEncoderMaxCompressedSize\fP (size_t input_size)" +.br +.RI "\fICalculates the output size bound for the given \fCinput_size\fP\&. \fP" +.ti -1c +.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderSetParameter\fP (\fBBrotliEncoderState\fP *state, \fBBrotliEncoderParameter\fP param, uint32_t value)" +.br +.RI "\fISets the specified parameter to the given encoder instance\&. \fP" +.ti -1c +.RI "const uint8_t * \fBBrotliEncoderTakeOutput\fP (\fBBrotliEncoderState\fP *state, size_t *size)" +.br +.RI "\fIAcquires pointer to internal output buffer\&. \fP" +.ti -1c +.RI "uint32_t \fBBrotliEncoderVersion\fP (void)" +.br +.RI "\fIGets an encoder library version\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +API for Brotli compression\&. + + +.SH "Macro Definition Documentation" +.PP +.SS "#define BROTLI_DEFAULT_MODE \fBBROTLI_MODE_GENERIC\fP" + +.PP +Default value for \fBBROTLI_PARAM_MODE\fP parameter\&. +.SS "#define BROTLI_DEFAULT_QUALITY 11" + +.PP +Default value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. +.SS "#define BROTLI_DEFAULT_WINDOW 22" + +.PP +Default value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. +.SS "#define BROTLI_MAX_INPUT_BLOCK_BITS 24" + +.PP +Maximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. +.SS "#define BROTLI_MAX_QUALITY 11" + +.PP +Maximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. +.SS "#define BROTLI_MAX_WINDOW_BITS 24" + +.PP +Maximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. +.PP +\fBNote:\fP +.RS 4 +equal to \fCBROTLI_MAX_DISTANCE_BITS\fP constant\&. +.RE +.PP + +.SS "#define BROTLI_MIN_INPUT_BLOCK_BITS 16" + +.PP +Minimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. +.SS "#define BROTLI_MIN_QUALITY 0" + +.PP +Minimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. +.SS "#define BROTLI_MIN_WINDOW_BITS 10" + +.PP +Minimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. +.SH "Typedef Documentation" +.PP +.SS "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP" + +.PP +Options for \fBBROTLI_PARAM_MODE\fP parameter\&. +.SS "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP" + +.PP +Operations that can be performed by streaming encoder\&. +.SS "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP" + +.PP +Options to be used with \fBBrotliEncoderSetParameter\fP\&. +.SS "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP" + +.PP +Opaque structure that holds encoder state\&. Allocated and initialized with \fBBrotliEncoderCreateInstance\fP\&. Cleaned up and deallocated with \fBBrotliEncoderDestroyInstance\fP\&. +.SH "Enumeration Type Documentation" +.PP +.SS "enum \fBBrotliEncoderMode\fP" + +.PP +Options for \fBBROTLI_PARAM_MODE\fP parameter\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBROTLI_MODE_GENERIC \fP\fP +Default compression mode\&. In this mode compressor does not know anything in advance about the properties of the input\&. +.TP +\fB\fIBROTLI_MODE_TEXT \fP\fP +Compression mode for UTF-8 formatted text input\&. +.TP +\fB\fIBROTLI_MODE_FONT \fP\fP +Compression mode used in WOFF 2\&.0\&. +.SS "enum \fBBrotliEncoderOperation\fP" + +.PP +Operations that can be performed by streaming encoder\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBROTLI_OPERATION_PROCESS \fP\fP +Process input\&. Encoder may postpone producing output, until it has processed enough input\&. +.TP +\fB\fIBROTLI_OPERATION_FLUSH \fP\fP +Produce output for all processed input\&. Actual flush is performed when input stream is depleted and there is enough space in output stream\&. This means that client should repeat \fBBROTLI_OPERATION_FLUSH\fP operation until \fCavailable_in\fP becomes \fC0\fP, and \fBBrotliEncoderHasMoreOutput\fP returns \fBBROTLI_FALSE\fP\&. If output is acquired via \fBBrotliEncoderTakeOutput\fP, then operation should be repeated after output buffer is drained\&. +.PP +\fBWarning:\fP +.RS 4 +Until flush is complete, client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&. +.RE +.PP +When flush is complete, output data will be sufficient for decoder to reproduce all the given input\&. +.TP +\fB\fIBROTLI_OPERATION_FINISH \fP\fP +Finalize the stream\&. Actual finalization is performed when input stream is depleted and there is enough space in output stream\&. This means that client should repeat \fBBROTLI_OPERATION_FINISH\fP operation until \fCavailable_in\fP becomes \fC0\fP, and \fBBrotliEncoderHasMoreOutput\fP returns \fBBROTLI_FALSE\fP\&. If output is acquired via \fBBrotliEncoderTakeOutput\fP, then operation should be repeated after output buffer is drained\&. +.PP +\fBWarning:\fP +.RS 4 +Until finalization is complete, client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&. +.RE +.PP +Helper function \fBBrotliEncoderIsFinished\fP checks if stream is finalized and output fully dumped\&. +.PP +Adding more input data to finalized stream is impossible\&. +.TP +\fB\fIBROTLI_OPERATION_EMIT_METADATA \fP\fP +Emit metadata block to stream\&. Metadata is opaque to Brotli: neither encoder, nor decoder processes this data or relies on it\&. It may be used to pass some extra information from encoder client to decoder client without interfering with main data stream\&. +.PP +\fBNote:\fP +.RS 4 +Encoder may emit empty metadata blocks internally, to pad encoded stream to byte boundary\&. +.RE +.PP +\fBWarning:\fP +.RS 4 +Until emitting metadata is complete client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&. +.PP +The whole content of input buffer is considered to be the content of metadata block\&. Do \fBNOT\fP \fIappend\fP metadata to input stream, before it is depleted with other operations\&. +.RE +.PP +Stream is soft-flushed before metadata block is emitted\&. Metadata block \fBMUST\fP be no longer than than 16MiB\&. +.SS "enum \fBBrotliEncoderParameter\fP" + +.PP +Options to be used with \fBBrotliEncoderSetParameter\fP\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBROTLI_PARAM_MODE \fP\fP +Tune encoder for specific input\&. \fBBrotliEncoderMode\fP enumerates all available values\&. +.TP +\fB\fIBROTLI_PARAM_QUALITY \fP\fP +The main compression speed-density lever\&. The higher the quality, the slower the compression\&. Range is from \fBBROTLI_MIN_QUALITY\fP to \fBBROTLI_MAX_QUALITY\fP\&. +.TP +\fB\fIBROTLI_PARAM_LGWIN \fP\fP +Recommended sliding LZ77 window size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than window size\&. +.PP +Window size is \fC(1 << value) - 16\fP\&. +.PP +Range is from \fBBROTLI_MIN_WINDOW_BITS\fP to \fBBROTLI_MAX_WINDOW_BITS\fP\&. +.TP +\fB\fIBROTLI_PARAM_LGBLOCK \fP\fP +Recommended input block size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than input block size\&. +.PP +Range is from \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP to \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP\&. +.PP +\fBNote:\fP +.RS 4 +Bigger input block size allows better compression, but consumes more memory\&. +.br + The rough formula of memory used for temporary input storage is \fC3 << lgBlock\fP\&. +.RE +.PP + +.TP +\fB\fIBROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING \fP\fP +Flag that affects usage of 'literal context modeling' format feature\&. This flag is a 'decoding-speed vs compression ratio' trade-off\&. +.TP +\fB\fIBROTLI_PARAM_SIZE_HINT \fP\fP +Estimated total input size for all \fBBrotliEncoderCompressStream\fP calls\&. The default value is 0, which means that the total input size is unknown\&. +.TP +\fB\fIBROTLI_PARAM_LARGE_WINDOW \fP\fP +Flag that determines if 'Large Window Brotli' is used\&. +.TP +\fB\fIBROTLI_PARAM_NPOSTFIX \fP\fP +Recommended number of postfix bits (NPOSTFIX)\&. Encoder may change this value\&. +.PP +Range is from 0 to \fBBROTLI_MAX_NPOSTFIX\fP\&. +.TP +\fB\fIBROTLI_PARAM_NDIRECT \fP\fP +Recommended number of direct distance codes (NDIRECT)\&. Encoder may change this value\&. +.PP +Range is from 0 to (15 << NPOSTFIX) in steps of (1 << NPOSTFIX)\&. +.TP +\fB\fIBROTLI_PARAM_STREAM_OFFSET \fP\fP +Number of bytes of input stream already processed by a different instance\&. +.PP +\fBNote:\fP +.RS 4 +It is important to configure all the encoder instances with same parameters (except this one) in order to allow all the encoded parts obey the same restrictions implied by header\&. +.RE +.PP +If offset is not 0, then stream header is omitted\&. In any case output start is byte aligned, so for proper streams stitching 'predecessor' stream must be flushed\&. +.PP +Range is not artificially limited, but all the values greater or equal to maximal window size have the same effect\&. Values greater than 2**30 are not allowed\&. +.SH "Function Documentation" +.PP +.SS "\fBBROTLI_BOOL\fP BrotliEncoderCompress (int quality, int lgwin, \fBBrotliEncoderMode\fP mode, size_t input_size, const uint8_t input_buffer[input_size], size_t * encoded_size, uint8_t encoded_buffer[*encoded_size])" + +.PP +Performs one-shot memory-to-memory compression\&. Compresses the data in \fCinput_buffer\fP into \fCencoded_buffer\fP, and sets \fC*encoded_size\fP to the compressed length\&. +.PP +\fBNote:\fP +.RS 4 +If \fBBrotliEncoderMaxCompressedSize\fP(\fCinput_size\fP) returns non-zero value, then output is guaranteed to be no longer than that\&. +.PP +If \fClgwin\fP is greater than \fBBROTLI_MAX_WINDOW_BITS\fP then resulting stream might be incompatible with RFC 7932; to decode such streams, decoder should be configured with \fBBROTLI_DECODER_PARAM_LARGE_WINDOW\fP = \fC1\fP +.RE +.PP +\fBParameters:\fP +.RS 4 +\fIquality\fP quality parameter value, e\&.g\&. \fBBROTLI_DEFAULT_QUALITY\fP +.br +\fIlgwin\fP lgwin parameter value, e\&.g\&. \fBBROTLI_DEFAULT_WINDOW\fP +.br +\fImode\fP mode parameter value, e\&.g\&. \fBBROTLI_DEFAULT_MODE\fP +.br +\fIinput_size\fP size of \fCinput_buffer\fP +.br +\fIinput_buffer\fP input data buffer with at least \fCinput_size\fP addressable bytes +.br +\fIencoded_size\fP \fBin:\fP size of \fCencoded_buffer\fP; +.br + \fBout:\fP length of compressed data written to \fCencoded_buffer\fP, or \fC0\fP if compression fails +.br +\fIencoded_buffer\fP compressed data destination buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_FALSE\fP in case of compression error +.PP +\fBBROTLI_FALSE\fP if output buffer is too small +.PP +\fBBROTLI_TRUE\fP otherwise +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliEncoderCompressStream (\fBBrotliEncoderState\fP * state, \fBBrotliEncoderOperation\fP op, size_t * available_in, const uint8_t ** next_in, size_t * available_out, uint8_t ** next_out, size_t * total_out)" + +.PP +Compresses input stream to output stream\&. The values \fC*available_in\fP and \fC*available_out\fP must specify the number of bytes addressable at \fC*next_in\fP and \fC*next_out\fP respectively\&. When \fC*available_out\fP is \fC0\fP, \fCnext_out\fP is allowed to be \fCNULL\fP\&. +.PP +After each call, \fC*available_in\fP will be decremented by the amount of input bytes consumed, and the \fC*next_in\fP pointer will be incremented by that amount\&. Similarly, \fC*available_out\fP will be decremented by the amount of output bytes written, and the \fC*next_out\fP pointer will be incremented by that amount\&. +.PP +\fCtotal_out\fP, if it is not a null-pointer, will be set to the number of bytes compressed since the last \fCstate\fP initialization\&. +.PP +Internally workflow consists of 3 tasks: +.IP "1." 4 +(optionally) copy input data to internal buffer +.IP "2." 4 +actually compress data and (optionally) store it to internal buffer +.IP "3." 4 +(optionally) copy compressed bytes from internal buffer to output stream +.PP +.PP +Whenever all 3 tasks can't move forward anymore, or error occurs, this method returns the control flow to caller\&. +.PP +\fCop\fP is used to perform flush, finish the stream, or inject metadata block\&. See \fBBrotliEncoderOperation\fP for more information\&. +.PP +Flushing the stream means forcing encoding of all input passed to encoder and completing the current output block, so it could be fully decoded by stream decoder\&. To perform flush set \fCop\fP to \fBBROTLI_OPERATION_FLUSH\fP\&. Under some circumstances (e\&.g\&. lack of output stream capacity) this operation would require several calls to \fBBrotliEncoderCompressStream\fP\&. The method must be called again until both input stream is depleted and encoder has no more output (see \fBBrotliEncoderHasMoreOutput\fP) after the method is called\&. +.PP +Finishing the stream means encoding of all input passed to encoder and adding specific 'final' marks, so stream decoder could determine that stream is complete\&. To perform finish set \fCop\fP to \fBBROTLI_OPERATION_FINISH\fP\&. Under some circumstances (e\&.g\&. lack of output stream capacity) this operation would require several calls to \fBBrotliEncoderCompressStream\fP\&. The method must be called again until both input stream is depleted and encoder has no more output (see \fBBrotliEncoderHasMoreOutput\fP) after the method is called\&. +.PP +\fBWarning:\fP +.RS 4 +When flushing and finishing, \fCop\fP should not change until operation is complete; input stream should not be swapped, reduced or extended as well\&. +.RE +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP encoder instance +.br +\fIop\fP requested operation +.br +\fIavailable_in\fP \fBin:\fP amount of available input; +.br + \fBout:\fP amount of unused input +.br +\fInext_in\fP pointer to the next input byte +.br +\fIavailable_out\fP \fBin:\fP length of output buffer; +.br + \fBout:\fP remaining size of output buffer +.br +\fInext_out\fP compressed output buffer cursor; can be \fCNULL\fP if \fCavailable_out\fP is \fC0\fP +.br +\fItotal_out\fP number of bytes produced so far; can be \fCNULL\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_FALSE\fP if there was an error +.PP +\fBBROTLI_TRUE\fP otherwise +.RE +.PP + +.SS "\fBBrotliEncoderState\fP* BrotliEncoderCreateInstance (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)" + +.PP +Creates an instance of \fBBrotliEncoderState\fP and initializes it\&. \fCalloc_func\fP and \fCfree_func\fP \fBMUST\fP be both zero or both non-zero\&. In the case they are both zero, default memory allocators are used\&. \fCopaque\fP is passed to \fCalloc_func\fP and \fCfree_func\fP when they are called\&. \fCfree_func\fP has to return without doing anything when asked to free a NULL pointer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIalloc_func\fP custom memory allocation function +.br +\fIfree_func\fP custom memory free function +.br +\fIopaque\fP custom memory manager handle +.RE +.PP +\fBReturns:\fP +.RS 4 +\fC0\fP if instance can not be allocated or initialized +.PP +pointer to initialized \fBBrotliEncoderState\fP otherwise +.RE +.PP + +.SS "void BrotliEncoderDestroyInstance (\fBBrotliEncoderState\fP * state)" + +.PP +Deinitializes and frees \fBBrotliEncoderState\fP instance\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP decoder instance to be cleaned up and deallocated +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliEncoderHasMoreOutput (\fBBrotliEncoderState\fP * state)" + +.PP +Checks if encoder has more output\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP encoder instance +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_TRUE\fP, if encoder has some unconsumed output +.PP +\fBBROTLI_FALSE\fP otherwise +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliEncoderIsFinished (\fBBrotliEncoderState\fP * state)" + +.PP +Checks if encoder instance reached the final state\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP encoder instance +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_TRUE\fP if encoder is in a state where it reached the end of the input and produced all of the output +.PP +\fBBROTLI_FALSE\fP otherwise +.RE +.PP + +.SS "size_t BrotliEncoderMaxCompressedSize (size_t input_size)" + +.PP +Calculates the output size bound for the given \fCinput_size\fP\&. +.PP +\fBWarning:\fP +.RS 4 +Result is only valid if quality is at least \fC2\fP and, in case \fBBrotliEncoderCompressStream\fP was used, no flushes (\fBBROTLI_OPERATION_FLUSH\fP) were performed\&. +.RE +.PP +\fBParameters:\fP +.RS 4 +\fIinput_size\fP size of projected input +.RE +.PP +\fBReturns:\fP +.RS 4 +\fC0\fP if result does not fit \fCsize_t\fP +.RE +.PP + +.SS "\fBBROTLI_BOOL\fP BrotliEncoderSetParameter (\fBBrotliEncoderState\fP * state, \fBBrotliEncoderParameter\fP param, uint32_t value)" + +.PP +Sets the specified parameter to the given encoder instance\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP encoder instance +.br +\fIparam\fP parameter to set +.br +\fIvalue\fP new parameter value +.RE +.PP +\fBReturns:\fP +.RS 4 +\fBBROTLI_FALSE\fP if parameter is unrecognized, or value is invalid +.PP +\fBBROTLI_FALSE\fP if value of parameter can not be changed at current encoder state (e\&.g\&. when encoding is started, window size might be already encoded and therefore it is impossible to change it) +.PP +\fBBROTLI_TRUE\fP if value is accepted +.RE +.PP +\fBWarning:\fP +.RS 4 +invalid values might be accepted in case they would not break encoding process\&. +.RE +.PP + +.SS "const uint8_t* BrotliEncoderTakeOutput (\fBBrotliEncoderState\fP * state, size_t * size)" + +.PP +Acquires pointer to internal output buffer\&. This method is used to make language bindings easier and more efficient: +.IP "1." 4 +push data to \fBBrotliEncoderCompressStream\fP, until \fBBrotliEncoderHasMoreOutput\fP returns BROTL_TRUE +.IP "2." 4 +use \fBBrotliEncoderTakeOutput\fP to peek bytes and copy to language-specific entity +.PP +.PP +Also this could be useful if there is an output stream that is able to consume all the provided data (e\&.g\&. when data is saved to file system)\&. +.PP +\fBAttention:\fP +.RS 4 +After every call to \fBBrotliEncoderTakeOutput\fP \fC*size\fP bytes of output are considered consumed for all consecutive calls to the instance methods; returned pointer becomes invalidated as well\&. +.RE +.PP +\fBNote:\fP +.RS 4 +Encoder output is not guaranteed to be contiguous\&. This means that after the size-unrestricted call to \fBBrotliEncoderTakeOutput\fP, immediate next call to \fBBrotliEncoderTakeOutput\fP may return more data\&. +.RE +.PP +\fBParameters:\fP +.RS 4 +\fIstate\fP encoder instance +.br +\fIsize\fP \fBin:\fP number of bytes caller is ready to take, \fC0\fP if any amount could be handled; +.br + \fBout:\fP amount of data pointed by returned pointer and considered consumed; +.br + out value is never greater than in value, unless it is \fC0\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +pointer to output data +.RE +.PP + +.SS "uint32_t BrotliEncoderVersion (void)" + +.PP +Gets an encoder library version\&. Look at BROTLI_VERSION for more information\&. +.SH "Author" +.PP +Generated automatically by Doxygen for Brotli from the source code\&. diff --git a/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/types.h.3 b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/types.h.3 new file mode 100644 index 000000000..bef931303 --- /dev/null +++ b/roms/edk2/MdeModulePkg/Library/BrotliCustomDecompressLib/brotli/docs/types.h.3 @@ -0,0 +1,117 @@ +.TH "types.h" 3 "Thu Feb 22 2018" "Brotli" \" -*- nroff -*- +.ad l +.nh +.SH NAME +types.h \- Common types used in decoder and encoder API\&. + +.SH SYNOPSIS +.br +.PP +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBBROTLI_BOOL\fP int" +.br +.RI "\fIA portable \fCbool\fP replacement\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_FALSE\fP 0" +.br +.RI "\fIPortable \fCfalse\fP replacement\&. \fP" +.ti -1c +.RI "#define \fBBROTLI_TRUE\fP 1" +.br +.RI "\fIPortable \fCtrue\fP replacement\&. \fP" +.ti -1c +.RI "#define \fBTO_BROTLI_BOOL\fP(X) (!!(X) ? \fBBROTLI_TRUE\fP : \fBBROTLI_FALSE\fP)" +.br +.RI "\fI\fCbool\fP to \fBBROTLI_BOOL\fP conversion macros\&. \fP" +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef void *(* \fBbrotli_alloc_func\fP) (void *opaque, size_t size)" +.br +.RI "\fIAllocating function pointer type\&. \fP" +.ti -1c +.RI "typedef void(* \fBbrotli_free_func\fP) (void *opaque, void *address)" +.br +.RI "\fIDeallocating function pointer type\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Common types used in decoder and encoder API\&. + + +.SH "Macro Definition Documentation" +.PP +.SS "#define BROTLI_BOOL int" + +.PP +A portable \fCbool\fP replacement\&. \fBBROTLI_BOOL\fP is a 'documentation' type: actually it is \fCint\fP, but in API it denotes a type, whose only values are \fBBROTLI_TRUE\fP and \fBBROTLI_FALSE\fP\&. +.PP +\fBBROTLI_BOOL\fP values passed to Brotli should either be \fBBROTLI_TRUE\fP or \fBBROTLI_FALSE\fP, or be a result of \fBTO_BROTLI_BOOL\fP macros\&. +.PP +\fBBROTLI_BOOL\fP values returned by Brotli should not be tested for equality with \fCtrue\fP, \fCfalse\fP, \fBBROTLI_TRUE\fP, \fBBROTLI_FALSE\fP, but rather should be evaluated, for example: +.PP +.nf +if (SomeBrotliFunction(encoder, BROTLI_TRUE) && + !OtherBrotliFunction(decoder, BROTLI_FALSE)) { + bool x = !!YetAnotherBrotliFunction(encoder, TO_BROLTI_BOOL(2 * 2 == 4)); + DoSomething(x); +} + +.fi +.PP + +.SS "#define BROTLI_FALSE 0" + +.PP +Portable \fCfalse\fP replacement\&. +.SS "#define BROTLI_TRUE 1" + +.PP +Portable \fCtrue\fP replacement\&. +.SS "#define TO_BROTLI_BOOL(X) (!!(X) ? \fBBROTLI_TRUE\fP : \fBBROTLI_FALSE\fP)" + +.PP +\fCbool\fP to \fBBROTLI_BOOL\fP conversion macros\&. +.SH "Typedef Documentation" +.PP +.SS "typedef void*(* brotli_alloc_func) (void *opaque, size_t size)" + +.PP +Allocating function pointer type\&. +.PP +\fBParameters:\fP +.RS 4 +\fIopaque\fP custom memory manager handle provided by client +.br +\fIsize\fP requested memory region size; can not be \fC0\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +\fC0\fP in the case of failure +.PP +a valid pointer to a memory region of at least \fCsize\fP bytes long otherwise +.RE +.PP + +.SS "typedef void(* brotli_free_func) (void *opaque, void *address)" + +.PP +Deallocating function pointer type\&. This function \fBSHOULD\fP do nothing if \fCaddress\fP is \fC0\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIopaque\fP custom memory manager handle provided by client +.br +\fIaddress\fP memory region pointer returned by \fBbrotli_alloc_func\fP, or \fC0\fP +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Brotli from the source code\&. |