* [PATCH 1/1] Ext4Pkg: Add documentation surrounding ext4 directory entries
@ 2023-01-11 23:21 Pedro Falcato
2023-01-11 23:34 ` Marvin Häuser
0 siblings, 1 reply; 3+ messages in thread
From: Pedro Falcato @ 2023-01-11 23:21 UTC (permalink / raw)
To: devel; +Cc: Pedro Falcato, Marvin Häuser
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 | 18 +++++++++++++++++-
Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h | 3 +--
2 files changed, 18 insertions(+), 3 deletions(-)
diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
index 4fd91a423324..2dad967e575d 100644
--- a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
+++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
@@ -397,12 +397,28 @@ typedef struct _Ext4Inode {
UINT32 i_projid;
} EXT4_INODE;
+#define EXT4_NAME_MAX 255
+
typedef struct {
+ // ext4 directory entries are layed out in the following fashion:
+ // offset 0x0: UINT32 inode number (if 0, unused entry, should skip.)
+ // offset 0x4: UINT16 rec_len: Dir entry's length.
+ // Note: rec_len >= name_len + EXT4_MIN_DIR_ENTRY_LEN and rec_len % 4 == 0.
+ // offset 0x6: UINT8 name_len: Dir entry's name's length
+ // offset 0x7: UINT8 file_type Dir entry's file type indicator
+ // offset 0x8: CHAR8 name[name_len]: Variable length character array; not null-terminated.
+ //
+ // Further note: 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.
UINT32 inode;
UINT16 rec_len;
UINT8 name_len;
UINT8 file_type;
- CHAR8 name[255];
+ CHAR8 name[EXT4_NAME_MAX];
} 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..81ba568c5947 100644
--- a/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
+++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
@@ -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
^ permalink raw reply related [flat|nested] 3+ messages in thread* Re: [PATCH 1/1] Ext4Pkg: Add documentation surrounding ext4 directory entries
2023-01-11 23:21 [PATCH 1/1] Ext4Pkg: Add documentation surrounding ext4 directory entries Pedro Falcato
@ 2023-01-11 23:34 ` Marvin Häuser
2023-01-11 23:44 ` Pedro Falcato
0 siblings, 1 reply; 3+ messages in thread
From: Marvin Häuser @ 2023-01-11 23:34 UTC (permalink / raw)
To: Pedro Falcato; +Cc: devel
> On 12. Jan 2023, at 00:21, 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 | 18 +++++++++++++++++-
> Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h | 3 +--
> 2 files changed, 18 insertions(+), 3 deletions(-)
>
> diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> index 4fd91a423324..2dad967e575d 100644
> --- a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> +++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> @@ -397,12 +397,28 @@ typedef struct _Ext4Inode {
> UINT32 i_projid;
> } EXT4_INODE;
>
> +#define EXT4_NAME_MAX 255
> +
> typedef struct {
> + // ext4 directory entries are layed out in the
laid out
> following fashion:
> + // offset 0x0: UINT32 inode number (if 0, unused entry, should skip.)
> + // offset 0x4: UINT16 rec_len: Dir entry's length.
> + // Note: rec_len >= name_len + EXT4_MIN_DIR_ENTRY_LEN and rec_len % 4 == 0.
> + // offset 0x6: UINT8 name_len: Dir entry's name's length
> + // offset 0x7: UINT8 file_type Dir entry's file type indicator
> + // offset 0x8: CHAR8 name[name_len]: Variable length character array; not null-terminated.
Why not document all that right above the member names? Would remove redundant info and be more Doxygen-friendly.
> + //
> + // Further note: 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.
> UINT32 inode;
> UINT16 rec_len;
> UINT8 name_len;
> UINT8 file_type;
> - CHAR8 name[255];
> + CHAR8 name[EXT4_NAME_MAX];
> } 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..81ba568c5947 100644
> --- a/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
> +++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
> @@ -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
>
^ permalink raw reply [flat|nested] 3+ messages in thread* Re: [PATCH 1/1] Ext4Pkg: Add documentation surrounding ext4 directory entries
2023-01-11 23:34 ` Marvin Häuser
@ 2023-01-11 23:44 ` Pedro Falcato
0 siblings, 0 replies; 3+ messages in thread
From: Pedro Falcato @ 2023-01-11 23:44 UTC (permalink / raw)
To: Marvin Häuser; +Cc: devel
[-- Attachment #1: Type: text/plain, Size: 3164 bytes --]
On Wed, Jan 11, 2023 at 11:34 PM Marvin Häuser <mhaeuser@posteo.de> wrote:
>
> > On 12. Jan 2023, at 00:21, 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 | 18 +++++++++++++++++-
> > Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h | 3 +--
> > 2 files changed, 18 insertions(+), 3 deletions(-)
> >
> > diff --git a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> > index 4fd91a423324..2dad967e575d 100644
> > --- a/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> > +++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Disk.h
> > @@ -397,12 +397,28 @@ typedef struct _Ext4Inode {
> > UINT32 i_projid;
> > } EXT4_INODE;
> >
> > +#define EXT4_NAME_MAX 255
> > +
> > typedef struct {
> > + // ext4 directory entries are layed out in the
>
> laid out
>
> > following fashion:
> > + // offset 0x0: UINT32 inode number (if 0, unused entry, should skip.)
> > + // offset 0x4: UINT16 rec_len: Dir entry's length.
> > + // Note: rec_len >= name_len + EXT4_MIN_DIR_ENTRY_LEN and
> rec_len % 4 == 0.
> > + // offset 0x6: UINT8 name_len: Dir entry's name's length
> > + // offset 0x7: UINT8 file_type Dir entry's file type indicator
> > + // offset 0x8: CHAR8 name[name_len]: Variable length character array;
> not null-terminated.
>
> Why not document all that right above the member names? Would remove
> redundant info and be more Doxygen-friendly.
>
> > + //
> > + // Further note: 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.
> > UINT32 inode;
> > UINT16 rec_len;
> > UINT8 name_len;
> > UINT8 file_type;
> > - CHAR8 name[255];
> > + CHAR8 name[EXT4_NAME_MAX];
> > } 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..81ba568c5947 100644
> > --- a/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
> > +++ b/Features/Ext4Pkg/Ext4Dxe/Ext4Dxe.h
> > @@ -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
> >
>
ACK, sending v2.
--
Pedro
[-- Attachment #2: Type: text/html, Size: 4133 bytes --]
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2023-01-11 23:44 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-01-11 23:21 [PATCH 1/1] Ext4Pkg: Add documentation surrounding ext4 directory entries Pedro Falcato
2023-01-11 23:34 ` Marvin Häuser
2023-01-11 23:44 ` Pedro Falcato
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox