sd-id128: document everywhere that we treat all UUIDs as Variant 1

So in theory UUID Variant 2 (i.e. microsoft GUIDs) are supposed to be
displayed in native endian. That is of course a bad idea, and Linux
userspace generally didn't implement that, i.e. uuidd and similar.
Hence, let's not bother either, but let's document that we treat
everything the same as Variant 1, even if it declares something else.

man/machine-id.xml

@@ -147,15 +147,13 @@
   <refsect1>
     <title>Relation to OSF UUIDs</title>
 
-    <para>Note that the machine ID historically is not an OSF UUID as
-    defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
-    4122</ulink>, nor a Microsoft GUID; however, starting with systemd
-    v30, newly generated machine IDs do qualify as v4 UUIDs.</para>
+    <para>Note that the machine ID historically is not an OSF UUID as defined by <ulink
+    url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink>, nor a Microsoft GUID; however, starting with
+    systemd v30, newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
 
-    <para>In order to maintain compatibility with existing
-    installations, an application requiring a UUID should decode the
-    machine ID, and then apply the following operations to turn it
-    into a valid OSF v4 UUID. With <literal>id</literal> being an
+    <para>In order to maintain compatibility with existing installations, an application requiring a strictly
+    RFC 4122 compliant UUID should decode the machine ID, and then (non-reversibly) apply the following
+    operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID. With <literal>id</literal> being an
     unsigned character array:</para>
 
     <programlisting>/* Set UUID version to 4 --- truly random generation */

man/sd-id128.xml

@@ -50,13 +50,11 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>sd-id128.h</filename> provides APIs to process and
-    generate 128-bit ID values. The 128-bit ID values processed and
-    generated by these APIs are a generalization of OSF UUIDs as
-    defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
-    4122</ulink> but use a simpler string format. These functions
-    impose no structure on the used IDs, much unlike OSF UUIDs or
-    Microsoft GUIDs, but are fully compatible with those types of IDs.
+    <para><filename>sd-id128.h</filename> provides APIs to process and generate 128-bit ID values. The
+    128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined by
+    <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> but use a simpler string format. These
+    functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
+    compatible with those types of IDs.
     </para>
 
     <para>See
@@ -101,8 +99,7 @@
 
 int main(int argc, char **argv) {
   puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
-}
-    </programlisting>
+}</programlisting>
 
     <para><function>SD_ID128_CONST_STR()</function> may be used to
     convert constant 128-bit IDs into constant strings for output. The
@@ -125,9 +122,13 @@ int main(int argc, char **argv) {
 }</programlisting>
 
     <para><constant>SD_ID128_UUID_FORMAT_STR</constant> is similar to
-    <constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the
-    "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
-    </para>
+    <constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the "<ulink
+    url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical
+    representation</ulink>". This formats the string based on <ulink
+    url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, i.e. converting from Big
+    Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
+    best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All 128-bit IDs
+    generated by the sd-id128 APIs strictly conform to Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
 
     <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para>
 

man/sd_id128_get_machine.xml

@@ -101,10 +101,10 @@
 
     <para>Note that <function>sd_id128_get_machine_app_specific()</function>,
     <function>sd_id128_get_boot()</function>, <function>sd_id128_get_boot_app_specific()</function>, and
-    <function>sd_id128_get_invocation()</function> always return UUID v4 compatible IDs.
-    <function>sd_id128_get_machine()</function> will also return a UUID v4-compatible ID on new installations
-    but might not on older. It is possible to convert the machine ID into a UUID v4-compatible one. For more
-    information, see
+    <function>sd_id128_get_invocation()</function> always return UUID Variant 1 Version 4 compatible IDs.
+    <function>sd_id128_get_machine()</function> will also return a UUID Variant 1 Version 4 compatible ID on
+    new installations but might not on older. It is possible to convert the machine ID non-reversibly into a
+    UUID Variant 1 Version 4 compatible one. For more information, see
     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It is
     hence guaranteed that these functions will never return the ID consisting of all zero or all one bits
     (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>) — with the possible exception of

man/sd_id128_randomize.xml

@@ -42,9 +42,9 @@
     <filename>/dev/urandom</filename> kernel random number
     generator.</para>
 
-    <para>Note that <function>sd_id128_randomize()</function> always returns a UUID v4-compatible ID. It is
-    hence guaranteed that this function will never return the ID consisting of all zero or all one bits
-    (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>).</para>
+    <para>Note that <function>sd_id128_randomize()</function> always returns a UUID Variant 1 Version 4
+    compatible ID. It is hence guaranteed that this function will never return the ID consisting of all zero
+    or all one bits (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>).</para>
 
     <para>For more information about the <literal>sd_id128_t</literal>
     type, see

man/sd_id128_to_string.xml

@@ -54,6 +54,11 @@
     <constant>NULL</constant> the function will validate the passed ID string, but not actually return it in parsed
     form.</para>
 
+    <para>Note that when parsing 37 character UUIDs this is done strictly in Big Endian byte order,
+    i.e. according to <ulink url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1
+    rules, even if the UUID encodes a different variant. This matches behaviour in various other Linux
+    userspace tools. It's probably wise to avoid UUIDs of other variant types.</para>
+
     <para>For more information about the <literal>sd_id128_t</literal>
     type see
     <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.

src/systemd/sd-id128.h

@@ -63,7 +63,9 @@ int sd_id128_get_boot_app_specific(sd_id128_t app_id, sd_id128_t *ret);
 #define SD_ID128_FORMAT_STR "%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x"
 #define SD_ID128_FORMAT_VAL(x) (x).bytes[0], (x).bytes[1], (x).bytes[2], (x).bytes[3], (x).bytes[4], (x).bytes[5], (x).bytes[6], (x).bytes[7], (x).bytes[8], (x).bytes[9], (x).bytes[10], (x).bytes[11], (x).bytes[12], (x).bytes[13], (x).bytes[14], (x).bytes[15]
 
-/* Like SD_ID128_FORMAT_STR, but formats as UUID, not in plain format */
+/* Like SD_ID128_FORMAT_STR, but formats as UUID, not in plain format (Strictly Big Endian byte order,
+ * i.e. treats everything as RFC4122 Variant 1 UUIDs, even if variant says otherwise, but matching other
+ * Linux userspace behaviour.) */
 #define SD_ID128_UUID_FORMAT_STR "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x"
 
 #define SD_ID128_CONST_STR(x)                                           \