+ * Feature description: Compression
+ * --------------------
+ * In order to avoid keeping large amunt of memory reserved for a panic stackshot, kcdata has support
+ * for compressing the buffer in a streaming fashion. New data pushed to the kcdata buffer will be
+ * automatically compressed using an algorithm selected by the API user (currently, we only support
+ * pass-through and zlib, in the future we plan to add WKDM support, see: 57913859).
+ *
+ * To start using compression, call:
+ * kcdata_init_compress(kcdata_p, hdr_tag, memcpy_f, comp_type);
+ * where:
+ * `kcdata_p` is the kcdata buffer that will be used
+ * `hdr_tag` is the usual header tag denoting what type of kcdata buffer this will be
+ * `memcpy_f` a memcpy(3) function to use to copy into the buffer, optional.
+ * `compy_type` is the compression type, see KCDCT_ZLIB for an example.
+ *
+ * Once compression is initialized:
+ * (1) all self-describing APIs will automatically compress
+ * (2) you can now use the following APIs to compress data into the buffer:
+ * (None of the following will compress unless kcdata_init_compress() has been called)
+ *
+ * - kcdata_push_data(kcdata_descriptor_t data, uint32_t type, uint32_t size, const void *input_data)
+ * Pushes the buffer of kctype @type at[@input_data, @input_data + @size]
+ * into the kcdata buffer @data, compressing if needed.
+ *
+ * - kcdata_push_array(kcdata_descriptor_t data, uint32_t type_of_element,
+ * uint32_t size_of_element, uint32_t count, const void *input_data)
+ * Pushes the array found at @input_data, with element type @type_of_element, where
+ * each element is of size @size_of_element and there are @count elements into the kcdata buffer
+ * at @data.
+ *
+ * - kcdata_compression_window_open/close(kcdata_descriptor_t data)
+ * In case the data you are trying to push to the kcdata buffer @data is difficult to predict,
+ * you can open a "compression window". Between an open and a close, no compression will be done.
+ * Once you clsoe the window, the underlying compression algorithm will compress the data into the buffer
+ * and automatically rewind the current end marker of the kcdata buffer.
+ * There is an ASCII art in kern_cdata.c to aid the reader in understanding
+ * this.
+ *
+ * - kcdata_finish_compression(kcdata_descriptor_t data)
+ * Must be called at the end to flush any underlying buffers used by the compression algorithms.
+ * This function will also add some statistics about the compression to the buffer which helps with
+ * decompressing later.
+ *
+ * Once you are done with the kcdata buffer, call kcdata_deinit_compress to
+ * free any buffers that may have been allocated internal to the compression
+ * algorithm.
projects / apple / xnu.git / blobdiff