[pbs-devel] [PATCH v3 proxmox-backup 55/58] docs: describe file format for split payload files

[Christian Ebner]

Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
---
changes since version 2:
- not present in previous version

 docs/file-formats.rst         | 32 ++++++++++++++++++++++
 docs/meta-format-overview.dot | 50 +++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 docs/meta-format-overview.dot

diff --git a/docs/file-formats.rst b/docs/file-formats.rst
index 43ecfefce..292660579 100644
--- a/docs/file-formats.rst
+++ b/docs/file-formats.rst
@@ -8,6 +8,38 @@ Proxmox File Archive Format (``.pxar``)
 
 .. graphviz:: pxar-format-overview.dot
 
+.. _pxar-meta-format:
+
+Proxmox File Archive Format - Meta (``.mpxar``)
+-----------------------------------------------
+
+.. graphviz:: meta-format-overview.dot
+
+.. _ppxar-format:
+
+Proxmox File Archive Format - Payload (``.ppxar``)
+--------------------------------------------------
+
+The pxar payload contains a concatenation of regular file payloads,
+each prefixed by a `PAYLOAD` header. Further, the entries can have
+some padding following the actual payload, if a referenced chunk was
+not fully reused:
+
+.. list-table::
+   :widths: auto
+
+   * - ``PAYLOAD_START_MARKER``
+     - ``[u8; 16]``
+   * - ``PAYLOAD``
+     - ``header with [u8; 16]``
+   * - ``Payload``
+     - ``raw regular file payload``
+   * - ``Padding``
+     - ``none if chunk fully reused``
+   * - ``...``
+     - ``Further list of header, payload and padding``
+   * - ``PAYLOAD_TAIL_MARKER``
+     - ``[u8; 16]``
 
 .. _data-blob-format:
 
diff --git a/docs/meta-format-overview.dot b/docs/meta-format-overview.dot
new file mode 100644
index 000000000..c3e4869b3
--- /dev/null
+++ b/docs/meta-format-overview.dot
@@ -0,0 +1,50 @@
+digraph g {
+graph [
+rankdir = "LR"
+fontname="Helvetica"
+];
+node [
+fontsize = "16"
+shape = "record"
+];
+edge [
+];
+
+"archive" [
+label = "archive.mpxar"
+shape = "record"
+];
+
+"rootdir" [
+label = "<f0> FORMAT_VERSION | CLI_PARAMS | ENTRY| \{XATTR\}\* extended attribute list\l | \{ACL_USER\}\* USER ACL entries\l | \{ACL_GROUP\}\* GROUP ACL entries\l| \[ACL_GROUP_OBJ\] the ACL_GROUP_OBJ \l| \[ACL_DEFAULT\] the various default ACL fields\l|\{ACL_DEFAULT_USER\}\* USER ACL entries\l|\{ACL_DEFAULT_GROUP\}\* GROUP ACL entries\l|\[FCAPS\] file capability in Linux disk format\l|\[QUOTA_PROJECT_ID\] the ext4/xfs quota project ID\l| { <pl> PAYLOAD_REF  | SYMLINK | DEVICE | { <de> \{DirectoryEntries\}\* | GOODBYE}}"
+shape = "record"
+];
+
+
+"entry" [
+label = "<f0> size: u64 = 64\l|type: u64 = ENTRY\l|feature_flags: u64\l|mode: u64\l|flags: u64\l|uid: u64\l|gid: u64\l|mtime: u64\l"
+labeljust = "l"
+shape = "record"
+];
+
+
+
+"direntry" [
+label = "<f0> FILENAME |{ENTRY | HARDLINK}"
+shape = "record"
+];
+
+"payloadrefentry" [
+label = "<f0> offset: u64 \l| size: u64\l"
+shape = "record"
+];
+
+"archive" -> "rootdir":f0
+
+"rootdir":f0 -> "entry":f0
+
+"rootdir":de -> "direntry":f0
+
+"rootdir":pl -> "payloadrefentry":f0
+
+}
-- 
2.39.2