1eda14cbcSMatt Macy# ZSTD-On-ZFS Library Manual 2eda14cbcSMatt Macy 3eda14cbcSMatt Macy## Introduction 4eda14cbcSMatt Macy 5eda14cbcSMatt MacyThis subtree contains the ZSTD library used in ZFS. It is heavily cut-down by 6eda14cbcSMatt Macydropping any unneeded files, and combined into a single file, but otherwise is 7eda14cbcSMatt Macyintentionally unmodified. Please do not alter the file containing the zstd 8eda14cbcSMatt Macylibrary, besides upgrading to a newer ZSTD release. 9eda14cbcSMatt Macy 10eda14cbcSMatt MacyTree structure: 11eda14cbcSMatt Macy 12*716fd348SMartin Matuska* `zfs_zstd.c` are the actual `zfs` kernel module hooks. 13c03c5b1cSMartin Matuska* `lib/` contains the unmodified version of the `Zstandard` library 14c03c5b1cSMartin Matuska* `zstd-in.c` is our template file for generating the single-file library 15eda14cbcSMatt Macy* `include/`: This directory contains supplemental includes for platform 16eda14cbcSMatt Macy compatibility, which are not expected to be used by ZFS elsewhere in the 17eda14cbcSMatt Macy future. Thus we keep them private to ZSTD. 18eda14cbcSMatt Macy 19eda14cbcSMatt Macy## Updating ZSTD 20eda14cbcSMatt Macy 21eda14cbcSMatt MacyTo update ZSTD the following steps need to be taken: 22eda14cbcSMatt Macy 23eda14cbcSMatt Macy1. Grab the latest release of [ZSTD](https://github.com/facebook/zstd/releases). 24c03c5b1cSMartin Matuska2. Copy the files output by the following script to `module/zstd/lib/`: 25c03c5b1cSMartin Matuska`grep include [path to zstd]/contrib/single_file_libs/zstd-in.c | awk '{ print $2 }'` 26c03c5b1cSMartin Matuska3. Remove debug.c, threading.c, and zstdmt_compress.c. 27c03c5b1cSMartin Matuska4. Update Makefiles with resulting file lists. 28*716fd348SMartin Matuska5. Follow symbol renaming notes in `include/zstd_compat_wrapper.h` 29eda14cbcSMatt Macy 30eda14cbcSMatt Macy## Altering ZSTD and breaking changes 31eda14cbcSMatt Macy 32eda14cbcSMatt MacyIf ZSTD made changes that break compatibility or you need to make breaking 33eda14cbcSMatt Macychanges to the way we handle ZSTD, it is required to maintain backwards 34eda14cbcSMatt Macycompatibility. 35eda14cbcSMatt Macy 36eda14cbcSMatt MacyWe already save the ZSTD version number within the block header to be used 37eda14cbcSMatt Macyto add future compatibility checks and/or fixes. However, currently it is 38eda14cbcSMatt Macynot actually used in such a way. 39