updated documentation in anticipation for `v1.9.4` release

2 files changed, 121 insertions, 52 deletions

diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html
index 5461ab9..6fafb21 100644
--- a/doc/lz4_manual.html
+++ b/doc/lz4_manual.html
@@ -48,6 +48,35 @@
   The `lz4` CLI can only manage frames.
 <BR></pre>
 
+<pre><b>#if defined(LZ4_FREESTANDING) && (LZ4_FREESTANDING == 1)
+#  define LZ4_HEAPMODE 0
+#  define LZ4HC_HEAPMODE 0
+#  define LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION 1
+#  if !defined(LZ4_memcpy)
+#    error "LZ4_FREESTANDING requires macro 'LZ4_memcpy'."
+#  endif
+#  if !defined(LZ4_memset)
+#    error "LZ4_FREESTANDING requires macro 'LZ4_memset'."
+#  endif
+#  if !defined(LZ4_memmove)
+#    error "LZ4_FREESTANDING requires macro 'LZ4_memmove'."
+#  endif
+#elif ! defined(LZ4_FREESTANDING)
+#  define LZ4_FREESTANDING 0
+#endif
+</b><p>  When this macro is set to 1, it enables "freestanding mode" that is
+  suitable for typical freestanding environment which doesn't support
+  standard C library.
+
+  - LZ4_FREESTANDING is a compile-time switch.
+  - It requires the following macros to be defined:
+    LZ4_memcpy, LZ4_memmove, LZ4_memset.
+  - It only enables LZ4/HC functions which don't use heap.
+    All LZ4F_* functions are not supported.
+  - See tests/freestanding.c to check its basic setup.
+ 
+</p></pre><BR>
+
 <a name="Chapter2"></a><h2>Version</h2><pre></pre>
 
 <pre><b>int LZ4_versionNumber (void);  </b>/**< library version number; useful to check dll version; requires v1.3.0+ */<b>
@@ -267,8 +296,10 @@ int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int src
 <a name="Chapter7"></a><h2>Streaming Decompression Functions</h2><pre>  Bufferless synchronous API
 <BR></pre>
 
-<pre><b>LZ4_streamDecode_t* LZ4_createStreamDecode(void);
+<pre><b>#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION)
+LZ4_streamDecode_t* LZ4_createStreamDecode(void);
 int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
+#endif </b>/* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */<b>
 </b><p>  creation / destruction of streaming decompression tracking context.
   A tracking context can be re-used multiple times.
  
@@ -297,7 +328,10 @@ int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
  
 </p></pre><BR>
 
-<pre><b>int LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int srcSize, int dstCapacity);
+<pre><b>int
+LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode,
+                        const char* src, char* dst,
+                        int srcSize, int dstCapacity);
 </b><p>  These decoding functions allow decompression of consecutive blocks in "streaming" mode.
   A block is an unsplittable entity, it must be presented entirely to a decompression function.
   Decompression functions only accepts one block at a time.
@@ -323,7 +357,10 @@ int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
   then indicate where this data is saved using LZ4_setStreamDecode(), before decompressing next block.
 </p></pre><BR>
 
-<pre><b>int LZ4_decompress_safe_usingDict (const char* src, char* dst, int srcSize, int dstCapcity, const char* dictStart, int dictSize);
+<pre><b>int
+LZ4_decompress_safe_usingDict(const char* src, char* dst,
+                              int srcSize, int dstCapacity,
+                              const char* dictStart, int dictSize);
 </b><p>  These decoding functions work the same as
   a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue()
   They are stand-alone, and don't need an LZ4_streamDecode_t structure.
@@ -363,7 +400,9 @@ int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
  
 </p></pre><BR>
 
-<pre><b>LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const LZ4_stream_t* dictionaryStream);
+<pre><b>LZ4LIB_STATIC_API void
+LZ4_attach_dictionary(LZ4_stream_t* workingStream,
+                const LZ4_stream_t* dictionaryStream);
 </b><p>  This is an experimental API that allows
   efficient use of a static dictionary many times.
 
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html
index 196881e..cfb437e 100644
--- a/doc/lz4frame_manual.html
+++ b/doc/lz4frame_manual.html
@@ -22,9 +22,9 @@
 </ol>
 <hr>
 <a name="Chapter1"></a><h2>Introduction</h2><pre>
-  lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md).
-  lz4frame.h provides frame compression functions that take care
-  of encoding standard metadata alongside LZ4-compressed blocks.
+ lz4frame.h implements LZ4 frame specification: see doc/lz4_Frame_format.md .
+ LZ4 Frames are compatible with `lz4` CLI,
+ and designed to be interoperable with any system.
 <BR></pre>
 
 <a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre>
@@ -135,17 +135,19 @@
 
 <pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
 LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
-</b><p> The first thing to do is to create a compressionContext object,
- which will keep track of operation state during streaming compression.
- This is achieved using LZ4F_createCompressionContext(), which takes as argument a version.
- The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL.
- The function will provide a pointer to a fully allocated LZ4F_cctx object.
- If @return != zero, there context creation failed.
- Once all streaming compression jobs are completed,
- the state object can be released using LZ4F_freeCompressionContext().
- Note1 : LZ4F_freeCompressionContext() is always successful. Its return value can be ignored.
- Note2 : LZ4F_freeCompressionContext() works fine with NULL input pointers (do nothing).
- 
+</b><p>  The first thing to do is to create a compressionContext object,
+  which will keep track of operation state during streaming compression.
+  This is achieved using LZ4F_createCompressionContext(), which takes as argument a version,
+  and a pointer to LZ4F_cctx*, to write the resulting pointer into.
+  @version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL.
+  The function provides a pointer to a fully allocated LZ4F_cctx object.
+  @cctxPtr MUST be != NULL.
+  If @return != zero, context creation failed.
+  A created compression context can be employed multiple times for consecutive streaming operations.
+  Once all streaming compression jobs are completed,
+  the state object can be released using LZ4F_freeCompressionContext().
+  Note1 : LZ4F_freeCompressionContext() is always successful. Its return value can be ignored.
+  Note2 : LZ4F_freeCompressionContext() works fine with NULL input pointers (do nothing).
 </p></pre><BR>
 
 <a name="Chapter8"></a><h2>Compression</h2><pre></pre>
@@ -225,16 +227,21 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 <a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre>
 
 <pre><b>typedef struct {
-  unsigned stableDst;    </b>/* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */<b>
-  unsigned reserved[3];  </b>/* must be set to zero for forward compatibility */<b>
+  unsigned stableDst;     /* pledges that last 64KB decompressed data will remain available unmodified between invocations.
+                           * This optimization skips storage operations in tmp buffers. */
+  unsigned skipChecksums; /* disable checksum calculation and verification, even when one is present in frame, to save CPU time.
+                           * Setting this option to 1 once disables all checksums for the rest of the frame. */
+  unsigned reserved1;     </b>/* must be set to zero for forward compatibility */<b>
+  unsigned reserved0;     </b>/* idem */<b>
 } LZ4F_decompressOptions_t;
 </b></pre><BR>
 <pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
 LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
 </b><p>  Create an LZ4F_dctx object, to track all decompression operations.
-  The version provided MUST be LZ4F_VERSION.
-  The function provides a pointer to an allocated and initialized LZ4F_dctx object.
-  The result is an errorCode, which can be tested using LZ4F_isError().
+  @version provided MUST be LZ4F_VERSION.
+  @dctxPtr MUST be valid.
+  The function fills @dctxPtr with the value of a pointer to an allocated and initialized LZ4F_dctx object.
+  The @return is an errorCode, which can be tested using LZ4F_isError().
   dctx memory can be released using LZ4F_freeDecompressionContext();
   Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released.
   That is, it should be == 0 if decompression has been completed fully and correctly.
@@ -254,11 +261,12 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
  
 </p></pre><BR>
 
-<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
-                                     LZ4F_frameInfo_t* frameInfoPtr,
-                                     const void* srcBuffer, size_t* srcSizePtr);
+<pre><b>size_t
+LZ4F_getFrameInfo(LZ4F_dctx* dctx,
+                  LZ4F_frameInfo_t* frameInfoPtr,
+            const void* srcBuffer, size_t* srcSizePtr);
 </b><p>  This function extracts frame parameters (max blockSize, dictID, etc.).
-  Its usage is optional: user can call LZ4F_decompress() directly.
+  Its usage is optional: user can also invoke LZ4F_decompress() directly.
 
   Extracted information will fill an existing LZ4F_frameInfo_t structure.
   This can be useful for allocation and dictionary identification purposes.
@@ -301,10 +309,11 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
  
 </p></pre><BR>
 
-<pre><b>size_t LZ4F_decompress(LZ4F_dctx* dctx,
-                                   void* dstBuffer, size_t* dstSizePtr,
-                                   const void* srcBuffer, size_t* srcSizePtr,
-                                   const LZ4F_decompressOptions_t* dOptPtr);
+<pre><b>size_t
+LZ4F_decompress(LZ4F_dctx* dctx,
+                void* dstBuffer, size_t* dstSizePtr,
+          const void* srcBuffer, size_t* srcSizePtr,
+          const LZ4F_decompressOptions_t* dOptPtr);
 </b><p>  Call this function repetitively to regenerate data compressed in `srcBuffer`.
 
   The function requires a valid dctx state.
@@ -352,10 +361,11 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
   the maximum block size associated with blockSizeID.
 </p></pre><BR>
 
-<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_uncompressedUpdate(LZ4F_cctx* cctx,
-                                                  void* dstBuffer, size_t dstCapacity,
-                                                  const void* srcBuffer, size_t srcSize,
-                                                  const LZ4F_compressOptions_t* cOptPtr);
+<pre><b>LZ4FLIB_STATIC_API size_t
+LZ4F_uncompressedUpdate(LZ4F_cctx* cctx,
+                        void* dstBuffer, size_t dstCapacity,
+                  const void* srcBuffer, size_t srcSize,
+                  const LZ4F_compressOptions_t* cOptPtr);
 </b><p>  LZ4F_uncompressedUpdate() can be called repetitively to add as much data uncompressed data as necessary.
   Important rule: dstCapacity MUST be large enough to store the entire source buffer as
   no compression is done for this operation
@@ -380,12 +390,12 @@ LZ4FLIB_STATIC_API void        LZ4F_freeCDict(LZ4F_CDict* CDict);
  `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict 
 </p></pre><BR>
 
-<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict(
-    LZ4F_cctx* cctx,
-    void* dst, size_t dstCapacity,
-    const void* src, size_t srcSize,
-    const LZ4F_CDict* cdict,
-    const LZ4F_preferences_t* preferencesPtr);
+<pre><b>LZ4FLIB_STATIC_API size_t
+LZ4F_compressFrame_usingCDict(LZ4F_cctx* cctx,
+                              void* dst, size_t dstCapacity,
+                        const void* src, size_t srcSize,
+                        const LZ4F_CDict* cdict,
+                        const LZ4F_preferences_t* preferencesPtr);
 </b><p>  Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary.
   cctx must point to a context created by LZ4F_createCompressionContext().
   If cdict==NULL, compress without a dictionary.
@@ -397,11 +407,11 @@ LZ4FLIB_STATIC_API void        LZ4F_freeCDict(LZ4F_CDict* CDict);
            or an error code if it fails (can be tested using LZ4F_isError()) 
 </p></pre><BR>
 
-<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict(
-    LZ4F_cctx* cctx,
-    void* dstBuffer, size_t dstCapacity,
-    const LZ4F_CDict* cdict,
-    const LZ4F_preferences_t* prefsPtr);
+<pre><b>LZ4FLIB_STATIC_API size_t
+LZ4F_compressBegin_usingCDict(LZ4F_cctx* cctx,
+                              void* dstBuffer, size_t dstCapacity,
+                        const LZ4F_CDict* cdict,
+                        const LZ4F_preferences_t* prefsPtr);
 </b><p>  Inits streaming dictionary compression, and writes the frame header into dstBuffer.
   dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes.
  `prefsPtr` is optional : you may provide NULL as argument,
@@ -410,16 +420,36 @@ LZ4FLIB_STATIC_API void        LZ4F_freeCDict(LZ4F_CDict* CDict);
            or an error code (which can be tested using LZ4F_isError()) 
 </p></pre><BR>
 
-<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict(
-    LZ4F_dctx* dctxPtr,
-    void* dstBuffer, size_t* dstSizePtr,
-    const void* srcBuffer, size_t* srcSizePtr,
-    const void* dict, size_t dictSize,
-    const LZ4F_decompressOptions_t* decompressOptionsPtr);
+<pre><b>LZ4FLIB_STATIC_API size_t
+LZ4F_decompress_usingDict(LZ4F_dctx* dctxPtr,
+                          void* dstBuffer, size_t* dstSizePtr,
+                    const void* srcBuffer, size_t* srcSizePtr,
+                    const void* dict, size_t dictSize,
+                    const LZ4F_decompressOptions_t* decompressOptionsPtr);
 </b><p>  Same as LZ4F_decompress(), using a predefined dictionary.
   Dictionary is used "in place", without any preprocessing.
   It must remain accessible throughout the entire frame decoding. 
 </p></pre><BR>
 
+<pre><b>typedef void* (*LZ4F_AllocFunction) (void* opaqueState, size_t size);
+typedef void* (*LZ4F_CallocFunction) (void* opaqueState, size_t size);
+typedef void  (*LZ4F_FreeFunction) (void* opaqueState, void* address);
+typedef struct {
+    LZ4F_AllocFunction customAlloc;
+    LZ4F_CallocFunction customCalloc; </b>/* optional; when not defined, uses customAlloc + memset */<b>
+    LZ4F_FreeFunction customFree;
+    void* opaqueState;
+} LZ4F_CustomMem;
+static
+#ifdef __GNUC__
+__attribute__((__unused__))
+#endif
+LZ4F_CustomMem const LZ4F_defaultCMem = { NULL, NULL, NULL, NULL };  </b>/**< this constant defers to stdlib's functions */<b>
+</b><p>  These prototypes make it possible to pass custom allocation/free functions.
+  LZ4F_customMem is provided at state creation time, using LZ4F_create*_advanced() listed below.
+  All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones.
+ 
+</p></pre><BR>
+
 </html>
 </body>