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

[Jan Beulich <jbeulich@xxxxxxxx>]

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?

> 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).

> + *       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