xen_domain_handle_t is defined as a opaque 16-bytes blob, but is
commonly used by toolstack and guest as a big-endian encoded and
formatted UUID (alike RFC 9562).

Clarify the definition of the type to ensure the guest and toolstack
interprets this value correctly in a way consistent with existing users
(at least with XAPI, xl, libvirt, hvmloader and Linux).

Fixes: 30ce2a9295a5 ("Store an opaque handle (tools uuid) in the domain structure")
Suggested-by: Andrew Cooper <andrew.cooper3@citrix.com>
Signed-off-by: Teddy Astie <teddy.astie@vates.tech>
---
v2:
 - introduced
---
 CHANGELOG.md             | 1 +
 xen/include/public/xen.h | 7 +++++++
 2 files changed, 8 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cd34ea87b8..8c4435c181 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
    - For x86, GCC 5.1 and Binutils 2.25, or Clang/LLVM 11
    - For ARM32 and ARM64, GCC 5.1 and Binutils 2.25
  - Linux based device model stubdomains are now fully supported.
+ - Clarify guest UUIDs as being big-endian encoded.
 
  - On x86:
    - Restrict the cache flushing done as a result of guest physical memory map
diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index 82b9c05a76..a219ef870f 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -973,6 +973,13 @@ typedef struct dom0_vga_console_info {
 #define xen_vga_console_info dom0_vga_console_info
 #define xen_vga_console_info_t dom0_vga_console_info_t
 
+/*
+ * The domain handle is chosen by the toolstack, and intended to hold a UUID
+ * conforming to RFC 9562 (i.e. big endian).
+ *
+ * Certain cases (e.g. SMBios) transform it to a Microsoft GUID (little
+ * endian) for presentation to the guest.
+ */
 typedef uint8_t xen_domain_handle_t[16];
 
 __DEFINE_XEN_GUEST_HANDLE(uint8,  uint8_t);
-- 
2.50.1



Teddy Astie | Vates XCP-ng Developer

XCP-ng & Xen Orchestra - Vates solutions

web: https://vates.tech

On 29.08.2025 11:58, Teddy Astie wrote:
> --- a/CHANGELOG.md
> +++ b/CHANGELOG.md
> @@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
>     - For x86, GCC 5.1 and Binutils 2.25, or Clang/LLVM 11
>     - For ARM32 and ARM64, GCC 5.1 and Binutils 2.25
>   - Linux based device model stubdomains are now fully supported.
> + - Clarify guest UUIDs as being big-endian encoded.

Is something like this really in need of having a ChangeLog entry?

Jan

> --- a/xen/include/public/xen.h
> +++ b/xen/include/public/xen.h
> @@ -973,6 +973,13 @@ typedef struct dom0_vga_console_info {
>  #define xen_vga_console_info dom0_vga_console_info
>  #define xen_vga_console_info_t dom0_vga_console_info_t
>  
> +/*
> + * The domain handle is chosen by the toolstack, and intended to hold a UUID
> + * conforming to RFC 9562 (i.e. big endian).
> + *
> + * Certain cases (e.g. SMBios) transform it to a Microsoft GUID (little
> + * endian) for presentation to the guest.
> + */
>  typedef uint8_t xen_domain_handle_t[16];
>  
>  __DEFINE_XEN_GUEST_HANDLE(uint8,  uint8_t);

On 9/1/25 5:55 PM, Jan Beulich wrote:
> On 29.08.2025 11:58, Teddy Astie wrote:
>> --- a/CHANGELOG.md
>> +++ b/CHANGELOG.md
>> @@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
>>      - For x86, GCC 5.1 and Binutils 2.25, or Clang/LLVM 11
>>      - For ARM32 and ARM64, GCC 5.1 and Binutils 2.25
>>    - Linux based device model stubdomains are now fully supported.
>> + - Clarify guest UUIDs as being big-endian encoded.
> Is something like this really in need of having a ChangeLog entry?

Perhaps, you are right and there is no a lot of sense to have such item in ChangeLog.

~ Oleksii

>> --- a/xen/include/public/xen.h
>> +++ b/xen/include/public/xen.h
>> @@ -973,6 +973,13 @@ typedef struct dom0_vga_console_info {
>>   #define xen_vga_console_info dom0_vga_console_info
>>   #define xen_vga_console_info_t dom0_vga_console_info_t
>>   
>> +/*
>> + * The domain handle is chosen by the toolstack, and intended to hold a UUID
>> + * conforming to RFC 9562 (i.e. big endian).
>> + *
>> + * Certain cases (e.g. SMBios) transform it to a Microsoft GUID (little
>> + * endian) for presentation to the guest.
>> + */
>>   typedef uint8_t xen_domain_handle_t[16];
>>   
>>   __DEFINE_XEN_GUEST_HANDLE(uint8,  uint8_t);

On 8/29/25 11:58 AM, Teddy Astie wrote:
> xen_domain_handle_t is defined as a opaque 16-bytes blob, but is
> commonly used by toolstack and guest as a big-endian encoded and
> formatted UUID (alike RFC 9562).
>
> Clarify the definition of the type to ensure the guest and toolstack
> interprets this value correctly in a way consistent with existing users
> (at least with XAPI, xl, libvirt, hvmloader and Linux).
>
> Fixes: 30ce2a9295a5 ("Store an opaque handle (tools uuid) in the domain structure")
> Suggested-by: Andrew Cooper<andrew.cooper3@citrix.com>
> Signed-off-by: Teddy Astie<teddy.astie@vates.tech>

LGTM: Acked-by: Oleksii Kurochko<oleksii.kurochko@gmail.com>

Thanks.

~ Oleksii

> ---
> v2:
>   - introduced
> ---
>   CHANGELOG.md             | 1 +
>   xen/include/public/xen.h | 7 +++++++
>   2 files changed, 8 insertions(+)
>
> diff --git a/CHANGELOG.md b/CHANGELOG.md
> index cd34ea87b8..8c4435c181 100644
> --- a/CHANGELOG.md
> +++ b/CHANGELOG.md
> @@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
>      - For x86, GCC 5.1 and Binutils 2.25, or Clang/LLVM 11
>      - For ARM32 and ARM64, GCC 5.1 and Binutils 2.25
>    - Linux based device model stubdomains are now fully supported.
> + - Clarify guest UUIDs as being big-endian encoded.
>   
>    - On x86:
>      - Restrict the cache flushing done as a result of guest physical memory map
> diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
> index 82b9c05a76..a219ef870f 100644
> --- a/xen/include/public/xen.h
> +++ b/xen/include/public/xen.h
> @@ -973,6 +973,13 @@ typedef struct dom0_vga_console_info {
>   #define xen_vga_console_info dom0_vga_console_info
>   #define xen_vga_console_info_t dom0_vga_console_info_t
>   
> +/*
> + * The domain handle is chosen by the toolstack, and intended to hold a UUID
> + * conforming to RFC 9562 (i.e. big endian).
> + *
> + * Certain cases (e.g. SMBios) transform it to a Microsoft GUID (little
> + * endian) for presentation to the guest.
> + */
>   typedef uint8_t xen_domain_handle_t[16];
>   
>   __DEFINE_XEN_GUEST_HANDLE(uint8,  uint8_t);