Merge tag 'efi-2025-01-rc2' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request efi-2025-01-rc2

Documentation:

* include semihosting and K3 boards only once in table of contents
* include file-system API into HTML docs
* describe struct ext2_inode
* update Python requirements

UEFI:

* mark local functions static
* simplify efi_free_pages()
* pass correct end address value to  efi_dp_from_mem()
* fix typos in HII test and eficonfig command

2 files changed, 71 insertions, 28 deletions

diff --git a/include/ext_common.h b/include/ext_common.h
index b09bbde116a..6e17fbd2771 100644
--- a/include/ext_common.h
+++ b/include/ext_common.h
@@ -173,20 +173,38 @@ struct ext2_block_group {
 	__le32 bg_reserved;
 };
 
-/* The ext2 inode. */
+/**
+ * struct ext2_inode - ext2 inode
+ *
+ * For details see Linux file
+ * Documentation/filesystems/ext4/inodes.rst.
+ */
 struct ext2_inode {
+	/** @mode: file mode */
 	__le16 mode;
+	/** @uid: lower 16 bits of owner UID */
 	__le16 uid;
+	/** @size: lower 32 bits of file size */
 	__le32 size;
+	/** @atime: last access time */
 	__le32 atime;
+	/** @ctime: last change time */
 	__le32 ctime;
+	/** @mtime: last modification time */
 	__le32 mtime;
+	/** @dtime: deletion time */
 	__le32 dtime;
+	/** @gid: lower 16 bits of group ID */
 	__le16 gid;
+	/** @nlinks: number of hard links */
 	__le16 nlinks;
-	__le32 blockcnt;	/* Blocks of either 512 or block_size bytes */
+	/** @blockcnt: lower 32 bit of block count */
+	__le32 blockcnt;
+	/** @flags: inode flags */
 	__le32 flags;
+	/** @osd1: operating system specific data */
 	__le32 osd1;
+	/** @b: block map or extent tree */
 	union {
 		struct datablocks {
 			__le32 dir_blocks[INDIRECT_BLOCKS];
@@ -197,10 +215,19 @@ struct ext2_inode {
 		char symlink[60];
 		char inline_data[60];
 	} b;
+	/** @version: file version (for NFS) */
 	__le32 version;
+	/** @acl: lower 32 bit of extended attribute block */
 	__le32 acl;
-	__le32 size_high;	/* previously dir_acl, but never used */
+	/** @size_high - dir_acl on ext2/3, upper 32 size bits on ext4
+	 *
+	 * In ext2/3 this field was named i_dir_acl, though it was usually set
+	 * to zero and never used.
+	 */
+	__le32 size_high;
+	/** @fragment_addr - (obsolete) fragment address */
 	__le32 fragment_addr;
+	/** @osd2: operating system specific data */
 	__le32 osd2[3];
 };
 
diff --git a/include/fs.h b/include/fs.h
index ef540e7c23d..63727567ccc 100644
--- a/include/fs.h
+++ b/include/fs.h
@@ -25,7 +25,7 @@ struct blk_desc;
  * do_fat_fsload - Run the fatload command
  *
  * @cmdtp: Command information for fatload
- * @flag: Command flags (CMD_FLAG_...)
+ * @flag: Command flags (CMD_FLAG\_...)
  * @argc: Number of arguments
  * @argv: List of arguments
  * Return: result (see enum command_ret_t)
@@ -37,7 +37,7 @@ int do_fat_fsload(struct cmd_tbl *cmdtp, int flag, int argc,
  * do_ext2load - Run the ext2load command
  *
  * @cmdtp: Command information for ext2load
- * @flag: Command flags (CMD_FLAG_...)
+ * @flag: Command flags (CMD_FLAG\_...)
  * @argc: Number of arguments
  * @argv: List of arguments
  * Return: result (see enum command_ret_t)
@@ -145,7 +145,7 @@ int fs_size(const char *filename, loff_t *size);
  * @offset:	offset in the file from where to start reading
  * @len:	the number of bytes to read. Use 0 to read entire file.
  * @actread:	returns the actual number of bytes read
- * Return:	0 if OK with valid *actread, -1 on error conditions
+ * Return:	0 if OK with valid @actread, -1 on error conditions
  */
 int fs_read(const char *filename, ulong addr, loff_t offset, loff_t len,
 	    loff_t *actread);
@@ -160,7 +160,7 @@ int fs_read(const char *filename, ulong addr, loff_t offset, loff_t len,
  * @offset:	offset in the file from where to start writing
  * @len:	the number of bytes to write
  * @actwrite:	returns the actual number of bytes written
- * Return:	0 if OK with valid *actwrite, -1 on error conditions
+ * Return:	0 if OK with valid @actwrite, -1 on error conditions
  */
 int fs_write(const char *filename, ulong addr, loff_t offset, loff_t len,
 	     loff_t *actwrite);
@@ -186,57 +186,73 @@ struct fs_dirent {
 	unsigned int type;
 	/** @size:		file size */
 	loff_t size;
-	/** @flags:		attribute flags (FS_ATTR_*) */
+	/** @attr:		attribute flags (FS_ATTR_*) */
 	u32 attr;
-	/** create_time:	time of creation */
+	/** @create_time:	time of creation */
 	struct rtc_time create_time;
-	/** access_time:	time of last access */
+	/** @access_time:	time of last access */
 	struct rtc_time access_time;
-	/** change_time:	time of last modification */
+	/** @change_time:	time of last modification */
 	struct rtc_time change_time;
-	/** name:		file name */
+	/** @name:		file name */
 	char name[FS_DIRENT_NAME_LEN];
 };
 
-/* Note: fs_dir_stream should be treated as opaque to the user of fs layer */
+/**
+ * struct fs_dir_stream - Structure representing an opened directory
+ *
+ * Struct fs_dir_stream should be treated opaque to the user of fs layer.
+ * The fields @desc and @part are used by the fs layer.
+ * File system drivers pass additional private fields with the pointers
+ * to this structure.
+ *
+ * @desc:	block device descriptor
+ * @part:	partition number
+ */
 struct fs_dir_stream {
-	/* private to fs. layer: */
 	struct blk_desc *desc;
 	int part;
 };
 
-/*
+/**
  * fs_opendir - Open a directory
  *
- * @filename: the path to directory to open
- * Return: a pointer to the directory stream or NULL on error and errno
- *    set appropriately
+ * .. note::
+ *    The returned struct fs_dir_stream should be treated opaque to the
+ *    user of the fs layer.
+ *
+ * @filename: path to the directory to open
+ * Return:
+ * A pointer to the directory stream or NULL on error and errno set
+ * appropriately
  */
 struct fs_dir_stream *fs_opendir(const char *filename);
 
-/*
+/**
  * fs_readdir - Read the next directory entry in the directory stream.
  *
- * Works in an analogous way to posix readdir().  The previously returned
- * directory entry is no longer valid after calling fs_readdir() again.
+ * fs_readir works in an analogous way to posix readdir().
+ * The previously returned directory entry is no longer valid after calling
+ * fs_readdir() again.
  * After fs_closedir() is called, the returned directory entry is no
  * longer valid.
  *
  * @dirs: the directory stream
- * Return: the next directory entry (only valid until next fs_readdir() or
- *    fs_closedir() call, do not attempt to free()) or NULL if the end of
- *    the directory is reached.
+ * Return:
+ * the next directory entry (only valid until next fs_readdir() or
+ * fs_closedir() call, do not attempt to free()) or NULL if the end of
+ * the directory is reached.
  */
 struct fs_dirent *fs_readdir(struct fs_dir_stream *dirs);
 
-/*
+/**
  * fs_closedir - close a directory stream
  *
  * @dirs: the directory stream
  */
 void fs_closedir(struct fs_dir_stream *dirs);
 
-/*
+/**
  * fs_unlink - delete a file or directory
  *
  * If a given name is a directory, it will be deleted only if it's empty
@@ -246,7 +262,7 @@ void fs_closedir(struct fs_dir_stream *dirs);
  */
 int fs_unlink(const char *filename);
 
-/*
+/**
  * fs_mkdir - Create a directory
  *
  * @filename: Name of directory to create
@@ -292,7 +308,7 @@ int do_fs_type(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]);
  * do_fs_types - List supported filesystems.
  *
  * @cmdtp: Command information for fstypes
- * @flag: Command flags (CMD_FLAG_...)
+ * @flag: Command flags (CMD_FLAG\_...)
  * @argc: Number of arguments
  * @argv: List of arguments
  * Return: result (see enum command_ret_t)