[PATCH 0/3] Sphinx docs: Design Document for NUMA node-affine claim sets

[Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>]

Dear reviewers,

This updated design document forms the basis of the NUMA claims v7
series and is intended to serve as a reference during review.

It extends Xen's memory claim design to support installing claim sets
spanning multiple NUMA nodes atomically. As Roger Pau Monné suggested:

   Ideally, we would need to introduce a new hypercall that allows
   making claims from multiple nodes in a single locked region, as
   to ensure success or failure in an atomic way.

This design documents that model in detail and is integrated into the
Sphinx site below Hypervisor Guide -> Design Documents -> NUMA Claims.

The rendered design document is available here for review:

https://xen.kaindl.dev/claims-v7-design-master/designs/claims/

The Sphinx site can be built and viewed locally as follows:

  git pull git@xxxxxxxxxx:bernhardkaindl/xen.git claims-v7-design-master
  make -C docs sphinx-env-build # xdg-open docs/sphinx/html/index.html
  or start a minimal HTTP server:
    (cd docs/sphinx/html; python -m http.server)

Changes since v6
----------------

The review comments from v6 have been incorporated.

In particular, Jan noted that "global" is ambiguous in this context,
and following his suggestion, this series adopts the term host claims
(short for host-wide claims) found here:
https://lists.xen.org/archives/html/xen-devel/2026-05/msg00026.html

The helper names have also been adjusted to make domain scope explicit
and to keep the release/set/get operations named consistently:

- deduct_global_claims()         -> domain_release_host_claims()
- deduct_node_claims()           -> domain_release_node_claims()
- domain_set_outstanding_pages() -> domain_set_claim_entries()
- new: domain_get_claim_entries()

This version also keeps the new code minimal for review and avoids
functional duplication. domain_set_claim_entries() now also handles
the legacy XENMEM_claim_pages interface for backwards compatibility,
replacing domain_set_outstanding_pages().

Best regards,

Bernhard

Bernhard Kaindl (3):
  Sphinx docs: Rearrange the design docs into a new dedicated design
    index
  Sphinx docs: Enable autosectionlabels and Mermaid support
  Sphinx docs: Design Document for NUMA node affine claim sets

 .readthedocs.yaml                             |   2 +-
 docs/conf.py                                  |  21 +
 docs/{misc => designs}/cache-coloring.rst     |   4 +-
 docs/designs/claims/accounting.rst            | 331 +++++++++++++++
 docs/designs/claims/design.rst                | 243 +++++++++++
 docs/designs/claims/development.rst           | 197 +++++++++
 docs/designs/claims/implementation.rst        | 393 ++++++++++++++++++
 docs/designs/claims/index.rst                 |  48 +++
 docs/designs/claims/installation.rst          |  70 ++++
 docs/designs/claims/invariants.mmd            |  35 ++
 docs/designs/claims/performance.rst           |  33 ++
 docs/designs/claims/protection.rst            | 200 +++++++++
 docs/designs/claims/redeeming.rst             |  71 ++++
 docs/designs/claims/terminology.rst           | 138 ++++++
 docs/designs/claims/use-cases.rst             |  39 ++
 docs/designs/index.rst                        |  17 +
 docs/designs/launch/hyperlaunch.rst           |   4 +-
 docs/designs/launch/index.rst                 |  10 +
 docs/glossary.rst                             |  12 +-
 .../dom/DOMCTL_claim_memory-data.mmd          |  43 ++
 .../dom/DOMCTL_claim_memory-seqdia.mmd        |  23 +
 .../dom/DOMCTL_claim_memory-workflow.mmd      |  23 +
 docs/guest-guide/dom/DOMCTL_claim_memory.rst  | 221 ++++++++++
 docs/guest-guide/dom/index.rst                |  14 +
 docs/guest-guide/index.rst                    |  23 +
 docs/guest-guide/mem/XENMEM_claim_pages.rst   | 102 +++++
 docs/guest-guide/mem/index.rst                |  12 +
 docs/hypervisor-guide/index.rst               |  12 +-
 docs/index.rst                                |   2 -
 29 files changed, 2331 insertions(+), 12 deletions(-)
 rename docs/{misc => designs}/cache-coloring.rst (99%)
 create mode 100644 docs/designs/claims/accounting.rst
 create mode 100644 docs/designs/claims/design.rst
 create mode 100644 docs/designs/claims/development.rst
 create mode 100644 docs/designs/claims/implementation.rst
 create mode 100644 docs/designs/claims/index.rst
 create mode 100644 docs/designs/claims/installation.rst
 create mode 100644 docs/designs/claims/invariants.mmd
 create mode 100644 docs/designs/claims/performance.rst
 create mode 100644 docs/designs/claims/protection.rst
 create mode 100644 docs/designs/claims/redeeming.rst
 create mode 100644 docs/designs/claims/terminology.rst
 create mode 100644 docs/designs/claims/use-cases.rst
 create mode 100644 docs/designs/index.rst
 create mode 100644 docs/designs/launch/index.rst
 create mode 100644 docs/guest-guide/dom/DOMCTL_claim_memory-data.mmd
 create mode 100644 docs/guest-guide/dom/DOMCTL_claim_memory-seqdia.mmd
 create mode 100644 docs/guest-guide/dom/DOMCTL_claim_memory-workflow.mmd
 create mode 100644 docs/guest-guide/dom/DOMCTL_claim_memory.rst
 create mode 100644 docs/guest-guide/dom/index.rst
 create mode 100644 docs/guest-guide/mem/XENMEM_claim_pages.rst
 create mode 100644 docs/guest-guide/mem/index.rst

-- 
2.39.5