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