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 <mhaeu...@posteo.de <mailto:mhaeu...@posteo.de>> > On 12. Jan 2023, at 00:59, Pedro Falcato <pedro.falc...@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.falc...@gmail.com> > Cc: Marvin Häuser <mhaeu...@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/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
