[PATCH 5/6] fat: Convert fat.h to kernel-doc style
Heinrich Schuchardt
heinrich.schuchardt at canonical.com
Thu Nov 13 07:46:55 CET 2025
From: Simon Glass <simon.glass at canonical.com>
Add kernel-doc comments to structs and public functions in fat.h so that
it is easier to understand the code.
Co-developed-by: Claude <noreply at anthropic.com>
Signed-off-by: Simon Glass <simon.glass at canonical.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
---
include/fat.h | 349 ++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 284 insertions(+), 65 deletions(-)
diff --git a/include/fat.h b/include/fat.h
index 3e6065f845b..f6b31b2de49 100644
--- a/include/fat.h
+++ b/include/fat.h
@@ -83,129 +83,348 @@ struct disk_partition;
((fatsize) != 16 ? 0xff0 : 0xfff0) : \
0xffffff0))
+/**
+ * struct boot_sector - FAT boot sector structure
+ * @ignored: bootstrap code (first 3 bytes)
+ * @system_id: name of filesystem (8 bytes)
+ * @sector_size: bytes per sector
+ * @cluster_size: sectors per cluster
+ * @reserved: number of reserved sectors
+ * @fats: number of FAT copies
+ * @dir_entries: number of root directory entries
+ * @sectors: number of sectors (for small disks)
+ * @media: media descriptor code
+ * @fat_length: sectors per FAT (for FAT12/16)
+ * @secs_track: sectors per track
+ * @heads: number of heads
+ * @hidden: number of hidden sectors
+ * @total_sect: total number of sectors (for larger disks)
+ * @fat32_length: sectors per FAT (FAT32 only)
+ * @flags: flags (bit 8: fat mirroring, low 4: active fat)
+ * @version: filesystem version (FAT32 only)
+ * @root_cluster: first cluster of root directory (FAT32 only)
+ * @info_sector: filesystem info sector (FAT32 only)
+ * @backup_boot: backup boot sector location (FAT32 only)
+ * @reserved2: unused (FAT32 only)
+ */
struct boot_sector {
- __u8 ignored[3]; /* Bootstrap code */
- char system_id[8]; /* Name of fs */
- __u8 sector_size[2]; /* Bytes/sector */
- __u8 cluster_size; /* Sectors/cluster */
- __u16 reserved; /* Number of reserved sectors */
- __u8 fats; /* Number of FATs */
- __u8 dir_entries[2]; /* Number of root directory entries */
- __u8 sectors[2]; /* Number of sectors */
- __u8 media; /* Media code */
- __u16 fat_length; /* Sectors/FAT */
- __u16 secs_track; /* Sectors/track */
- __u16 heads; /* Number of heads */
- __u32 hidden; /* Number of hidden sectors */
- __u32 total_sect; /* Number of sectors (if sectors == 0) */
+ __u8 ignored[3];
+ char system_id[8];
+ __u8 sector_size[2];
+ __u8 cluster_size;
+ __u16 reserved;
+ __u8 fats;
+ __u8 dir_entries[2];
+ __u8 sectors[2];
+ __u8 media;
+ __u16 fat_length;
+ __u16 secs_track;
+ __u16 heads;
+ __u32 hidden;
+ __u32 total_sect;
/* FAT32 only */
- __u32 fat32_length; /* Sectors/FAT */
- __u16 flags; /* Bit 8: fat mirroring, low 4: active fat */
- __u8 version[2]; /* Filesystem version */
- __u32 root_cluster; /* First cluster in root directory */
- __u16 info_sector; /* Filesystem info sector */
- __u16 backup_boot; /* Backup boot sector */
- __u16 reserved2[6]; /* Unused */
+ __u32 fat32_length;
+ __u16 flags;
+ __u8 version[2];
+ __u32 root_cluster;
+ __u16 info_sector;
+ __u16 backup_boot;
+ __u16 reserved2[6];
};
+/**
+ * struct volume_info - FAT volume information structure
+ * @drive_number: BIOS drive number
+ * @reserved: unused field
+ * @ext_boot_sign: extended boot signature (0x29 if fields below exist)
+ * @volume_id: volume serial number (4 bytes)
+ * @volume_label: volume label (11 bytes, padded with spaces)
+ * @fs_type: filesystem type string (typically "FAT12", "FAT16", or "FAT32")
+ *
+ * This structure is part of the boot sector, located after the common fields.
+ * Boot code follows this structure, with boot signature at the end of sector.
+ */
struct volume_info {
- __u8 drive_number; /* BIOS drive number */
- __u8 reserved; /* Unused */
- __u8 ext_boot_sign; /* 0x29 if fields below exist (DOS 3.3+) */
- __u8 volume_id[4]; /* Volume ID number */
- char volume_label[11]; /* Volume label */
- char fs_type[8]; /* Typically FAT12, FAT16, or FAT32 */
- /* Boot code comes next, all but 2 bytes to fill up sector */
- /* Boot sign comes last, 2 bytes */
+ __u8 drive_number;
+ __u8 reserved;
+ __u8 ext_boot_sign;
+ __u8 volume_id[4];
+ char volume_label[11];
+ char fs_type[8];
};
/* see dir_entry::lcase: */
#define CASE_LOWER_BASE 8 /* base (name) is lower case */
#define CASE_LOWER_EXT 16 /* extension is lower case */
+/**
+ * struct nameext - 8.3 filename components
+ * @name: filename (8 bytes)
+ * @ext: extension (3 bytes)
+ */
struct nameext {
char name[8];
char ext[3];
};
+/**
+ * struct dir_entry - FAT directory entry
+ * @nameext: filename and extension (8.3 format)
+ * @attr: file attributes (ATTR_* flags)
+ * @lcase: case flags for name and extension (CASE_LOWER_* flags)
+ * @ctime_ms: creation time (milliseconds)
+ * @ctime: creation time (hours, minutes, seconds)
+ * @cdate: creation date
+ * @adate: last access date
+ * @starthi: high 16 bits of cluster number (FAT32 only)
+ * @time: modification time
+ * @date: modification date
+ * @start: low 16 bits of cluster number
+ * @size: file size in bytes
+ */
struct dir_entry {
- struct nameext nameext; /* Name and extension */
- __u8 attr; /* Attribute bits */
- __u8 lcase; /* Case for name and ext (CASE_LOWER_x) */
- __u8 ctime_ms; /* Creation time, milliseconds */
- __u16 ctime; /* Creation time */
- __u16 cdate; /* Creation date */
- __u16 adate; /* Last access date */
- __u16 starthi; /* High 16 bits of cluster in FAT32 */
- __u16 time,date,start;/* Time, date and first cluster */
- __u32 size; /* File size in bytes */
+ struct nameext nameext;
+ __u8 attr;
+ __u8 lcase;
+ __u8 ctime_ms;
+ __u16 ctime;
+ __u16 cdate;
+ __u16 adate;
+ __u16 starthi;
+ __u16 time;
+ __u16 date;
+ __u16 start;
+ __u32 size;
};
+/**
+ * struct dir_slot - VFAT long filename entry
+ * @id: sequence number (bit 6 = last entry, bits 0-4 = sequence)
+ * @name0_4: characters 0-4 of long filename (UTF-16LE)
+ * @attr: must be ATTR_VFAT (0x0F)
+ * @reserved: unused field
+ * @alias_checksum: checksum of 8.3 alias for this long name
+ * @name5_10: characters 5-10 of long filename (UTF-16LE)
+ * @start: unused (always 0)
+ * @name11_12: characters 11-12 of long filename (UTF-16LE)
+ *
+ * Long filename entries precede the corresponding short entry in directory.
+ * Multiple entries may be used to store names longer than 13 characters.
+ */
struct dir_slot {
- __u8 id; /* Sequence number for slot */
- __u8 name0_4[10]; /* First 5 characters in name */
- __u8 attr; /* Attribute byte */
- __u8 reserved; /* Unused */
- __u8 alias_checksum;/* Checksum for 8.3 alias */
- __u8 name5_10[12]; /* 6 more characters in name */
- __u16 start; /* Unused */
- __u8 name11_12[4]; /* Last 2 characters in name */
+ __u8 id;
+ __u8 name0_4[10];
+ __u8 attr;
+ __u8 reserved;
+ __u8 alias_checksum;
+ __u8 name5_10[12];
+ __u16 start;
+ __u8 name11_12[4];
};
-/*
- * Private filesystem parameters
+/**
+ * struct fsdata - FAT filesystem instance data
+ * @fatbuf: buffer for reading/writing FAT (must be 32-bit aligned for FAT32)
+ * @fatsize: size of FAT in bits (12, 16, or 32)
+ * @fatlength: length of FAT in sectors
+ * @fat_sect: starting sector of the FAT
+ * @fat_dirty: flag indicating if fatbuf has been modified
+ * @rootdir_sect: starting sector of root directory
+ * @sect_size: size of sectors in bytes
+ * @clust_size: size of clusters in sectors
+ * @data_begin: sector offset of first data cluster (can be negative)
+ * @fatbufnum: currently buffered FAT sector number (init to -1)
+ * @rootdir_size: size of root directory in entries (for non-FAT32)
+ * @root_cluster: first cluster of root directory (FAT32 only)
+ * @total_sect: total number of sectors
+ * @fats: number of FAT copies
*
- * Note: FAT buffer has to be 32 bit aligned
- * (see FAT32 accesses)
+ * This structure holds the runtime state of a mounted FAT filesystem.
+ * The fatbuf must be 32-bit aligned due to FAT32 sector access requirements.
*/
struct fsdata {
- __u8 *fatbuf; /* Current FAT buffer */
- int fatsize; /* Size of FAT in bits */
- __u32 fatlength; /* Length of FAT in sectors */
- __u16 fat_sect; /* Starting sector of the FAT */
- __u8 fat_dirty; /* Set if fatbuf has been modified */
- __u32 rootdir_sect; /* Start sector of root directory */
- __u16 sect_size; /* Size of sectors in bytes */
- __u16 clust_size; /* Size of clusters in sectors */
- int data_begin; /* The sector of the first cluster, can be negative */
- int fatbufnum; /* Used by get_fatent, init to -1 */
- int rootdir_size; /* Size of root dir for non-FAT32 */
- __u32 root_cluster; /* First cluster of root dir for FAT32 */
- u32 total_sect; /* Number of sectors */
- int fats; /* Number of FATs */
+ __u8 *fatbuf;
+ int fatsize;
+ __u32 fatlength;
+ __u16 fat_sect;
+ __u8 fat_dirty;
+ __u32 rootdir_sect;
+ __u16 sect_size;
+ __u16 clust_size;
+ int data_begin;
+ int fatbufnum;
+ int rootdir_size;
+ __u32 root_cluster;
+ u32 total_sect;
+ int fats;
};
struct fat_itr;
+/**
+ * clust_to_sect() - convert cluster number to sector number
+ * @fsdata: filesystem instance data
+ * @clust: cluster number
+ *
+ * Return: sector number corresponding to the given cluster
+ */
static inline u32 clust_to_sect(struct fsdata *fsdata, u32 clust)
{
return fsdata->data_begin + clust * fsdata->clust_size;
}
+/**
+ * sect_to_clust() - convert sector number to cluster number
+ * @fsdata: filesystem instance data
+ * @sect: sector number
+ *
+ * Return: cluster number corresponding to the given sector
+ */
static inline u32 sect_to_clust(struct fsdata *fsdata, int sect)
{
return (sect - fsdata->data_begin) / fsdata->clust_size;
}
+/**
+ * file_fat_detectfs() - detect and initialize the FAT filesystem
+ *
+ * Return: 0 on success, -1 on error
+ */
int file_fat_detectfs(void);
+
+/**
+ * fat_exists() - check if a file exists
+ * @filename: full path to file
+ *
+ * Return: 0 if file exists, -1 if not found or error
+ */
int fat_exists(const char *filename);
+
+/**
+ * fat_size() - get the size of a file
+ * @filename: full path to file
+ * @size: pointer to store file size
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_size(const char *filename, loff_t *size);
+
+/**
+ * file_fat_read() - read a file from FAT filesystem
+ * @filename: full path to file
+ * @buffer: buffer to read data into
+ * @maxsize: maximum number of bytes to read
+ *
+ * Return: number of bytes read, -1 on error
+ */
int file_fat_read(const char *filename, void *buffer, int maxsize);
+
+/**
+ * fat_set_blk_dev() - set the block device and partition for FAT operations
+ * @rbdd: block device descriptor
+ * @info: partition information
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_set_blk_dev(struct blk_desc *rbdd, struct disk_partition *info);
+
+/**
+ * fat_register_device() - register a FAT filesystem on a block device
+ * @dev_desc: block device descriptor
+ * @part_no: partition number (0 = whole device)
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_register_device(struct blk_desc *dev_desc, int part_no);
+/**
+ * file_fat_write() - write to a file on FAT filesystem
+ * @filename: full path to file
+ * @buf: buffer containing data to write
+ * @offset: offset in file to start writing
+ * @len: number of bytes to write
+ * @actwrite: pointer to store actual number of bytes written
+ *
+ * Return: 0 on success, -1 on error
+ */
int file_fat_write(const char *filename, void *buf, loff_t offset, loff_t len,
loff_t *actwrite);
+
+/**
+ * fat_read_file() - read from a file on FAT filesystem
+ * @filename: full path to file
+ * @buf: buffer to read data into
+ * @offset: offset in file to start reading
+ * @len: number of bytes to read
+ * @actread: pointer to store actual number of bytes read
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_read_file(const char *filename, void *buf, loff_t offset, loff_t len,
loff_t *actread);
+
+/**
+ * fat_opendir() - open a directory for reading
+ * @filename: full path to directory
+ * @dirsp: pointer to store directory stream handle
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_opendir(const char *filename, struct fs_dir_stream **dirsp);
+
+/**
+ * fat_readdir() - read next entry from directory
+ * @dirs: directory stream handle
+ * @dentp: pointer to store directory entry
+ *
+ * Return: 0 on success, -1 on error or end of directory
+ */
int fat_readdir(struct fs_dir_stream *dirs, struct fs_dirent **dentp);
+
+/**
+ * fat_closedir() - close a directory stream
+ * @dirs: directory stream handle
+ */
void fat_closedir(struct fs_dir_stream *dirs);
+
+/**
+ * fat_unlink() - delete a file or empty directory
+ * @filename: full path to file or directory
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_unlink(const char *filename);
+
+/**
+ * fat_rename() - rename a file or directory
+ * @old_path: current full path
+ * @new_path: new full path
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_rename(const char *old_path, const char *new_path);
+
+/**
+ * fat_mkdir() - create a directory
+ * @dirname: full path to new directory
+ *
+ * Return: 0 on success, -1 on error
+ */
int fat_mkdir(const char *dirname);
+
+/**
+ * fat_close() - close FAT filesystem and release resources
+ */
void fat_close(void);
+
+/**
+ * fat_next_cluster() - get the next cluster in a chain
+ * @itr: directory iterator
+ * @nbytes: pointer to store number of bytes in cluster
+ *
+ * Return: pointer to cluster data buffer
+ */
void *fat_next_cluster(struct fat_itr *itr, unsigned int *nbytes);
/**
--
2.51.0
More information about the U-Boot
mailing list