fatdrvce.h

#include <fatdrvce.h>

The fatdrvce library implements routines for working with a FAT32 based filesystem. The read and write functions are implemented as user-provided callbacks, allowing for any underlying storage to be used.

Typical Usage
Known Limitations
API Documentation

Typical Usage 

This library can be integrated with msddrvce in order to access physical devices such as a flash drive.

For best performance, the “cluster allocation size” should be set to the maximum allowed. On Linux this can be accomplished with the following command:

mkfs.vfat -s 128 -S 512 -v /dev/<drive partition, e.g. sda1>

Known Limitations 

The filesystem must use 512 byte logical blocks.
The filesystem must be formatted as FAT32 (no support for FAT12, FAT16, or exFAT)
Long name support is not currently implemented.

API Documentation 

FAT Filesystem Driver.

Author: Matt “MateoConLechuga” Waltz
Author: Jacob “jacobly” Young

Defines

FAT_BLOCK_SIZE: Block size in bytes.

fat_callback_data_t

A pointer to fat_callback_data_t is passed to the user-provided callback functions.

The default is void *, but this can be changed by doing:

#define fat_callback_data_t struct my_fat_callback_data
#include <fatdrvce.h>

FAT_FILE: Entry has no attributes.

FAT_RDONLY: Entry is read-only.

FAT_HIDDEN: Entry is hidden.

FAT_SYSTEM: Entry is a system file / directory.

FAT_VOLLABEL: Entry is a volume label — only for root directory.

FAT_DIR: Entry is a directory (or subdirectory)

FAT_ARCHIVE: Entry is a directory (or subdirectory)

Enums

enum fat_error_t

FAT Driver return codes.

Values:

enumerator FAT_SUCCESS = 0: Operation was successful.

enumerator FAT_ERROR_INVALID_PARAM: An invalid argument was provided.

enumerator FAT_ERROR_NOT_SUPPORTED: The operation is not supported.

enumerator FAT_ERROR_INVALID_CLUSTER: An invalid FAT cluster was accessed.

enumerator FAT_ERROR_INVALID_POSITION: An invalid position in the file.

enumerator FAT_ERROR_NOT_FOUND: The partition, file, or entry does not exist.

enumerator FAT_ERROR_EXISTS: The file or entry already exists.

enumerator FAT_ERROR_INVALID_PATH: An invalid path was provided.

enumerator FAT_ERROR_FAILED_ALLOC: Allocation of a cluster or file failed.

enumerator FAT_ERROR_CLUSTER_CHAIN: The cluster chain was corrupted.

enumerator FAT_ERROR_DIRECTORY_NOT_EMPTY: The directory is not empty.

enumerator FAT_ERROR_NO_VOLUME_LABEL: No volume label found for partition.

enumerator FAT_ERROR_RDONLY: The file or entry is read-only.

enumerator FAT_ERROR_RW_FAILED: The callback read failed to read/write.

enumerator FAT_ERROR_INVALID_FILESYSTEM: Attempted to initialize a non-FAT filesystem.

enum fat_list_option_t

FAT directory listing options.

Values:

enumerator FAT_LIST_FILEONLY: For listing only files.

enumerator FAT_LIST_DIRONLY: For listing only directories.

enumerator FAT_LIST_ALL: For listing files and directories.

Functions

fat_error_t fat_Init(fat_t *fat)

Initializes the FAT filesystem and allows other FAT functions to be used.

This function will read and verify that a valid FAT filesystem is being accessed.

Parameters: fat – FAT structure type. Before calling this function, the following elements must be set in the fat structure: read, write, usr, first_lba, and last_lba.
Returns: FAT_SUCCESS on success, otherwise error.

fat_error_t fat_Deinit(fat_t *fat)

Deinitialize the FAT filesystem.

This is not required to be called, however it will clear the filesystem dirty bit so other OSes don’t see the filesystem with potential errors. You cannot use the FAT structure after this call, and should call fat_Init if you need to modify the filesystem again.

Parameters: fat – Initialized FAT structure type.
Returns: FAT_SUCCESS on success, otherwise error.

uint24_t fat_DirList(fat_t *fat, const char *path, fat_list_option_t option, fat_dir_entry_t *entries, uint24_t size, uint24_t skip)

Parses a directory and returns a list of files and subdirectories in it.

#define MAX_ENTRIES 10

fat_dir_entry_t entries[MAX_ENTRIES];
int24_t count = fat_DirList("/DIR", FAT_LIST_ALL, entries, MAX_ENTRIES, 0);

Parameters

fat – Initialized FAT structure.
path – Directory path to get list from.
option – Listing option for files to find (e.g. FAT_LIST_FILEONLY)
entries – Location to store found entries.
size – Number of available entries to store to in the entries argument. Must be greater than or equal to 1.
skip – If this function has previously been called, use this function to start parsing after this many entries.

Returns

Number of entries found.

fat_error_t fat_GetVolumeLabel(fat_t *fat, char *label)

Returns the volume label of the drive if it exists.

Parameters

fat – Initialized FAT structure type.
label – Storage for returning label, must be >= 13 bytes.

Returns

FAT_SUCCESS on success, FAT_ERROR_NO_VOLUME_LABEL if no label, otherwise a different error.

fat_error_t fat_Create(fat_t *fat, const char *path, const char *name, uint8_t attrib)

Creates new files or directories in the filesystem.

Parameters

fat – Initialized FAT structure.
path – Path in which to create. Does not create subdirectories.
name – Name of new file or directory.
attrib – New entry attributes, can be a mask of FAT_RDONLY, FAT_HIDDEN, FAT_SYSTEM, and FAT_DIR.

Returns

FAT_SUCCESS on success, otherwise error.

fat_error_t fat_Delete(fat_t *fat, const char *filepath)

Deletes a file or directory and deallocates the spaced used by it on disk.

Note

Directories must be empty in order to be deleted.

Warning

Do not use this function on open files. The file must be closed before attempting to delete it.

Parameters

fat – Initialized FAT structure.
filepath – Absolute path to file or directory to delete.

Returns

FAT_SUCCESS on success, otherwise error.

fat_error_t fat_SetAttrib(fat_t *fat, const char *filepath, uint8_t attrib)

Sets the attributes (read only, hidden, etc) of the file.

Parameters

fat – Initialized FAT structure.
filepath – Absolute file path.
attrib – FAT attributes to set file to.

Returns

FAT_SUCCESS on success, otherwise error.

uint8_t fat_GetAttrib(fat_t *fat, const char *filepath)

Gets the attributes (read only, hidden, etc) of the file.

Parameters

fat – Initialized FAT structure.
filepath – Absolute file path.

Returns

File attributes, or 255 if an error.

fat_error_t fat_Open(fat_file_t *file, fat_t *fat, const char *filepath)

Opens a file for either reading or writing, or both.

Parameters

file – Uninitialized structure to store working file information.
fat – Initialized FAT structure.
filepath – Absolute file path.

Returns

FAT_SUCCESS on success, otherwise error.

fat_error_t fat_SetSize(fat_file_t *file, uint32_t size)

Sets the size of the file, allocating or deallocating space as needed.

This function should be called before attempting to read/write in a file that does not have a large enough current file size, (i.e. a newly created file).

Note

This function resets the block position to 0, regardless size change.

Parameters

file – FAT file structure.
size – New file size.

Returns

FAT_SUCCESS on success, otherwise error.

uint32_t fat_GetSize(fat_file_t *file)

Gets the size of a file.

Parameters: file – FAT file structure.
Returns: File size in bytes.

fat_error_t fat_SetPos(fat_file_t *file, uint24_t block)

Sets the block offset position in the file.

Parameters

file – File handle returned from fat_Open.
block – Block offset into file.

Returns

FAT_SUCCESS on success, otherwise error.

uint24_t fat_GetPos(fat_file_t *file)

Gets the sector offset position in the file.

Parameters: file – File handle returned from fat_Open.
Returns: File block offset.

uint24_t fat_Read(fat_file_t *file, uint24_t count, void *buffer)

Read from a file.

Advances file block offset position.

Parameters

file – File handle returned from fat_Open.
count – Number of blocks to read.
buffer – Data read from FAT file.

Returns

Returns number of blocks read, should equal count if success.

uint24_t fat_Write(fat_file_t *file, uint24_t count, const void *buffer)

Write to a file.

Advances file block offset position.

Parameters

file – File handle returned from fat_Open.
count – Number of blocks to write to file.
buffer – Data to write to FAT file.

Returns

Returns number of blocks written, should equal count if success.

fat_error_t fat_Close(fat_file_t *file)

Closes an open file handle.

Parameters: file – File handle returned from fat_Open.
Returns: FAT_SUCCESS on success, otherwise error.

struct fat_t

Public Members

uint24_t (*read)(void *usr, uint32_t lba, uint24_t count, void *buffer): Callback for reading logical blocks.

uint24_t (*write)(void *usr, uint32_t lba, uint24_t count, const void *buffer): Callback for writing logical blocks.

void *usr

Pointer to user-provided data structure that is passed to the relevant read/write callback functions.

This can be used to store context information when working with different storage mechanisms.

uint32_t first_lba: First Logical Block Address (LBA) in the filesystem.

uint32_t last_lba: Last Logical Block Address (LBA) in the filesystem.

struct fat_file_t

struct fat_dir_entry_t

Public Members

char filename[13]: Name of file in 8.3 format.

uint8_t attrib: File attributes.

uint32_t size: Size of file in bytes.

fatdrvce.h

Typical Usage

Known Limitations

API Documentation

Typical Usage 

Known Limitations 

API Documentation 