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

[Fabian Grünbichler]

Quoting Christian Ebner (2024-03-28 13:37:04)
> 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``

well.. technically somehow true, but for a format description this only gives
half the picture IMHO ;) at least mentioning that the Padding itself consists
of (possibly truncated) ``PAYLOAD`` entries would probably help for new people
trying to understand the structure. also, mentioning what the 16 bytes in the
header mean would be helpful?

it might also be nice to dump the magic values and include them here and in the
other related sections, like for the blobs (but always correct, not as a
possibly outdated copy ;))

> +   * - ``...``
> +     - ``Further list of header, payload and padding``
> +   * - ``PAYLOAD_TAIL_MARKER``
> +     - ``[u8; 16]``
>  
>  .. _data-blob-format: