commit 96a1d71709381c4967ac9a2534a3b8b25e13e0c1
from: Stefan Sperling <stsp@stsp.name>
date: Wed Jan 24 16:54:21 2018 UTC

document the delta stream data format

commit - 710bb5ca3b8431a50bbc184d82c55e881ee43400
commit + 96a1d71709381c4967ac9a2534a3b8b25e13e0c1
blob - 3c6a6e724069a232e85775d3c107fa419a473769
blob + ebdebab3fc9d4c856f0e8b58963f92726a6439a5
--- lib/delta.h
+++ lib/delta.h
@@ -33,3 +33,57 @@ const struct got_error *got_delta_chain_get_base_type(
     struct got_delta_chain *);
 const struct got_error *got_delta_apply(struct got_delta *, FILE *, FILE *,
     FILE *);
+
+/*
+ * Definitions for delta data streams.
+ */
+
+#define GOT_DELTA_STREAM_LENGTH_MIN	4	/* bytes */
+
+/*
+ * A delta stream begins with two size fields. The first specifies the
+ * size of the delta base, and the second describes the expected size of
+ * the data which results from combining the delta base and the delta.
+ *
+ * Each size field uses a variable length encoding:
+ * size0...sizeN form a 7+7+7+...+7 bit integer, where size0 is the
+ * least significant part and sizeN is the most significant part.
+ * If the MSB of a size byte is set, an additional size byte follows.
+ */
+#define GOT_DELTA_SIZE_VAL_MASK	0x7f
+#define GOT_DELTA_SIZE_SHIFT	7
+#define GOT_DELTA_SIZE_MORE	0x80
+
+/*
+ * A delta stream contains copy opcodes and verbatim data.
+ *
+ * A copy opcode instructs the delta combiner to copy N bytes starting at
+ * offset X from the delta base to the output. Copy opcodes begin with a
+ * byte which has its MSB set. The remaining bits of this byte describe how
+ * many offset and length value bytes follow.
+ * The offset X is encoded in 1 to 4 bytes, and the length N is encoded in
+ * 1 to 3 bytes. For both values, the first byte contributes the least
+ * significant part and the last byte which is present contributes the
+ * most significant part.
+ * If the offset value is omitted, an offset of zero is implied.
+ * If the length value is omitted, a default length of 65536 bytes is implied.
+ *
+ * Verbatim data is copied from the delta stream to the output.
+ * Verbatim data is preceded by one byte which does not have the MSB set
+ * and which specifies the length of the verbatim data which follows (i.e.
+ * at most 127 bytes). A length value of zero is invalid.
+ */
+
+#define GOT_DELTA_COPY_OPCODE	0x80
+
+#define GOT_DELTA_COPY_OFF1	0x01	/* byte 1 of offset is present */
+#define GOT_DELTA_COPY_OFF2	0x02	/* byte 2 of offset is present */
+#define GOT_DELTA_COPY_OFF3	0x04	/* byte 3 of offset is present */
+#define GOT_DELTA_COPY_OFF4	0x08	/* byte 4 of offset is present */
+
+#define GOT_DELTA_COPY_LEN1	0x10	/* byte 1 of length is present */
+#define GOT_DELTA_COPY_LEN2	0x20	/* byte 2 of length is present */
+#define GOT_DELTA_COPY_LEN3	0x40	/* byte 3 of length is present */
+
+#define GOT_DELTA_COPY_DEFAULT_OFF	0x0	/* default offset if omitted */
+#define GOT_DELTA_COPY_DEFAULT_LEN	0x10000 /* default length if omitted */