Ext4Pkg: Add documentation surrounding ext4 directory entries

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>
Reviewed-by: Marvin Häuser <mhaeuser@posteo.de>

2 files changed, 21 insertions, 5 deletions

diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
index 4fd91a4233..d0a455d0e5 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 adf3c13f6e..466e495230 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,