Index: ossp-pkg/uuid/ChangeLog
RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/ChangeLog,v
rcsdiff -q -kk '-r1.113' '-r1.114' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/ChangeLog,v' 2>/dev/null
--- ChangeLog	2006/05/10 08:53:11	1.113
+++ ChangeLog	2006/05/10 09:07:33	1.114
@@ -13,6 +13,10 @@
 
   Changes between 1.4.2 and 1.4.3 (13-Mar-2006 to XX-May-2006)
 
+   o Added an "OVERVIEW" file which tries to give the "big picture"
+     about UUIDs and allows to survice during the nasty UUID bit fiddling.
+     [Ralf S. Engelschall]
+
    o Replaced "clock_seq_and_reserved" with
      "clock_seq_high_and_reserved" in uuid.pod to already reflect the
      description in the forthcoming RFC.
Index: ossp-pkg/uuid/OVERVIEW
RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/OVERVIEW,v
co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/uuid/Attic/OVERVIEW,v' | diff -u /dev/null - -L'ossp-pkg/uuid/OVERVIEW' 2>/dev/null
--- ossp-pkg/uuid/OVERVIEW
+++ -	2024-05-21 23:13:46.815415904 +0200
@@ -0,0 +1,81 @@
+
+   _        ___  ____ ____  ____                _     _
+  |_|_ _   / _ \/ ___/ ___||  _ \   _   _ _   _(_) __| |
+  _|_||_| | | | \___ \___ \| |_) | | | | | | | | |/ _` |
+ |_||_|_| | |_| |___) |__) |  __/  | |_| | |_| | | (_| |
+  |_|_|_|  \___/|____/____/|_|      \__,_|\__,_|_|\__,_|
+
+  OSSP uuid - Universally Unique Identifier
+
+  OVERVIEW
+
+  A UUID consists of 128 bits (16-octets) which are split into 6
+  octet-bounded unsigned integer fields ("time_low", "time_mid",
+  "time_hi_and_version", "clk_seq_hi_res", "clk_seq_low" and "node") and
+  where two fields are multiplexed with a fixed size 4-bit "version" and
+  a variable sized 2-3 bit "variant" field.
+
+  The UUID octets are counted from left to right 15 to 0 and the bits
+  in each octet are counted from left to right 7 to 0 (most significant
+  bit first, least significant bit last). The unsigned integer fields
+  formed out of multiple octets are stored in "network byte order" (most
+  significant octet first, least significant octet last). A UUID is
+  stored and transmitted from left to right, i.e., in "network byte
+  order" with the most significant octet first and the least significant
+  octet last.
+
+  Illustration 1:
+  (single octet array, less compact, more annotations)
+
+
+  Bits:                                                   [4]           [2-3]
+  Field:                                                version        variant
+        MSO                                           -->|  |<--      -->| |<--                                                        LSO
+           \                                             |  |            | |                                                          /
+  Octet:    15      14      13      12      11      10   |  |9       8   | | 7       6       5       4       3       2       1       0
+         +------++------++------++------++------++------++------++------++------++------++------++------++------++------++------++------+
+  UUID:  |      ||      ||      ||      ||      ||      |####   ||      |##:    ||      ||      ||      ||      ||      ||      ||      |
+         +------++------++------++------++------++------++------++------++------++------++------++------++------++------++------++------+
+  Bit:   76543210765432107654321076543210765432107654321076543210765432107654321076543210765432107654321076543210765432107654321076543210
+        /|                              ||              ||              ||      ||      ||                                              |\
+     MSB |                              ||              ||              ||      ||      ||                                              | LSB
+         |<---------------------------->||<------------>||<------------>||<---->||<---->||<-------------------------------------------->|
+                                                           time_hi        clk_seq clk_seq
+  Field:           time_low                  time_mid      _and_version   _hi_res _low                         node
+  Bits:              [32]                      [16]           [16]        [5-6]     [8]                        [48]
+
+
+  Illustration 2:
+  (two octet arrays, more compact, less annotations)
+
+                                                        [4]
+                                                      version
+                                                    -->|  |<--
+                                                       |  |
+                                                       |  |  [16]
+                   [32]                      [16]      |  |time_hi
+                 time_low                  time_mid    | _and_version
+       |<---------------------------->||<------------>||<------------>|
+       |    MSO                       ||              ||  |           |
+       |   /                          ||              ||  |           |
+       |  15      14      13      12  ||  11      10  ||  |9       8  |
+       7654321076543210765432107654321076543210765432107654321076543210
+      /+------++------++------++------++------++------++------++------+~
+   MSB |      ||      ||      ||      ||      ||      |####   ||      |  ...
+       +------++------++------++------++------++------++------++------+~
+      ~+------++------++------++------++------++------++------++------+
+  ...  ##:    ||      ||      ||      ||      ||      ||      ||      | LSB
+      ~+------++------++------++------++------++------++------++------+/
+       7654321076543210765432107654321076543210765432107654321076543210
+       | | 7  ||   6  ||   5       4       3       2       1       0  |
+       | |    ||      ||                                          /   |
+       | |    ||      ||                                        LSO   |
+       |<---->||<---->||<-------------------------------------------->|
+       |clk_seq clk_seq                      node
+       |_hi_res _low                         [48]
+       |[5-6]    [8]
+       | |
+    -->| |<--
+     variant
+      [2-3]
+