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.

Physical Drive Usage
Known Limitations
General Information
API Documentation

Physical Drive 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 -F 32 -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.

General Information 

The root directory is /. For example, accessing the ROOT.BIN file in the root directory would look like fat_OpenFile(fat, "/ROOT.BIN", &file);.

API Documentation 

FAT Filesystem Driver.

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

Defines

FAT_BLOCK_SIZE: Block size in bytes.

fat_callback_usr_t

A pointer to fat_callback_usr_t is passed to the user provided callback functions for reading and writing.

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

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

Typedefs

typedef uint24_t (*fat_read_callback_t)(void *usr, uint32_t lba, uint24_t count, void *buffer)

Callback for reading logical blocks.

Param usr: [in] User defined data pointer.
Param lba: [in] Local block address (LBA) to read.
Param count: [in] Number of logical blocks to read.
Param buffer: [in] Buffer to store read data into.
Return: Number of logical blocks read.

typedef uint24_t (*fat_write_callback_t)(void *usr, uint32_t lba, uint24_t count, const void *buffer)

Callback for writing logical blocks.

Param usr: [in] User defined data pointer.
Param lba: [in] Local block address (LBA) to write.
Param count: [in] Number of logical blocks to write.
Param buffer: [in] Buffer to fetch write data from.
Return: Number of logical blocks written.

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_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 read or write callback failed (count != return)

enumerator FAT_ERROR_INVALID_FILESYSTEM: A non-FAT filesystem detected.

enumerator FAT_ERROR_INVALID_SIZE: An invalid size was detected.

enumerator FAT_ERROR_INVALID_MAGIC: Some invalid magic bytes were detected.

enumerator FAT_ERROR_INVALID_SIGNATURE: Some invalid signature was detected.

enumerator FAT_ERROR_NO_MORE_ENTRIES: No more entries in the directory.

enumerator FAT_ERROR_INVALID_NAME: An invalid filename was provided.

enum fat_file_attrib

Values:

enumerator FAT_RDONLY = (1 << 0): Entry is read-only.

enumerator FAT_HIDDEN = (1 << 1): Entry is hidden.

enumerator FAT_SYSTEM = (1 << 2): Entry is a system file / directory.

enumerator FAT_VOLLABEL = (1 << 3): Entry is a volume label.

enumerator FAT_DIR = (1 << 4): Entry is a directory (or subdirectory)

enumerator FAT_ARCHIVE = (1 << 5): Entry is changed (created/modified)

Functions

fat_error_t fat_Open(fat_t *fat, fat_read_callback_t read, fat_write_callback_t write, void *usr, const uint32_t base_lba)

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

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

Parameters

fat – [out] Uninitialized FAT structure type.
read – [in] Callback for reading logical blocks.
write – [in] Callback for writing logical blocks.
usr – [in] Pointer to user-provided data structure that is passed to the relevant read/write callback functions. This can be used to store context information with different storage mechanisms.
base_lba – [in] LBA added to every FAT access for ease of use.

Returns

FAT_SUCCESS on success, otherwise error.

fat_error_t fat_Close(fat_t *fat)

Closes 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_Open() if you need to modify the filesystem again.

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

fat_error_t fat_OpenDir(fat_t *fat, const char *path, fat_dir_t *dir)

Opens a directory for reading contents.

Parameters

fat – [in] Initialized FAT structure.
path – [in] Directory path to get list from.
dir – [out] Pointer to store opaque directory handle.

Returns

FAT_SUCCESS on success, otherwise error.

fat_error_t fat_ReadDir(fat_dir_t *dir, fat_dir_entry_t *entry)

Gets the next directory entry.

If entry.name[0] is 0, then there are no more entries to fetch.

Parameters

dir – [in] Initialized directory handle from fat_OpenDir().
entry – [out] Pointer to store entry information.

Returns

FAT_SUCCESS on success, otherwise error.

fat_error_t fat_CloseDir(fat_dir_t *dir)

Closes an open directory handle.

Parameters: dir – [in] Directory handle.
Returns: FAT_SUCCESS on success, otherwise error.

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

Returns the volume label of the drive if it exists.

Parameters

fat – [in] Initialized FAT structure type.
label – [out] 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 – [in] Initialized FAT structure.
path – [in] Path in which to create. Does not create subdirectories.
name – [in] Name of new file or directory.
attrib – [in] New entry attributes (fat_file_attrib mask).

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 – [in] Initialized FAT structure.
filepath – [in] 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 – [in] Initialized FAT structure.
filepath – [in] Absolute file path.
attrib – [in] FAT attributes to set file to (fat_file_attrib mask).

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 – [in] Initialized FAT structure.
filepath – [in] Absolute file path.

Returns

File attributes, or 255 if an error.

fat_error_t fat_OpenFile(fat_t *fat, const char *filepath, uint8_t flags, fat_file_t *file)

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

Parameters

fat – [in] Initialized FAT structure.
filepath – [in] Absolute file path.
flags – [in] File open flags (currently no flags available, set to 0)
file – [out] Uninitialized structure to store working file information.

Returns

FAT_SUCCESS on success, otherwise error.

fat_error_t fat_SetFileSize(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). This function may take a long time to run as it will allocate/deallocate the clusters required for storing to the file.

Note

This function always resets the block position to 0.

Parameters

file – [in] FAT file structure.
size – [in] New file size.

Returns

FAT_SUCCESS on success, otherwise error.

uint32_t fat_GetFileSize(fat_file_t *file)

Gets the size of a file.

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

fat_error_t fat_SetFileBlockOffset(fat_file_t *file, uint24_t block)

Sets the block offset position in the file.

Parameters

file – [in] File handle returned from fat_OpenFile().
block – [in] Block offset into file.

Returns

FAT_SUCCESS on success, otherwise error.

uint24_t fat_GetFileBlockOffset(fat_file_t *file)

Gets the sector offset position in the file.

Parameters: file – [in] File handle returned from fat_OpenFile().
Returns: File block offset.

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

Read from a file.

Advances file block offset position.

Parameters

file – [in] File handle returned from fat_OpenFile().
count – [in] Number of blocks to read.
buffer – [out] Data read from FAT file.

Returns

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

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

Write to a file.

Advances file block offset position. Does not extend file size if at last block in file, fat_SetFileSize() must be used instead.

Parameters

file – [in] File handle returned from fat_OpenFile().
count – [in] Number of blocks to write to file.
buffer – [in] Data to write to FAT file.

Returns

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

fat_error_t fat_CloseFile(fat_file_t *file)

Closes an open file handle.

Parameters: file – [in] File handle returned from fat_OpenFile().
Returns: FAT_SUCCESS on success, otherwise error.

struct fat_t: #include <fatdrvce.h>

FAT structure.

struct fat_file_t: #include <fatdrvce.h>

FAT file structure.

struct fat_dir_t: #include <fatdrvce.h>

FAT directory structure.

struct fat_dir_entry_t

#include <fatdrvce.h>

FAT directory entry structure.

Public Members

char name[13]: Name in 8.3 format.

uint8_t attrib

File attributes.

fatdrvce.h

Physical Drive Usage

Known Limitations

General Information

API Documentation

Physical Drive Usage 

Known Limitations 

General Information 

API Documentation 