1. Patchew
  2. EDK2
  3. [edk2-devel] [PATCH 0/3] Ext4Pkg: Small ext4 fixes and improvements
  4. View patch

[edk2-devel] [PATCH 2/3] Ext4Pkg: Add documentation surrounding ext4 directory entries

Pedro Falcato posted 3 patches 3 years ago
[edk2-devel] [PATCH 2/3] Ext4Pkg: Add documentation surrounding ext4 directory entries
Posted by Pedro Falcato 3 years ago 
Several questions have popped up regarding the ext4 directory entry
layout and contents off-list. Attempt to clarify these issues by adding
some explanatory comments.

Signed-off-by: Pedro Falcato <pedro.falcato@gmail.com>
Cc: Marvin Häuser <mhaeuser@posteo.de>
---
 Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h | 21 +++++++++++++++++++--
 Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h  |  5 ++---
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
index 4fd91a423324..d0a455d0e572 100644
--- a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
+++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
@@ -1,7 +1,7 @@
 /** @file
   Raw filesystem data structures
 
-  Copyright (c) 2021 Pedro Falcato All rights reserved.
+  Copyright (c) 2021 - 2023 Pedro Falcato All rights reserved.
   SPDX-License-Identifier: BSD-2-Clause-Patent
 
   Layout of an EXT2/3/4 filesystem:
@@ -397,12 +397,29 @@ typedef struct _Ext4Inode {
   UINT32       i_projid;
 } EXT4_INODE;
 
+#define EXT4_NAME_MAX  255
+
 typedef struct {
+  // offset 0x0: inode number (if 0, unused entry, should skip.)
   UINT32    inode;
+  // offset 0x4: Directory entry's length.
+  //             Note: rec_len >= name_len + EXT4_MIN_DIR_ENTRY_LEN and rec_len % 4 == 0.
   UINT16    rec_len;
+  // offset 0x6: Directory entry's name's length
   UINT8     name_len;
+  // offset 0x7: Directory entry's file type indicator
   UINT8     file_type;
-  CHAR8     name[255];
+  // offset 0x8: name[name_len]: Variable length character array; not null-terminated.
+  CHAR8     name[EXT4_NAME_MAX];
+  // Further notes on names:
+  // 1) We use EXT4_NAME_MAX here instead of flexible arrays for ease of use around the driver.
+  //
+  // 2) ext4 directories are defined, as the documentation puts it, as:
+  // "a directory is more or less a flat file that maps an arbitrary byte string
+  // (usually ASCII) to an inode number on the filesystem". So, they are not
+  // necessarily encoded with ASCII, UTF-8, or any of the sort. We must treat it
+  // as a bag of bytes. When interacting with EFI interfaces themselves (which expect UCS-2)
+  // we skip any directory entry that is not valid UTF-8.
 } EXT4_DIR_ENTRY;
 
 #define EXT4_MIN_DIR_ENTRY_LEN  8
diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h b/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
index adf3c13f6ea9..466e49523030 100644
--- a/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
+++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
@@ -1,7 +1,7 @@
 /** @file
   Common header for the driver
 
-  Copyright (c) 2021 - 2022 Pedro Falcato All rights reserved.
+  Copyright (c) 2021 - 2023 Pedro Falcato All rights reserved.
   SPDX-License-Identifier: BSD-2-Clause-Patent
 **/
 
@@ -31,8 +31,7 @@
 
 #include "Ext4Disk.h"
 
-#define SYMLOOP_MAX    8
-#define EXT4_NAME_MAX  255
+#define SYMLOOP_MAX  8
 //
 // We need to specify path length limit for security purposes, to prevent possible
 // overflows and dead-loop conditions. Originally this limit is absent in FS design,
-- 
2.39.0



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#98326): https://edk2.groups.io/g/devel/message/98326
Mute This Topic: https://groups.io/mt/96212633/1787277
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org]
-=-=-=-=-=-=-=-=-=-=-=-
Re: [edk2-devel] [PATCH 2/3] Ext4Pkg: Add documentation surrounding ext4 directory entries
Posted by Marvin Häuser 3 years ago 
Well, this is still not Doxygen-friendly (requires three slashes) and it's still awkward (as in done nowhere else) to explicitly list the offset or name in the comment. In case neither is a concern:

Reviewed-by: Marvin Häuser <mhaeuser@posteo.de <mailto:mhaeuser@posteo.de>>

> On 12. Jan 2023, at 00:59, Pedro Falcato <pedro.falcato@gmail.com> wrote:
> 
> Several questions have popped up regarding the ext4 directory entry
> layout and contents off-list. Attempt to clarify these issues by adding
> some explanatory comments.
> 
> Signed-off-by: Pedro Falcato <pedro.falcato@gmail.com>
> Cc: Marvin Häuser <mhaeuser@posteo.de>
> ---
> Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h | 21 +++++++++++++++++++--
> Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h  |  5 ++---
> 2 files changed, 21 insertions(+), 5 deletions(-)
> 
> diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> index 4fd91a423324..d0a455d0e572 100644
> --- a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> +++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> @@ -1,7 +1,7 @@
> /** @file
>   Raw filesystem data structures
> 
> -  Copyright (c) 2021 Pedro Falcato All rights reserved.
> +  Copyright (c) 2021 - 2023 Pedro Falcato All rights reserved.
>   SPDX-License-Identifier: BSD-2-Clause-Patent
> 
>   Layout of an EXT2/3/4 filesystem:
> @@ -397,12 +397,29 @@ typedef struct _Ext4Inode {
>   UINT32       i_projid;
> } EXT4_INODE;
> 
> +#define EXT4_NAME_MAX  255
> +
> typedef struct {
> +  // offset 0x0: inode number (if 0, unused entry, should skip.)
>   UINT32    inode;
> +  // offset 0x4: Directory entry's length.
> +  //             Note: rec_len >= name_len + EXT4_MIN_DIR_ENTRY_LEN and rec_len % 4 == 0.
>   UINT16    rec_len;
> +  // offset 0x6: Directory entry's name's length
>   UINT8     name_len;
> +  // offset 0x7: Directory entry's file type indicator
>   UINT8     file_type;
> -  CHAR8     name[255];
> +  // offset 0x8: name[name_len]: Variable length character array; not null-terminated.
> +  CHAR8     name[EXT4_NAME_MAX];
> +  // Further notes on names:
> +  // 1) We use EXT4_NAME_MAX here instead of flexible arrays for ease of use around the driver.
> +  //
> +  // 2) ext4 directories are defined, as the documentation puts it, as:
> +  // "a directory is more or less a flat file that maps an arbitrary byte string
> +  // (usually ASCII) to an inode number on the filesystem". So, they are not
> +  // necessarily encoded with ASCII, UTF-8, or any of the sort. We must treat it
> +  // as a bag of bytes. When interacting with EFI interfaces themselves (which expect UCS-2)
> +  // we skip any directory entry that is not valid UTF-8.
> } EXT4_DIR_ENTRY;
> 
> #define EXT4_MIN_DIR_ENTRY_LEN  8
> diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h b/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
> index adf3c13f6ea9..466e49523030 100644
> --- a/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
> +++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
> @@ -1,7 +1,7 @@
> /** @file
>   Common header for the driver
> 
> -  Copyright (c) 2021 - 2022 Pedro Falcato All rights reserved.
> +  Copyright (c) 2021 - 2023 Pedro Falcato All rights reserved.
>   SPDX-License-Identifier: BSD-2-Clause-Patent
> **/
> 
> @@ -31,8 +31,7 @@
> 
> #include "Ext4Disk.h"
> 
> -#define SYMLOOP_MAX    8
> -#define EXT4_NAME_MAX  255
> +#define SYMLOOP_MAX  8
> //
> // We need to specify path length limit for security purposes, to prevent possible
> // overflows and dead-loop conditions. Originally this limit is absent in FS design,
> -- 
> 2.39.0
> 



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#98514): https://edk2.groups.io/g/devel/message/98514
Mute This Topic: https://groups.io/mt/96212633/1787277
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org]
-=-=-=-=-=-=-=-=-=-=-=-

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.