Merge branch '2023-08-26-bootstd-chromeos-impreovements-and-move-to-gcc-13.2' into next

First, update CI to using gcc-13.2 from 13.1, and rebuild the CI
containers.  This is needed because the second part adds utilities for
tests and provides, to quote the author:

This updates the ChromiumOS bootmeth to detect multiple kernel
partitions on a disk.

It also includes minor code improvements to the partition drivers,
including accessors for the optional fields.

This series also includes some other related tweaks in testing.

5 files changed, 270 insertions, 72 deletions

diff --git a/include/bootmeth.h b/include/bootmeth.h
index d3d8d608cd7..0fc36104ece 100644
--- a/include/bootmeth.h
+++ b/include/bootmeth.h
@@ -16,9 +16,12 @@ struct udevice;
  * enum bootmeth_flags - Flags for bootmeths
  *
  * @BOOTMETHF_GLOBAL: bootmeth handles bootdev selection automatically
+ * @BOOTMETHF_ANY_PART: bootmeth is willing to check any partition, even if it
+ * has no filesystem
  */
 enum bootmeth_flags {
 	BOOTMETHF_GLOBAL	= BIT(0),
+	BOOTMETHF_ANY_PART	= BIT(1),
 };
 
 /**
diff --git a/include/os.h b/include/os.h
index 968412b0a82..fc8a1b15cbf 100644
--- a/include/os.h
+++ b/include/os.h
@@ -98,6 +98,16 @@ int os_close(int fd);
  */
 int os_unlink(const char *pathname);
 
+/** os_persistent_fname() - Find the path to a test file
+ *
+ * @buf: Buffer to hold path
+ * @maxsize: Maximum size of buffer
+ * @fname: Leaf filename to find
+ * Returns: 0 on success, -ENOENT if file is not found, -ENOSPC if the buffer is
+ * too small
+ */
+int os_persistent_file(char *buf, int maxsize, const char *fname);
+
 /**
  * os_exit() - access to the OS exit() system call
  *
diff --git a/include/part.h b/include/part.h
index be144768777..f321479a5e9 100644
--- a/include/part.h
+++ b/include/part.h
@@ -80,6 +80,73 @@ struct disk_partition {
 #endif
 };
 
+/* Accessors for struct disk_partition field ->uuid */
+extern char *__invalid_use_of_disk_partition_uuid;
+
+static inline const char *disk_partition_uuid(const struct disk_partition *info)
+{
+#if CONFIG_IS_ENABLED(PARTITION_UUIDS)
+	return info->uuid;
+#else
+	return __invalid_use_of_disk_partition_uuid;
+#endif
+}
+
+static inline void disk_partition_set_uuid(struct disk_partition *info,
+					   const char *val)
+{
+#if CONFIG_IS_ENABLED(PARTITION_UUIDS)
+	strlcpy(info->uuid, val, UUID_STR_LEN + 1);
+#endif
+}
+
+static inline void disk_partition_clr_uuid(struct disk_partition *info)
+{
+#if CONFIG_IS_ENABLED(PARTITION_UUIDS)
+	*info->uuid = '\0';
+#endif
+}
+
+/* Accessors for struct disk_partition field ->type_guid */
+extern char *__invalid_use_of_disk_partition_type_uuid;
+
+static inline const
+char *disk_partition_type_uuid(const struct disk_partition *info)
+{
+#ifdef CONFIG_PARTITION_TYPE_GUID
+	return info->type_guid;
+#else
+	return __invalid_use_of_disk_partition_type_uuid;
+#endif
+}
+
+static inline void disk_partition_set_type_guid(struct disk_partition *info,
+						const char *val)
+{
+#ifdef CONFIG_PARTITION_TYPE_GUID
+	strlcpy(info->type_guid, val, UUID_STR_LEN + 1);
+#endif
+}
+
+static inline void disk_partition_clr_type_guid(struct disk_partition *info)
+{
+#ifdef CONFIG_PARTITION_TYPE_GUID
+	*info->type_guid = '\0';
+#endif
+}
+
+/* Accessors for struct disk_partition field ->sys_ind */
+extern int __invalid_use_of_disk_partition_sys_ind;
+
+static inline uint disk_partition_sys_ind(const struct disk_partition *info)
+{
+#ifdef CONFIG_DOS_PARTITION
+	return info->sys_ind;
+#else
+	return __invalid_use_of_disk_partition_sys_ind;
+#endif
+}
+
 struct disk_part {
 	int partnum;
 	struct disk_partition gpt_part_info;
@@ -113,7 +180,7 @@ struct blk_desc *mg_disk_get_dev(int dev);
  * contained with the interface's data structure. There is no global
  * numbering for block devices, so the interface name must be provided.
  *
- * @dev_desc:	Block device descriptor
+ * @desc:	Block device descriptor
  * @part:	Partition number to read
  * @part_type:	Partition driver to use, or PART_TYPE_UNKNOWN to automatically
  *		choose a driver
@@ -121,24 +188,24 @@ struct blk_desc *mg_disk_get_dev(int dev);
  *
  * Return: 0 on success, negative errno on failure
  */
-int part_get_info_by_type(struct blk_desc *dev_desc, int part, int part_type,
+int part_get_info_by_type(struct blk_desc *desc, int part, int part_type,
 			  struct disk_partition *info);
-int part_get_info(struct blk_desc *dev_desc, int part,
+int part_get_info(struct blk_desc *desc, int part,
 		  struct disk_partition *info);
 /**
  * part_get_info_whole_disk() - get partition info for the special case of
  * a partition occupying the entire disk.
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @info:	returned partition information
  * Return:	0 on success
  */
-int part_get_info_whole_disk(struct blk_desc *dev_desc,
+int part_get_info_whole_disk(struct blk_desc *desc,
 			     struct disk_partition *info);
 
-void part_print(struct blk_desc *dev_desc);
-void part_init(struct blk_desc *dev_desc);
-void dev_print(struct blk_desc *dev_desc);
+void part_print(struct blk_desc *desc);
+void part_init(struct blk_desc *desc);
+void dev_print(struct blk_desc *desc);
 
 /**
  * blk_get_device_by_str() - Get a block device given its interface/hw partition
@@ -162,11 +229,11 @@ void dev_print(struct blk_desc *dev_desc);
  *		containing the device number (e.g. "2") or the device number
  *		and hardware partition number (e.g. "2.4") for devices that
  *		support it (currently only MMC).
- * @dev_desc:	Returns a pointer to the block device on success
+ * @desc:	Returns a pointer to the block device on success
  * Return: block device number (local to the interface), or -1 on error
  */
 int blk_get_device_by_str(const char *ifname, const char *dev_str,
-			  struct blk_desc **dev_desc);
+			  struct blk_desc **desc);
 
 /**
  * blk_get_device_part_str() - Get a block device and partition
@@ -196,7 +263,7 @@ int blk_get_device_by_str(const char *ifname, const char *dev_str,
  *
  * @ifname:		Interface name (e.g. "ide", "scsi")
  * @dev_part_str:	Device and partition string
- * @dev_desc:		Returns a pointer to the block device on success
+ * @desc:		Returns a pointer to the block device on success
  * @info:		Returns partition information
  * @allow_whole_dev:	true to allow the user to select partition 0
  *			(which means the whole device), false to require a valid
@@ -205,22 +272,22 @@ int blk_get_device_by_str(const char *ifname, const char *dev_str,
  *
  */
 int blk_get_device_part_str(const char *ifname, const char *dev_part_str,
-			    struct blk_desc **dev_desc,
+			    struct blk_desc **desc,
 			    struct disk_partition *info, int allow_whole_dev);
 
 /**
  * part_get_info_by_name() - Search for a partition by name
  *                           among all available registered partitions
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @name:	the specified table entry name
  * @info:	returns the disk partition info
  *
  * Return: the partition number on match (starting on 1), -1 on no match,
  * otherwise error
  */
-int part_get_info_by_name(struct blk_desc *dev_desc,
-			      const char *name, struct disk_partition *info);
+int part_get_info_by_name(struct blk_desc *desc, const char *name,
+			  struct disk_partition *info);
 
 /**
  * part_get_info_by_dev_and_name_or_num() - Get partition info from dev number
@@ -232,11 +299,11 @@ int part_get_info_by_name(struct blk_desc *dev_desc,
  * (like "device_num#partition_name") or a device number plus a partition number
  * separated by a ":". For example both "0#misc" and "0:1" can be valid
  * partition descriptions for a given interface. If the partition is found, sets
- * dev_desc and part_info accordingly with the information of the partition.
+ * desc and part_info accordingly with the information of the partition.
  *
  * @dev_iface:		Device interface
  * @dev_part_str:	Input partition description, like "0#misc" or "0:1"
- * @dev_desc:		Place to store the device description pointer
+ * @desc:		Place to store the device description pointer
  * @part_info:		Place to store the partition information
  * @allow_whole_dev:	true to allow the user to select partition 0
  *			(which means the whole device), false to require a valid
@@ -245,7 +312,7 @@ int part_get_info_by_name(struct blk_desc *dev_desc,
  */
 int part_get_info_by_dev_and_name_or_num(const char *dev_iface,
 					 const char *dev_part_str,
-					 struct blk_desc **dev_desc,
+					 struct blk_desc **desc,
 					 struct disk_partition *part_info,
 					 int allow_whole_dev);
 
@@ -256,12 +323,12 @@ int part_get_info_by_dev_and_name_or_num(const char *dev_iface,
  * (DOS, ISO). Generates partition name out of the device type and partition
  * number.
  *
- * @dev_desc:	pointer to the block device
+ * @desc:	pointer to the block device
  * @part_num:	partition number for which the name is generated
  * @name:	buffer where the name is written
  */
-void part_set_generic_name(const struct blk_desc *dev_desc,
-	int part_num, char *name);
+void part_set_generic_name(const struct blk_desc *desc, int part_num,
+			   char *name);
 
 extern const struct block_drvr block_drvr[];
 #else
@@ -269,26 +336,25 @@ static inline struct blk_desc *blk_get_dev(const char *ifname, int dev)
 { return NULL; }
 static inline struct blk_desc *mg_disk_get_dev(int dev) { return NULL; }
 
-static inline int part_get_info(struct blk_desc *dev_desc, int part,
+static inline int part_get_info(struct blk_desc *desc, int part,
 				struct disk_partition *info) { return -1; }
-static inline int part_get_info_whole_disk(struct blk_desc *dev_desc,
+static inline int part_get_info_whole_disk(struct blk_desc *desc,
 					   struct disk_partition *info)
 { return -1; }
-static inline void part_print(struct blk_desc *dev_desc) {}
-static inline void part_init(struct blk_desc *dev_desc) {}
-static inline void dev_print(struct blk_desc *dev_desc) {}
+static inline void part_print(struct blk_desc *desc) {}
+static inline void part_init(struct blk_desc *desc) {}
+static inline void dev_print(struct blk_desc *desc) {}
 static inline int blk_get_device_by_str(const char *ifname, const char *dev_str,
-					struct blk_desc **dev_desc)
+					struct blk_desc **desc)
 { return -1; }
 static inline int blk_get_device_part_str(const char *ifname,
 					  const char *dev_part_str,
-					  struct blk_desc **dev_desc,
+					  struct blk_desc **desc,
 					  struct disk_partition *info,
 					  int allow_whole_dev)
-{ *dev_desc = NULL; return -1; }
+{ *desc = NULL; return -1; }
 
-static inline int part_get_info_by_name(struct blk_desc *dev_desc,
-					const char *name,
+static inline int part_get_info_by_name(struct blk_desc *desc, const char *name,
 					struct disk_partition *info)
 {
 	return -ENOENT;
@@ -297,23 +363,15 @@ static inline int part_get_info_by_name(struct blk_desc *dev_desc,
 static inline int
 part_get_info_by_dev_and_name_or_num(const char *dev_iface,
 				     const char *dev_part_str,
-				     struct blk_desc **dev_desc,
+				     struct blk_desc **desc,
 				     struct disk_partition *part_info,
 				     int allow_whole_dev)
 {
-	*dev_desc = NULL;
+	*desc = NULL;
 	return -ENOSYS;
 }
 #endif
 
-/**
- * part_get_bootable() - Find the first bootable partition
- *
- * @desc: Block-device descriptor
- * @return first bootable partition, or 0 if there is none
- */
-int part_get_bootable(struct blk_desc *desc);
-
 struct udevice;
 /**
  * disk_blk_read() - read blocks from a disk partition
@@ -382,29 +440,29 @@ struct part_driver {
 	/**
 	 * @get_info:		Get information about a partition
 	 *
-	 * @get_info.dev_desc:	Block device descriptor
+	 * @get_info.desc:	Block device descriptor
 	 * @get_info.part:	Partition number (1 = first)
 	 * @get_info.info:	Returns partition information
 	 */
-	int (*get_info)(struct blk_desc *dev_desc, int part,
+	int (*get_info)(struct blk_desc *desc, int part,
 			struct disk_partition *info);
 
 	/**
 	 * @print:		Print partition information
 	 *
-	 * @print.dev_desc:	Block device descriptor
+	 * @print.desc:	Block device descriptor
 	 */
-	void (*print)(struct blk_desc *dev_desc);
+	void (*print)(struct blk_desc *desc);
 
 	/**
 	 * @test:		Test if a device contains this partition type
 	 *
-	 * @test.dev_desc:	Block device descriptor
+	 * @test.desc:		Block device descriptor
 	 * @test.Return:
 	 * 0 if the block device appears to contain this partition type,
 	 * -ve if not
 	 */
-	int (*test)(struct blk_desc *dev_desc);
+	int (*test)(struct blk_desc *desc);
 };
 
 /* Declare a new U-Boot partition 'driver' */
@@ -418,19 +476,18 @@ struct part_driver {
 /**
  * write_gpt_table() - Write the GUID Partition Table to disk
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @gpt_h:	pointer to GPT header representation
  * @gpt_e:	pointer to GPT partition table entries
  *
  * Return:	zero on success, otherwise error
  */
-int write_gpt_table(struct blk_desc *dev_desc,
-		  gpt_header *gpt_h, gpt_entry *gpt_e);
+int write_gpt_table(struct blk_desc *desc, gpt_header *gpt_h, gpt_entry *gpt_e);
 
 /**
  * gpt_fill_pte() - Fill the GPT partition table entry
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @gpt_h:	GPT header representation
  * @gpt_e:	GPT partition table entries
  * @partitions:	list of partitions
@@ -438,55 +495,54 @@ int write_gpt_table(struct blk_desc *dev_desc,
  *
  * Return:	zero on success
  */
-int gpt_fill_pte(struct blk_desc *dev_desc,
-		 gpt_header *gpt_h, gpt_entry *gpt_e,
+int gpt_fill_pte(struct blk_desc *desc, gpt_header *gpt_h, gpt_entry *gpt_e,
 		 struct disk_partition *partitions, int parts);
 
 /**
  * gpt_fill_header() - Fill the GPT header
  *
- * @dev_desc:		block device descriptor
+ * @desc:		block device descriptor
  * @gpt_h:		GPT header representation
  * @str_guid:		disk guid string representation
  * @parts_count:	number of partitions
  *
  * Return:		error on str_guid conversion error
  */
-int gpt_fill_header(struct blk_desc *dev_desc, gpt_header *gpt_h,
-		char *str_guid, int parts_count);
+int gpt_fill_header(struct blk_desc *desc, gpt_header *gpt_h, char *str_guid,
+		    int parts_count);
 
 /**
  * gpt_restore() - Restore GPT partition table
  *
- * @dev_desc:		block device descriptor
+ * @desc:		block device descriptor
  * @str_disk_guid:	disk GUID
  * @partitions:		list of partitions
  * @parts_count:	number of partitions
  *
  * Return:		0 on success
  */
-int gpt_restore(struct blk_desc *dev_desc, char *str_disk_guid,
+int gpt_restore(struct blk_desc *desc, char *str_disk_guid,
 		struct disk_partition *partitions, const int parts_count);
 
 /**
  * is_valid_gpt_buf() - Ensure that the Primary GPT information is valid
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @buf:	buffer which contains the MBR and Primary GPT info
  *
  * Return:	0 on success, otherwise error
  */
-int is_valid_gpt_buf(struct blk_desc *dev_desc, void *buf);
+int is_valid_gpt_buf(struct blk_desc *desc, void *buf);
 
 /**
  * write_mbr_and_gpt_partitions() - write MBR, Primary GPT and Backup GPT
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @buf:	buffer which contains the MBR and Primary GPT info
  *
  * Return:	0 on success, otherwise error
  */
-int write_mbr_and_gpt_partitions(struct blk_desc *dev_desc, void *buf);
+int write_mbr_and_gpt_partitions(struct blk_desc *desc, void *buf);
 
 /**
  * gpt_verify_headers() - Read and check CRC32 of the GPT's header
@@ -494,24 +550,24 @@ int write_mbr_and_gpt_partitions(struct blk_desc *dev_desc, void *buf);
  *
  * As a side effect if sets gpt_head and gpt_pte so they point to GPT data.
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @gpt_head:	pointer to GPT header data read from medium
  * @gpt_pte:	pointer to GPT partition table enties read from medium
  *
  * Return:	0 on success, otherwise error
  */
-int gpt_verify_headers(struct blk_desc *dev_desc, gpt_header *gpt_head,
+int gpt_verify_headers(struct blk_desc *desc, gpt_header *gpt_head,
 		       gpt_entry **gpt_pte);
 
 /**
  * gpt_repair_headers() - Function to repair the GPT's header
  *                        and partition table entries (PTE)
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  *
  * Return:	0 on success, otherwise error
  */
-int gpt_repair_headers(struct blk_desc *dev_desc);
+int gpt_repair_headers(struct blk_desc *desc);
 
 /**
  * gpt_verify_partitions() - Function to check if partitions' name, start and
@@ -521,7 +577,7 @@ int gpt_repair_headers(struct blk_desc *dev_desc);
  * provided in '$partitions' environment variable. Specificially, name, start
  * and size of the partition is checked.
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @partitions:	partition data read from '$partitions' env variable
  * @parts:	number of partitions read from '$partitions' env variable
  * @gpt_head:	pointer to GPT header data read from medium
@@ -529,7 +585,7 @@ int gpt_repair_headers(struct blk_desc *dev_desc);
  *
  * Return:	0 on success, otherwise error
  */
-int gpt_verify_partitions(struct blk_desc *dev_desc,
+int gpt_verify_partitions(struct blk_desc *desc,
 			  struct disk_partition *partitions, int parts,
 			  gpt_header *gpt_head, gpt_entry **gpt_pte);
 
@@ -540,12 +596,12 @@ int gpt_verify_partitions(struct blk_desc *dev_desc,
  * This function reads the GUID string from a block device whose descriptor
  * is provided.
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @guid:	pre-allocated string in which to return the GUID
  *
  * Return:	0 on success, otherwise error
  */
-int get_disk_guid(struct blk_desc *dev_desc, char *guid);
+int get_disk_guid(struct blk_desc *desc, char *guid);
 
 #endif
 
@@ -562,12 +618,12 @@ int is_valid_dos_buf(void *buf);
 /**
  * write_mbr_sector() - write DOS MBR
  *
- * @dev_desc:	block device descriptor
+ * @desc:	block device descriptor
  * @buf:	buffer which contains the MBR
  *
  * Return:	0 on success, otherwise error
  */
-int write_mbr_sector(struct blk_desc *dev_desc, void *buf);
+int write_mbr_sector(struct blk_desc *desc, void *buf);
 
 int write_mbr_partitions(struct blk_desc *dev,
 		struct disk_partition *p, int count, unsigned int disksig);
@@ -606,12 +662,24 @@ static inline struct part_driver *part_driver_get_first(void)
  */
 int part_get_type_by_name(const char *name);
 
+/**
+ * part_get_bootable() - Find the first bootable partition
+ *
+ * @desc: Block-device descriptor
+ * @return first bootable partition, or 0 if there is none
+ */
+int part_get_bootable(struct blk_desc *desc);
+
 #else
 static inline int part_driver_get_count(void)
 { return 0; }
 
 static inline struct part_driver *part_driver_get_first(void)
 { return NULL; }
+
+static inline bool part_get_bootable(struct blk_desc *desc)
+{ return false; }
+
 #endif /* CONFIG_PARTITIONS */
 
 #endif /* _PART_H */
diff --git a/include/part_efi.h b/include/part_efi.h
index c68529b4daf..59b7895b8a2 100644
--- a/include/part_efi.h
+++ b/include/part_efi.h
@@ -60,6 +60,20 @@
 	EFI_GUID( 0x3de21764, 0x95bd, 0x54bd, \
 		0xa5, 0xc3, 0x4a, 0xbe, 0x78, 0x6f, 0x38, 0xa8)
 
+/* Special ChromiumOS things */
+#define PARTITION_CROS_KERNEL \
+	EFI_GUID(0xfe3a2a5d, 0x4f32, 0x41a7, \
+		 0xb7, 0x25, 0xac, 0xcc, 0x32, 0x85, 0xa3, 0x09)
+#define PARTITION_CROS_ROOT \
+	EFI_GUID(0x3cb8e202, 0x3b7e, 0x47dd, \
+		 0x8a, 0x3c, 0x7f, 0xf2, 0xa1, 0x3c, 0xfc, 0xec)
+#define PARTITION_CROS_FIRMWARE \
+	EFI_GUID(0xcab6e88e, 0xabf3, 0x4102, \
+		 0xa0, 0x7a, 0xd4, 0xbb, 0x9b, 0xe3, 0xc1, 0xd3)
+#define PARTITION_CROS_RESERVED \
+	EFI_GUID(0x2e0a753d, 0x9e48, 0x43b0, \
+		 0x83, 0x37, 0xb1, 0x51, 0x92, 0xcb, 0x1b, 0x5e)
+
 /* linux/include/efi.h */
 typedef u16 efi_char16_t;
 
diff --git a/include/uuid.h b/include/uuid.h
index 89b93e642b7..f5a941250f4 100644
--- a/include/uuid.h
+++ b/include/uuid.h
@@ -12,6 +12,51 @@
 
 #include <linux/bitops.h>
 
+/*
+ * UUID - Universally Unique IDentifier - 128 bits unique number.
+ *        There are 5 versions and one variant of UUID defined by RFC4122
+ *        specification. A UUID contains a set of fields. The set varies
+ *        depending on the version of the UUID, as shown below:
+ *        - time, MAC address(v1),
+ *        - user ID(v2),
+ *        - MD5 of name or URL(v3),
+ *        - random data(v4),
+ *        - SHA-1 of name or URL(v5),
+ *
+ * Layout of UUID:
+ * timestamp - 60-bit: time_low, time_mid, time_hi_and_version
+ * version   - 4 bit (bit 4 through 7 of the time_hi_and_version)
+ * clock seq - 14 bit: clock_seq_hi_and_reserved, clock_seq_low
+ * variant:  - bit 6 and 7 of clock_seq_hi_and_reserved
+ * node      - 48 bit
+ *
+ * source: https://www.ietf.org/rfc/rfc4122.txt
+ *
+ * UUID binary format (16 bytes):
+ *
+ * 4B-2B-2B-2B-6B (big endian - network byte order)
+ *
+ * UUID string is 36 length of characters (36 bytes):
+ *
+ * 0        9    14   19   24
+ * xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ *    be     be   be   be       be
+ *
+ * where x is a hexadecimal character. Fields are separated by '-'s.
+ * When converting to a binary UUID, le means the field should be converted
+ * to little endian and be means it should be converted to big endian.
+ *
+ * UUID is also used as GUID (Globally Unique Identifier) with the same binary
+ * format but it differs in string format like below.
+ *
+ * GUID:
+ * 0        9    14   19   24
+ * xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ *    le     le   le   be       be
+ *
+ * GUID is used e.g. in GPT (GUID Partition Table) as a partiions unique id.
+ */
+
 /* This is structure is in big-endian */
 struct uuid {
 	unsigned int time_low;
@@ -40,20 +85,78 @@ struct uuid {
 #define UUID_VARIANT		0x1
 
 int uuid_str_valid(const char *uuid);
+
+/*
+ * uuid_str_to_bin() - convert string UUID or GUID to big endian binary data.
+ *
+ * @param uuid_str - pointer to UUID or GUID string [37B] or GUID shorcut
+ * @param uuid_bin - pointer to allocated array for big endian output [16B]
+ * @str_format     - UUID string format: 0 - UUID; 1 - GUID
+ * Return: 0 if OK, -EINVAL if the string is not a valid UUID
+ */
 int uuid_str_to_bin(const char *uuid_str, unsigned char *uuid_bin,
 		    int str_format);
+
+/*
+ * uuid_bin_to_str() - convert big endian binary data to string UUID or GUID.
+ *
+ * @param uuid_bin:	pointer to binary data of UUID (big endian) [16B]
+ * @param uuid_str:	pointer to allocated array for output string [37B]
+ * @str_format:		bit 0: 0 - UUID; 1 - GUID
+ *			bit 1: 0 - lower case; 2 - upper case
+ */
 void uuid_bin_to_str(const unsigned char *uuid_bin, char *uuid_str,
 		     int str_format);
+
+/*
+ * uuid_guid_get_bin() - this function get GUID bin for string
+ *
+ * @param guid_str - pointer to partition type string
+ * @param guid_bin - pointer to allocated array for big endian output [16B]
+ */
 int uuid_guid_get_bin(const char *guid_str, unsigned char *guid_bin);
+
+/*
+ * uuid_guid_get_str() - this function get string for GUID.
+ *
+ * @param guid_bin - pointer to string with partition type guid [16B]
+ *
+ * Returns NULL if the type GUID is not known.
+ */
 const char *uuid_guid_get_str(const unsigned char *guid_bin);
+
+/*
+ * gen_rand_uuid() - this function generates a random binary UUID version 4.
+ *                   In this version all fields beside 4 bits of version and
+ *                   2 bits of variant are randomly generated.
+ *
+ * @param uuid_bin - pointer to allocated array [16B]. Output is in big endian.
+ */
 void gen_rand_uuid(unsigned char *uuid_bin);
+
+/*
+ * gen_rand_uuid_str() - this function generates UUID v4 (random) in two string
+ *                       formats UUID or GUID.
+ *
+ * @param uuid_str - pointer to allocated array [37B].
+ * @param          - uuid output type: UUID - 0, GUID - 1
+ */
 void gen_rand_uuid_str(char *uuid_str, int str_format);
 
 /**
  * uuid_str_to_le_bin() - Convert string UUID to little endian binary data.
  * @uuid_str:	pointer to UUID string
  * @uuid_bin:	pointer to allocated array for little endian output [16B]
+ *
+ * UUID string is 36 characters (36 bytes):
+ *
+ * xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ *
+ * where x is a hexadecimal character. Fields are separated by '-'s.
+ * When converting to a little endian binary UUID, the string fields are reversed.
+ *
  * Return:
+ *
  *    uuid_bin filled with little endian UUID data
  *    On success 0 is returned. Otherwise, failure code.
  */