Skip to content

Added ZoneX to the documentation site - #59

Merged
fdesbiens merged 2 commits into
eclipse-threadx:mainfrom
fdesbiens:feature/zonex-docs
Sep 9, 2026
Merged

fdesbiens merged 2 commits into
eclipse-threadx:mainfrom
fdesbiens:feature/zonex-docs

Conversation

@fdesbiens

Copy link
Copy Markdown
Contributor

ZoneX is a deterministic partitioning hypervisor for Armv8-R and a new component of the suite, so it gets its own place in the navigation rather than a subsection of the ThreadX port pages. Six pages, following the shape the Cortex-R52 Modules documentation settled: the index stays a bare index, and each piece of detail gets its own page beneath it.

Page What it is for
Overview what the component is, and how a partitioned system is put together
What Phase 0 demonstrates, and what it does not the claim, the measurements, and the non-claim — where the index sends a reader first
Platform requirements and the region budget read before choosing a board
Writing a partition manifest the configuration reference, with a compiled example
Later phases marked throughout as not shipped

Two pages are written to be quoted rather than summarised.

The claim page states the temporal result split by cause, because the halves have different causes and only one is the partitioning: nothing a partition does through the schedule reaches its neighbour, and what does reach it is the hypervisor's own console driver, at up to one line tag per run — 22 bytes at 115,200 8N1, 17,640 counts of the board's 8 MHz counter. That is a defect in ZoneX rather than a limit of the partitioning, bounded and derived rather than observed. The page carries the non-claim in full, including that interrupt latency is not measured at all and that there is no structural coverage of the port.

The platform page states the region budget as a hard portability limit. A Cortex-R52 configured with no EL2 memory protection unit cannot run ZoneX at all, and there is no software fallback — on Armv8-R both stages of address control are region-based, so there is nothing else to fall back on. It also records that the fixed virtual platform cannot show a reader this constraint, since its console and interrupt controller cost no regions where a real part's do.

The manifest example is a constant, not the harness's shape. The demonstrator images build their manifests at run time from linker symbols so that a harness never restates an address the linker chose, but a real system's manifest is a constant, so that is what the page shows. The snippet was extracted from the rendered page and compiled against the real headers under -Wall -Wextra -Wpedantic; the three validator results quoted beneath it came from running the real validator rather than reading the error codes.

Scope of the wiring. Adding a component touches more than its own directory: the site playbooks, the component list on the home page, and the navigation of every other component, since each lists them all and a component present in its own nav but absent from the others is a half-landed change. The PDF assemblers need no change — they filter component versions rather than naming them.

Prose is unwrapped, one paragraph per line, matching the rest of the repository. Built locally with npm run build:html: no unresolved cross-references, all six pages render, and ZoneX appears in every component's navigation.

The companion code pull request introduces the component itself.

@fdesbiens

Copy link
Copy Markdown
Contributor Author

Companion code pull request: eclipse-threadx/zonex#5 — it introduces the component these pages document.

ZoneX is a deterministic partitioning hypervisor for Armv8-R and a new
component of the suite, so it gets its own place in the navigation rather than
a subsection of the ThreadX port pages. Six pages, and the shape follows what
the Cortex-R52 Modules documentation settled: the index stays a bare index and
each piece of detail gets its own page beneath it.

An overview of what the component is and how a partitioned system is put
together. What Phase 0 demonstrates and what it does not, which is the page
the index sends a reader to first and the one that carries the measurements.
Platform requirements and the region budget, which is the page someone reads
before choosing a board. Writing a partition manifest. And the later phases,
marked throughout as not shipped.

TWO PAGES ARE WRITTEN TO BE QUOTED RATHER THAN SUMMARISED.

The claim page states the temporal result split by cause, because the two
halves have different causes and only one of them is the partitioning:
nothing a partition does through the schedule reaches its neighbour, and what
does reach it is the hypervisor's own console driver, at a cost of one line
tag per run. That is a defect in ZoneX rather than a limit of the
partitioning, it is bounded and derived rather than observed, and the page
says so with the number attached. It also carries the non-claim in full,
including that interrupt latency is not measured at all and that there is no
structural coverage of the port.

The platform page states the region budget as a hard portability limit rather
than a note. A Cortex-R52 configured with no EL2 memory protection unit cannot
run ZoneX at all, and there is no software fallback, because on Armv8-R both
stages of address control are region-based and there is nothing else to fall
back on. It also records that the fixed virtual platform cannot show a reader
this constraint, since its console and interrupt controller cost no regions
where a real part's do.

THE MANIFEST EXAMPLE IS A CONSTANT, NOT THE HARNESS'S SHAPE. The demonstrator
images build their manifests at run time from linker symbols, deliberately, so
that a harness never restates an address the linker chose -- but a real
system's manifest is a constant, so that is what the page shows. The snippet
was extracted from the rendered page and compiled against the real headers
under -Wall -Wextra -Wpedantic, and the three validator results quoted beneath
it were produced by running the real validator rather than read off the error
codes.

Adding a component touches more than its own directory: the site playbooks,
the component list on the home page, and the navigation of every other
component, since each one lists them all and a component present in its own
nav but absent from the others is a half-landed change. The PDF assemblers
need no change; they filter component versions rather than naming them.

Prose is unwrapped, one paragraph per line, matching the rest of the
repository. The site builds with no unresolved cross-references.

Assisted-by: Claude Code (Opus 5) <noreply@anthropic.com>
The table came from a run six days old, taken before three commits that moved
the memory-type vocabulary and the region granule between headers. Those
changes are behaviour-neutral by construction and the assertions that bind
them are compile-time, but a page quoting silicon should quote the silicon the
code actually ships as.

Re-run on the same board: 22, 20, 24 and 185 counts for the quiet and fault
phases, 17,951 for the console, and the same 22-byte console hypercall at
106,116 core cycles.

The earlier run is now cited beside it rather than replaced, because two
independent runs agreeing to within the scatter is a different and better
claim than one run's figures. A single bench is only worth quoting if it
reproduces, and now the page says so with both sets of numbers.
@fdesbiens
fdesbiens merged commit e260200 into eclipse-threadx:main Sep 9, 2026
1 check passed
@fdesbiens
fdesbiens deleted the feature/zonex-docs branch September 9, 2026 19:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant