On 11/19/24 11:04 AM, Matthew Wilcox wrote: > On Tue, Nov 19, 2024 at 10:55:07AM -0800, Randy Dunlap wrote: >> Add some kernel-doc notation to structs in fiemap header files >> then pull that into Documentation/filesystems/fiemap.rst >> instead of duplicating the header file structs in fiemap.rst. >> This helps to future-proof fiemap.rst against struct changes. > > Thanks! This is great. Feels free to ignore every suggestion I'm about > to make. > >> +/** >> + * struct fiemap_extent - description of one fiemap extent >> + * @fe_logical: logical offset in bytes for the start of the extent >> + * from the beginning of the file > > * @fe_logical: Byte offset of extent in the file. > >> + * @fe_physical: physical offset in bytes for the start of the extent >> + * from the beginning of the disk > > * @fe_physical: Byte offset of extent on disk. > >> +/** >> + * struct fiemap - file extent mappings >> + * @fm_start: logical offset (inclusive) at >> + * which to start mapping (in) > > Do we want to say "Byte offset"? > >> >> +/* flags used in fm_flags: */ >> #define FIEMAP_FLAG_SYNC 0x00000001 /* sync file data before map */ >> #define FIEMAP_FLAG_XATTR 0x00000002 /* map extended attribute tree */ >> #define FIEMAP_FLAG_CACHE 0x00000004 /* request caching of the extents */ >> >> #define FIEMAP_FLAGS_COMPAT (FIEMAP_FLAG_SYNC | FIEMAP_FLAG_XATTR) > > Do we want to turn this into an enum so it can be kernel-doc? > >> +/* flags used in fe_flags: */ >> #define FIEMAP_EXTENT_LAST 0x00000001 /* Last extent in file. */ >> #define FIEMAP_EXTENT_UNKNOWN 0x00000002 /* Data location unknown. */ >> #define FIEMAP_EXTENT_DELALLOC 0x00000004 /* Location still pending. > > Likewise I did consider that. I can do it but it probably involves some fs testing that I don't plan to get into. -- ~Randy
