fatfs/source/ff.h

   1 /*----------------------------------------------------------------------------/
   2 /  FatFs - Generic FAT Filesystem module  R0.13b                              /
   3 /-----------------------------------------------------------------------------/
   4 /
   5 / Copyright (C) 2018, ChaN, all right reserved.
   6 /
   7 / FatFs module is an open source software. Redistribution and use of FatFs in
   8 / source and binary forms, with or without modification, are permitted provided
   9 / that the following condition is met:
  10
  11 / 1. Redistributions of source code must retain the above copyright notice,
  12 /    this condition and the following disclaimer.
  13 /
  14 / This software is provided by the copyright holder and contributors "AS IS"
  15 / and any warranties related to this software are DISCLAIMED.
  16 / The copyright owner or contributors be NOT LIABLE for any damages caused
  17 / by use of this software.
  18 /
  19 /----------------------------------------------------------------------------*/
  20
  21
  22 #ifndef FF_DEFINED
  23 #define FF_DEFINED      63463   /* Revision ID */
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 #include "integer.h"    /* Basic integer types */
  30 #include "ffconf.h"             /* FatFs configuration options */
  31
  32 #if FF_DEFINED != FFCONF_DEF
  33 #error Wrong configuration file (ffconf.h).
  34 #endif
  35
  36
  37
  38 /* Definitions of volume management */
  39
  40 #if FF_MULTI_PARTITION          /* Multiple partition configuration */
  41 typedef struct {
  42         BYTE pd;        /* Physical drive number */
  43         BYTE pt;        /* Partition: 0:Auto detect, 1-4:Forced partition) */
  44 } PARTITION;
  45 extern PARTITION VolToPart[];   /* Volume - Partition resolution table */
  46 #endif
  47
  48 #if FF_STR_VOLUME_ID
  49 #ifndef FF_VOLUME_STRS
  50 extern const char* VolumeStr[FF_VOLUMES];       /* User defied volume ID */
  51 #endif
  52 #endif
  53
  54
  55
  56 /* Type of path name strings on FatFs API */
  57
  58 #ifndef _INC_TCHAR
  59 #define _INC_TCHAR
  60
  61 #if FF_USE_LFN && FF_LFN_UNICODE == 1   /* Unicode in UTF-16 encoding */
  62 typedef WCHAR TCHAR;
  63 #define _T(x) L ## x
  64 #define _TEXT(x) L ## x
  65 #elif FF_USE_LFN && FF_LFN_UNICODE == 2 /* Unicode in UTF-8 encoding */
  66 typedef char TCHAR;
  67 #define _T(x) u8 ## x
  68 #define _TEXT(x) u8 ## x
  69 #elif FF_USE_LFN && FF_LFN_UNICODE == 3 /* Unicode in UTF-32 encoding */
  70 typedef DWORD TCHAR;
  71 #define _T(x) U ## x
  72 #define _TEXT(x) U ## x
  73 #elif FF_USE_LFN && (FF_LFN_UNICODE < 0 || FF_LFN_UNICODE > 3)
  74 #error Wrong FF_LFN_UNICODE setting
  75 #else                                                                   /* ANSI/OEM code in SBCS/DBCS */
  76 typedef char TCHAR;
  77 #define _T(x) x
  78 #define _TEXT(x) x
  79 #endif
  80
  81 #endif
  82
  83
  84
  85 /* Type of file size variables */
  86
  87 #if FF_FS_EXFAT
  88 typedef QWORD FSIZE_t;
  89 #else
  90 typedef DWORD FSIZE_t;
  91 #endif
  92
  93
  94
  95 /* Filesystem object structure (FATFS) */
  96
  97 typedef struct {
  98         BYTE    fs_type;                /* Filesystem type (0:N/A) */
  99         BYTE    pdrv;                   /* Physical drive number */
 100         BYTE    n_fats;                 /* Number of FATs (1 or 2) */
 101         BYTE    wflag;                  /* win[] flag (b0:dirty) */
 102         BYTE    fsi_flag;               /* FSINFO flags (b7:disabled, b0:dirty) */
 103         WORD    id;                             /* Volume mount ID */
 104         WORD    n_rootdir;              /* Number of root directory entries (FAT12/16) */
 105         WORD    csize;                  /* Cluster size [sectors] */
 106 #if FF_MAX_SS != FF_MIN_SS
 107         WORD    ssize;                  /* Sector size (512, 1024, 2048 or 4096) */
 108 #endif
 109 #if FF_USE_LFN
 110         WCHAR*  lfnbuf;                 /* LFN working buffer */
 111 #endif
 112 #if FF_FS_EXFAT
 113         BYTE*   dirbuf;                 /* Directory entry block scratchpad buffer for exFAT */
 114 #endif
 115 #if FF_FS_REENTRANT
 116         FF_SYNC_t       sobj;           /* Identifier of sync object */
 117 #endif
 118 #if !FF_FS_READONLY
 119         DWORD   last_clst;              /* Last allocated cluster */
 120         DWORD   free_clst;              /* Number of free clusters */
 121 #endif
 122 #if FF_FS_RPATH
 123         DWORD   cdir;                   /* Current directory start cluster (0:root) */
 124 #if FF_FS_EXFAT
 125         DWORD   cdc_scl;                /* Containing directory start cluster (invalid when cdir is 0) */
 126         DWORD   cdc_size;               /* b31-b8:Size of containing directory, b7-b0: Chain status */
 127         DWORD   cdc_ofs;                /* Offset in the containing directory (invalid when cdir is 0) */
 128 #endif
 129 #endif
 130         DWORD   n_fatent;               /* Number of FAT entries (number of clusters + 2) */
 131         DWORD   fsize;                  /* Size of an FAT [sectors] */
 132         DWORD   volbase;                /* Volume base sector */
 133         DWORD   fatbase;                /* FAT base sector */
 134         DWORD   dirbase;                /* Root directory base sector/cluster */
 135         DWORD   database;               /* Data base sector */
 136         DWORD   winsect;                /* Current sector appearing in the win[] */
 137         BYTE    win[FF_MAX_SS]; /* Disk access window for Directory, FAT (and file data at tiny cfg) */
 138 } FATFS;
 139
 140
 141
 142 /* Object ID and allocation information (FFOBJID) */
 143
 144 typedef struct {
 145         FATFS*  fs;                             /* Pointer to the hosting volume of this object */
 146         WORD    id;                             /* Hosting volume mount ID */
 147         BYTE    attr;                   /* Object attribute */
 148         BYTE    stat;                   /* Object chain status (b1-0: =0:not contiguous, =2:contiguous, =3:flagmented in this session, b2:sub-directory stretched) */
 149         DWORD   sclust;                 /* Object data start cluster (0:no cluster or root directory) */
 150         FSIZE_t objsize;                /* Object size (valid when sclust != 0) */
 151 #if FF_FS_EXFAT
 152         DWORD   n_cont;                 /* Size of first fragment - 1 (valid when stat == 3) */
 153         DWORD   n_frag;                 /* Size of last fragment needs to be written to FAT (valid when not zero) */
 154         DWORD   c_scl;                  /* Containing directory start cluster (valid when sclust != 0) */
 155         DWORD   c_size;                 /* b31-b8:Size of containing directory, b7-b0: Chain status (valid when c_scl != 0) */
 156         DWORD   c_ofs;                  /* Offset in the containing directory (valid when file object and sclust != 0) */
 157 #endif
 158 #if FF_FS_LOCK
 159         UINT    lockid;                 /* File lock ID origin from 1 (index of file semaphore table Files[]) */
 160 #endif
 161 } FFOBJID;
 162
 163
 164
 165 /* File object structure (FIL) */
 166
 167 typedef struct {
 168         FFOBJID obj;                    /* Object identifier (must be the 1st member to detect invalid object pointer) */
 169         BYTE    flag;                   /* File status flags */
 170         BYTE    err;                    /* Abort flag (error code) */
 171         FSIZE_t fptr;                   /* File read/write pointer (Zeroed on file open) */
 172         DWORD   clust;                  /* Current cluster of fpter (invalid when fptr is 0) */
 173         DWORD   sect;                   /* Sector number appearing in buf[] (0:invalid) */
 174 #if !FF_FS_READONLY
 175         DWORD   dir_sect;               /* Sector number containing the directory entry (not used at exFAT) */
 176         BYTE*   dir_ptr;                /* Pointer to the directory entry in the win[] (not used at exFAT) */
 177 #endif
 178 #if FF_USE_FASTSEEK
 179         DWORD*  cltbl;                  /* Pointer to the cluster link map table (nulled on open, set by application) */
 180 #endif
 181 #if !FF_FS_TINY
 182         BYTE    buf[FF_MAX_SS]; /* File private data read/write window */
 183 #endif
 184 } FIL;
 185
 186
 187
 188 /* Directory object structure (DIR) */
 189
 190 typedef struct {
 191         FFOBJID obj;                    /* Object identifier */
 192         DWORD   dptr;                   /* Current read/write offset */
 193         DWORD   clust;                  /* Current cluster */
 194         DWORD   sect;                   /* Current sector (0:Read operation has terminated) */
 195         BYTE*   dir;                    /* Pointer to the directory item in the win[] */
 196         BYTE    fn[12];                 /* SFN (in/out) {body[8],ext[3],status[1]} */
 197 #if FF_USE_LFN
 198         DWORD   blk_ofs;                /* Offset of current entry block being processed (0xFFFFFFFF:Invalid) */
 199 #endif
 200 #if FF_USE_FIND
 201         const TCHAR* pat;               /* Pointer to the name matching pattern */
 202 #endif
 203 } DIR;
 204
 205
 206
 207 /* File information structure (FILINFO) */
 208
 209 typedef struct {
 210         FSIZE_t fsize;                  /* File size */
 211         WORD    fdate;                  /* Modified date */
 212         WORD    ftime;                  /* Modified time */
 213         BYTE    fattrib;                /* File attribute */
 214 #if FF_USE_LFN
 215         TCHAR   altname[FF_SFN_BUF + 1];/* Altenative file name */
 216         TCHAR   fname[FF_LFN_BUF + 1];  /* Primary file name */
 217 #else
 218         TCHAR   fname[12 + 1];  /* File name */
 219 #endif
 220 } FILINFO;
 221
 222
 223
 224 /* File function return code (FRESULT) */
 225
 226 typedef enum {
 227         FR_OK = 0,                              /* (0) Succeeded */
 228         FR_DISK_ERR,                    /* (1) A hard error occurred in the low level disk I/O layer */
 229         FR_INT_ERR,                             /* (2) Assertion failed */
 230         FR_NOT_READY,                   /* (3) The physical drive cannot work */
 231         FR_NO_FILE,                             /* (4) Could not find the file */
 232         FR_NO_PATH,                             /* (5) Could not find the path */
 233         FR_INVALID_NAME,                /* (6) The path name format is invalid */
 234         FR_DENIED,                              /* (7) Access denied due to prohibited access or directory full */
 235         FR_EXIST,                               /* (8) Access denied due to prohibited access */
 236         FR_INVALID_OBJECT,              /* (9) The file/directory object is invalid */
 237         FR_WRITE_PROTECTED,             /* (10) The physical drive is write protected */
 238         FR_INVALID_DRIVE,               /* (11) The logical drive number is invalid */
 239         FR_NOT_ENABLED,                 /* (12) The volume has no work area */
 240         FR_NO_FILESYSTEM,               /* (13) There is no valid FAT volume */
 241         FR_MKFS_ABORTED,                /* (14) The f_mkfs() aborted due to any problem */
 242         FR_TIMEOUT,                             /* (15) Could not get a grant to access the volume within defined period */
 243         FR_LOCKED,                              /* (16) The operation is rejected according to the file sharing policy */
 244         FR_NOT_ENOUGH_CORE,             /* (17) LFN working buffer could not be allocated */
 245         FR_TOO_MANY_OPEN_FILES, /* (18) Number of open files > FF_FS_LOCK */
 246         FR_INVALID_PARAMETER    /* (19) Given parameter is invalid */
 247 } FRESULT;
 248
 249
 250
 251 /*--------------------------------------------------------------*/
 252 /* FatFs module application interface                           */
 253
 254 FRESULT f_open (FIL* fp, const TCHAR* path, BYTE mode);                         /* Open or create a file */
 255 FRESULT f_close (FIL* fp);                                                                                      /* Close an open file object */
 256 FRESULT f_read (FIL* fp, void* buff, UINT btr, UINT* br);                       /* Read data from the file */
 257 FRESULT f_write (FIL* fp, const void* buff, UINT btw, UINT* bw);        /* Write data to the file */
 258 FRESULT f_lseek (FIL* fp, FSIZE_t ofs);                                                         /* Move file pointer of the file object */
 259 FRESULT f_truncate (FIL* fp);                                                                           /* Truncate the file */
 260 FRESULT f_sync (FIL* fp);                                                                                       /* Flush cached data of the writing file */
 261 FRESULT f_opendir (DIR* dp, const TCHAR* path);                                         /* Open a directory */
 262 FRESULT f_closedir (DIR* dp);                                                                           /* Close an open directory */
 263 FRESULT f_readdir (DIR* dp, FILINFO* fno);                                                      /* Read a directory item */
 264 FRESULT f_findfirst (DIR* dp, FILINFO* fno, const TCHAR* path, const TCHAR* pattern);   /* Find first file */
 265 FRESULT f_findnext (DIR* dp, FILINFO* fno);                                                     /* Find next file */
 266 FRESULT f_mkdir (const TCHAR* path);                                                            /* Create a sub directory */
 267 FRESULT f_unlink (const TCHAR* path);                                                           /* Delete an existing file or directory */
 268 FRESULT f_rename (const TCHAR* path_old, const TCHAR* path_new);        /* Rename/Move a file or directory */
 269 FRESULT f_stat (const TCHAR* path, FILINFO* fno);                                       /* Get file status */
 270 FRESULT f_chmod (const TCHAR* path, BYTE attr, BYTE mask);                      /* Change attribute of a file/dir */
 271 FRESULT f_utime (const TCHAR* path, const FILINFO* fno);                        /* Change timestamp of a file/dir */
 272 FRESULT f_chdir (const TCHAR* path);                                                            /* Change current directory */
 273 FRESULT f_chdrive (const TCHAR* path);                                                          /* Change current drive */
 274 FRESULT f_getcwd (TCHAR* buff, UINT len);                                                       /* Get current directory */
 275 FRESULT f_getfree (const TCHAR* path, DWORD* nclst, FATFS** fatfs);     /* Get number of free clusters on the drive */
 276 FRESULT f_getlabel (const TCHAR* path, TCHAR* label, DWORD* vsn);       /* Get volume label */
 277 FRESULT f_setlabel (const TCHAR* label);                                                        /* Set volume label */
 278 FRESULT f_forward (FIL* fp, UINT(*func)(const BYTE*,UINT), UINT btf, UINT* bf); /* Forward data to the stream */
 279 FRESULT f_expand (FIL* fp, FSIZE_t szf, BYTE opt);                                      /* Allocate a contiguous block to the file */
 280 FRESULT f_mount (FATFS* fs, const TCHAR* path, BYTE opt);                       /* Mount/Unmount a logical drive */
 281 FRESULT f_mkfs (const TCHAR* path, BYTE opt, DWORD au, void* work, UINT len);   /* Create a FAT volume */
 282 FRESULT f_fdisk (BYTE pdrv, const DWORD* szt, void* work);                      /* Divide a physical drive into some partitions */
 283 FRESULT f_setcp (WORD cp);                                                                                      /* Set current code page */
 284 int f_putc (TCHAR c, FIL* fp);                                                                          /* Put a character to the file */
 285 int f_puts (const TCHAR* str, FIL* cp);                                                         /* Put a string to the file */
 286 int f_printf (FIL* fp, const TCHAR* str, ...);                                          /* Put a formatted string to the file */
 287 TCHAR* f_gets (TCHAR* buff, int len, FIL* fp);                                          /* Get a string from the file */
 288
 289 #define f_eof(fp) ((int)((fp)->fptr == (fp)->obj.objsize))
 290 #define f_error(fp) ((fp)->err)
 291 #define f_tell(fp) ((fp)->fptr)
 292 #define f_size(fp) ((fp)->obj.objsize)
 293 #define f_rewind(fp) f_lseek((fp), 0)
 294 #define f_rewinddir(dp) f_readdir((dp), 0)
 295 #define f_rmdir(path) f_unlink(path)
 296 #define f_unmount(path) f_mount(0, path, 0)
 297
 298 #ifndef EOF
 299 #define EOF (-1)
 300 #endif
 301
 302
 303
 304
 305 /*--------------------------------------------------------------*/
 306 /* Additional user defined functions                            */
 307
 308 /* RTC function */
 309 #if !FF_FS_READONLY && !FF_FS_NORTC
 310 DWORD get_fattime (void);
 311 #endif
 312
 313 /* LFN support functions */
 314 #if FF_USE_LFN >= 1                                             /* Code conversion (defined in unicode.c) */
 315 WCHAR ff_oem2uni (WCHAR oem, WORD cp);  /* OEM code to Unicode conversion */
 316 WCHAR ff_uni2oem (DWORD uni, WORD cp);  /* Unicode to OEM code conversion */
 317 DWORD ff_wtoupper (DWORD uni);                  /* Unicode upper-case conversion */
 318 #endif
 319 #if FF_USE_LFN == 3                                             /* Dynamic memory allocation */
 320 void* ff_memalloc (UINT msize);                 /* Allocate memory block */
 321 void ff_memfree (void* mblock);                 /* Free memory block */
 322 #endif
 323
 324 /* Sync functions */
 325 #if FF_FS_REENTRANT
 326 int ff_cre_syncobj (BYTE vol, FF_SYNC_t* sobj); /* Create a sync object */
 327 int ff_req_grant (FF_SYNC_t sobj);              /* Lock sync object */
 328 void ff_rel_grant (FF_SYNC_t sobj);             /* Unlock sync object */
 329 int ff_del_syncobj (FF_SYNC_t sobj);    /* Delete a sync object */
 330 #endif
 331
 332
 333
 334
 335 /*--------------------------------------------------------------*/
 336 /* Flags and offset address                                     */
 337
 338
 339 /* File access mode and open method flags (3rd argument of f_open) */
 340 #define FA_READ                         0x01
 341 #define FA_WRITE                        0x02
 342 #define FA_OPEN_EXISTING        0x00
 343 #define FA_CREATE_NEW           0x04
 344 #define FA_CREATE_ALWAYS        0x08
 345 #define FA_OPEN_ALWAYS          0x10
 346 #define FA_OPEN_APPEND          0x30
 347
 348 /* Fast seek controls (2nd argument of f_lseek) */
 349 #define CREATE_LINKMAP  ((FSIZE_t)0 - 1)
 350
 351 /* Format options (2nd argument of f_mkfs) */
 352 #define FM_FAT          0x01
 353 #define FM_FAT32        0x02
 354 #define FM_EXFAT        0x04
 355 #define FM_ANY          0x07
 356 #define FM_SFD          0x08
 357
 358 /* Filesystem type (FATFS.fs_type) */
 359 #define FS_FAT12        1
 360 #define FS_FAT16        2
 361 #define FS_FAT32        3
 362 #define FS_EXFAT        4
 363
 364 /* File attribute bits for directory entry (FILINFO.fattrib) */
 365 #define AM_RDO  0x01    /* Read only */
 366 #define AM_HID  0x02    /* Hidden */
 367 #define AM_SYS  0x04    /* System */
 368 #define AM_DIR  0x10    /* Directory */
 369 #define AM_ARC  0x20    /* Archive */
 370
 371
 372 #ifdef __cplusplus
 373 }
 374 #endif
 375
 376 #endif /* FF_DEFINED */