STM32 HAL FATFS Library - GitMasterNikanjam/ARM_WiKi GitHub Wiki

The FATFS library is a generic FAT file system module for embedded systems, widely used with STM32 microcontrollers and other platforms. It supports FAT12, FAT16, FAT32, and exFAT file systems, making it suitable for SD cards, USB drives, and other storage media.

Here’s an overview of the key FATFS library functions and their purposes:

Core FATFS Functions

1. Mounting and Unmounting

f_mount()

Mounts a logical drive.

FRESULT f_mount(FATFS *fs, const TCHAR *path, BYTE opt);
  • Parameters:
    • fs: Pointer to a FATFS structure for the file system object.
    • path: Logical drive path (e.g., "0:").
    • opt: Mount option (0 for lazy mount, 1 for immediate).
  • Returns: FR_OK on success.

f_unmount()

Unmounts a logical drive (alias for f_mount() with NULL for the file system object).

FRESULT f_mount(NULL, const TCHAR *path, BYTE opt);

2. File Operations

f_open()

Opens or creates a file.

FRESULT f_open(FIL *fp, const TCHAR *path, BYTE mode);
  • Parameters:
    • fp: Pointer to a FIL structure for the file object.
    • path: File path (e.g., "file.txt").
    • mode: Access mode (FA_READ, FA_WRITE, etc.).
  • Returns: FR_OK on success.

f_close()

Closes an open file.

FRESULT f_close(FIL *fp);

f_read()

Reads data from a file.

FRESULT f_read(FIL *fp, void *buff, UINT btr, UINT *br);
  • Parameters:
    • fp: Pointer to the open file object.
    • buff: Buffer to store read data.
    • btr: Number of bytes to read.
    • br: Actual number of bytes read.
  • Returns: FR_OK on success.

f_write()

Writes data to a file.

FRESULT f_write(FIL *fp, const void *buff, UINT btw, UINT *bw);
  • Parameters:
    • fp: Pointer to the open file object.
    • buff: Buffer containing data to write.
    • btw: Number of bytes to write.
    • bw: Actual number of bytes written.
  • Returns: FR_OK on success.

f_lseek()

Moves the file pointer to a specific position.

FRESULT f_lseek(FIL *fp, FSIZE_t ofs);
  • Parameters:
    • fp: Pointer to the open file object.
    • ofs: File pointer position (offset in bytes).
  • Returns: FR_OK on success.

f_truncate()

Truncates the file at the current file pointer position.

FRESULT f_truncate(FIL *fp);

3. Directory Operations

f_opendir()

Opens a directory for reading.

FRESULT f_opendir(DIR *dp, const TCHAR *path);
  • Parameters:
    • dp: Pointer to a DIR structure for the directory object.
    • path: Directory path (e.g., "0:/folder").
  • Returns: FR_OK on success.

f_readdir()

Reads a directory entry.

FRESULT f_readdir(DIR *dp, FILINFO *fno);
  • Parameters:
    • dp: Pointer to the open directory object.
    • fno: Pointer to a FILINFO structure to store file information.
  • Returns: FR_OK on success.

f_mkdir()

Creates a new directory.

FRESULT f_mkdir(const TCHAR *path);

4. File/Directory Management

f_unlink()

Deletes a file or directory.

FRESULT f_unlink(const TCHAR *path);

f_rename()

Renames or moves a file or directory.

FRESULT f_rename(const TCHAR *oldpath, const TCHAR *newpath);

f_stat()

Gets file or directory status.

FRESULT f_stat(const TCHAR *path, FILINFO *fno);
  • Returns: File size, date/time, attributes, etc.

5. Disk Operations

f_sync()

Flushes cached data of an open file to the storage device.

FRESULT f_sync(FIL *fp);

f_getfree()

Gets free space on the storage device.

FRESULT f_getfree(const TCHAR *path, DWORD *nclst, FATFS **fatfs);
  • Returns: Number of free clusters (nclst) and file system object (fatfs).

f_chdrive()

Changes the current drive.

FRESULT f_chdrive(const TCHAR *path);

f_chdir()

Changes the current directory.

FRESULT f_chdir(const TCHAR *path);

f_getcwd()

Gets the current directory path.

FRESULT f_getcwd(TCHAR *buff, UINT len);

FATFS Configuration Options

You can customize FATFS behavior through ffconf.h:

  • FF_MAX_SS: Maximum sector size.
  • FF_FS_LOCK: Maximum simultaneous open files/directories.
  • FF_USE_FASTSEEK: Enable fast seek support.
  • FF_USE_LFN: Enable long file name support.
  • FF_CODE_PAGE: Character encoding.

Return Values

All functions return an FRESULT status code:

  • FR_OK: Success.
  • FR_NO_FILE: File not found.
  • FR_NO_PATH: Path not found.
  • FR_DISK_ERR: Disk I/O error.
  • FR_NOT_READY: Storage device not ready.

By using these functions, you can efficiently manage files and directories on storage media with the FATFS library in STM32.