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

[Jan Beulich <jbeulich@xxxxxxxx>]

On 07.09.2026 15:56, Teddy Astie wrote:
> 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 ?

Along these lines, yes.

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

That'll be fine with me. Preferably "32-bit" instead of "4-bytes wide", though.

Jan