Re: [PATCH v2] public/xen.h: Update comment on mmu_update sub-command size and PTE alignment

[Teddy Astie <teddy.astie@xxxxxxxxxx>]

Le 24/08/2026 à 14:13, Jan Beulich a écrit :
> On 24.08.2026 11:31, Teddy Astie wrote:
> > HYPERVISOR_mmu_update passes a set of request, where each request has a pointer
> > to the PTE along with a sub-command.
> >
> > The PTE alignment padding is used to transport the sub-command while the rest
> There's no "alignment padding" here. It's the low bits of a necessarily-aligned
> PTE which are used.
>
> > is used as an address to a PTE entry. The current documentation state that the
> Nit: states
>
> > 2 first bits are used for sub-command, hence the other ones for PTE which
> Better "2 low its", as "first" is ambiguous.
>
> > imply here a 4-bytes alignment on PTEs.
> The part after the comma I'm having trouble parsing. Can this please be re-
> written some?
I agree, the wording is a bit weird. Though the name of the fields makes 
it a bit odd to work with.
We have in struct mmu_update

 uint64_t ptr;       /* Machine address of PTE. */

yet, ptr is actually something like (pte_addr | sub_command).

So we probably want to say that it's a number composed of a 8-byte 
aligned PTE address combined with 3 low bits large sub-command ?
> > On PV64 and PV32-PAE guests, all pagetable PTEs are 8-bytes aligned, hence
> > off-by-4 PTEs addresses are always incorrect. Non-PAE PV32 guests used
> > "legacy pagetables" which had 4-byte aligned PTEs. However, support had
> > been completely removed since Xen 4.0, and was only available when Xen was
> > built in 32-bits non-PAE mode [1].
> >
> > Current Xen logic behaves as if 3 bits are used as sub-command, thus all
> > off-by-4 PTEs are actually rejected as being unknown sub-commands.
> >
> > Adjust the documentation to match the current logic implemented in Xen,
> > also expanding the documented sub-command parameter to 3 bits.
> >
> > [1] 84d54d5d8b31 ("i386: Remove non-PAE hypervisor build target.")
> >
> > Signed-off-by: Frediano Ziglio <frediano.ziglio@xxxxxxxxxx>
> > Signed-off-by: Teddy Astie <teddy.astie@xxxxxxxxxx>
> Did you forget to also add a From: tag?
>
> > @@ -260,21 +260,26 @@ DEFINE_XEN_GUEST_HANDLE(xen_ulong_t);
> >    * hypercall. Also if so desired the OS can also try to write to the PTE
> >    * and be trapped by the hypervisor (as the PTE entry is RO).
> >    *
> > + * Note: Historically, Xen had support for non-PAE PV guests with 4-bytes wide
> > + *       PTEs (if Xen was built in non-PAE mode); which support got removed in
> A native speaker may correct me, but "which support" reads odd to me. Imo either
> "that support" or "support for which" (and then perhaps with a comma in place of
> the semicolon).
Maybe it can be reworded as

Xen had support for non-PAE PV guests with 4-bytes wide PTEs (if Xen was 
built in non-PAE mode) until Xen 4.0.
> > + *       Xen 4.0. As a result, in current Xen,, all PTE are now always 8-byte
> Nit: Double comma (when perhaps none is needed at all in that place).
>
> > + *       aligned which allows expanding sub-commands part (now 3-bits wide).
> Whether the part from "which" onwards is really relevant here I'm not quite 
> sure.
>
> Jan
Teddy

Attachment: OpenPGP_signature.asc
Description: OpenPGP digital signature