Download UM02001_emFile

676 Pages·2017·3.29 MB·English

emFile
CPU-independent file system
for embedded applications
User Guide & Reference Manual
Document: UM02001
Software Version: 5.20.0
Revision: 0
Date: November 15, 2022

A product of SEGGER Microcontroller GmbH
www.segger.com
2
Disclaimer
The information written in this document is assumed to be accurate without guarantee. The
information in this manual is subject to change for functional or performance improvements
without notice. SEGGER Microcontroller GmbH (SEGGER) assumes no responsibility for any errors
or omissions in this document. SEGGER disclaims any warranties or conditions, express, implied
or statutory for the fitness of the product for a particular purpose. It is your sole responsibility
to evaluate the fitness of the product for any specific use.
Copyright notice
You may not extract portions of this manual or modify the PDF file in any way without the prior
written permission of SEGGER. The software described in this document is furnished under a
license and may only be used or copied in accordance with the terms of such a license.
© 2002-2022 SEGGER Microcontroller GmbH, Monheim am Rhein / Germany
Trademarks
Names mentioned in this manual may be trademarks of their respective companies.
Brand and product names are trademarks or registered trademarks of their respective holders.
Contact address
SEGGER Microcontroller GmbH
Ecolab-Allee 5
D-40789 Monheim am Rhein
Germany
Tel. [phone]
Fax. [phone]
E-mail: [email protected]*
Internet: www.segger.com
*By sending us an email your (personal) data will automatically be processed. For further information please refer to our
privacy policy which is available at https://www.segger.com/legal/privacy-policy/.
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
3
Manual versions
This manual describes the current software version. If any error occurs, inform us and we will
try to assist you as soon as possible. Contact us for further information on topics or routines
not yet specified.
Print date: November 15, 2022
Software Revision Date By Description
Updated the list of supported NOR flash devices.
Added section for partitioning functions.
Updated the list of supported NAND flash devices.
Added FS_FGets() function.
Added FS_CreateGPT() function.
Added FS_SUPPORT_GPT configuration define.
Added FS_GetPartitioningScheme() function.
Added FS_GetGPTInfo() function.
5.20.0 0 221114 MD Added FS_GPT_INFO structure.
Added FS_GetPartitionInfoGPT() function.
Added FS_PARTITION_INFO_GPT structure.
Renamed FS_GetPartitionInfo() function to FS_GetPartitionInfoM-
BR()
Renamed FS_PARTITION_INFO structure to FS_PARTITION_INFO_MBR.
Added FS_SUPPORT_SECTOR_BUFFER_BURST configuration define.
Added FS_MMC_DISABLE_DAT3_PULLUP configuration define.
Added missing configuration defines for Card Mode MMC/SD driver.
Added FS_MMC_CM_AllowCacheActivation() function.
Added FS_NOR_SPIFI_AllowDTRMode() function.
Added FS_NOR_HW_TYPE_SPIFI_MAP_EX, FS_NOR_HW_TYPE_SPIFI_MAP_EX,
5.18.0 0 220727 MD FS_NOR_HW_TYPE_SPIFI_READ_EX, FS_NOR_HW_TYPE_SPIFI_WRITE_EX and
FS_NOR_HW_TYPE_SPIFI_POLL_EX functions.
Added FS_NOR_SPIFI_AllowOctalMode() function.
Updated the list of supported NOR flash devices.
5.16.2 0 220725 MD Changed the name of BigFile component to BigFAT.
Added sample for disk checking in the background.
Added FS_FPuts() function.
Added FS_NAND_UNI_SetMaxPageSize() function.
Added FS_NAND_UNI_SetMaxSpareAreaSize() function.
Added FS_FPrintf() function.
Added FS_OPTIMIZATION_TYPE configuration define.
5.16.0 0 220428 MD
Added extended the Storage layer API.
Updated the list of supported NAND flash devices.
Added FS_NOR_ErasePhySector() function.
Added FS_NOR_WriteOff() function.
Added FS_NOR_OPTIMIZE_DATA_WRITE configuration define.
Added FS_NOR_SUPPORT_TRIM configuration define.
Added FS_NOR_HW_TYPE_SPI_READ_EX and FS_NOR_HW_TYPE_SPI_WRITE_EX
functions.
Added FS_FAT_CHECK_UNUSED_DIR_ENTRIES configuration define.
Added FS_BIGFILE_CheckDisk() function.
Updated the list of supported NOR flash devices.
5.14.0 0 220307 MD
Added FS_NAND_2048X8_SetDeviceList() function.
Added FS_MMC_GetCardInfo() function.
Updated the list of supported NAND flash devices.
Added FS_JOURNAL_OPTIMIZE_SPACE_USAGE configuration define.
Added FS_NOR_SUPPORT_FORMAT configuration define.
Added FS_FAT_GetLFNConverter() function.
Updated the list of features.
Added FS_GetAutoMount() function.
5.12.0 0 211130 MD
Added FS_FAT_GetConfig() function.
Added FS_EFS_GetConfig() function.
Added FS_NOR_SPIFI_ExecCmd() function.
Updated the list of supported NAND flash devices.
5.10.0 0 210824 MD
Added setnumworkblocks command to NOR Image Creator.
Added FS_NAND_QSPI_SetDeviceList() function.
Added information about the compile time and runtime configuration of the
5.8.1 0 210618 MD
NAND physical layers.
Added information about resource usage of NAND physical layers.
5.8.0 0 210517 MD Added FS_CACHE_GetType() function.
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
4
Software Revision Date By Description
Added FS_NAND_UNI_GetBlockInfoEx() function.
Added FS_NAND_ONFI_SetDeviceList() function.
Updated the list of supported NOR flash devices.
Updated the list of supported NAND flash devices.
Added information about the compile time configuration of the NOR physi-
cal layers.
Added information about creating a custom device or logical driver.
Updated the list of file system configuration defines.
Added FS_NOR_BM_Mount() function.
Added FS_MMC_CM_SetDriverStrength() function.
Added information about the compile time configuration of the Block Map
NOR driver.
Added information about the compile time configuration of the Sector Map
NOR driver.
Updated the list of supported NOR flash devices.
5.6.0 0 210127 MD Added FS_NOR_BM_EnableECC() function.
Added FS_NOR_BM_DisableECC() function.
Added FS_NOR_BM_SetECCHook() function.
Added FS_NOR_BM_IsECCEnabled() function.
Added FS_NOR_ECC_HOOK structure.
Added FS_NOR_ECC_HOOK_CALC function.
Added FS_NOR_ECC_HOOK_APPLY function.
Improved the section about the RAM usage of the file system.
Added FS_GetVolumeAlias() function.
Added FS_NOR_SFDP_Configure() function.
Added FS_MMC_CM_AllowAccessModeDDR50() function.
Added FS_MMC_CM_AllowAccessModeHS200() function.
Added FS_MMC_CM_AllowAccessModeHS400() function.
Added FS_MMC_CM_AllowAccessModeHS_DDR() function.
Added FS_MMC_CM_AllowAccessModeSDR104() function.
5.4.0 0 201029 MD
Added FS_MMC_CM_AllowAccessModeSDR50() function.
Added FS_MMC_CM_AllowVoltageLevel1V8() function.
Added FS_MMC_CM_SetHS200Tuning() function.
Added FS_MMC_CM_SetSDR104Tuning() function.
Added FS_MMC_CM_SetSDR50Tuning() function.
Added information about the compile time configuration of the Card Mode
MMC/SD driver.
5.2.0 1 200630 MD Added FS_NAND_UNI_Mount() function.
Improved wording of the FAQs chapter.
5.2.0 0 200527 MD Added description of the BigFileMerger utility.
Added FS_NOR_BM_SetInvalidSectorError() function.
5.1.0 1 200411 MD Updated the resource usage of EFS.
Added FS_GetMountType() function.
Added FS_NOR_SPIFI_SetSectorSize() function.
Updated the list of supported NOR flash devices.
Added FS_EFS_SUPPORT_FREE_CLUSTER_CACHE configuration define.
5.1.0 0 200504 MD Added FS_SUPPORT_SECTOR_BUFFER_CACHE configuration define.
Added FS_GetMemInfo() function.
Added more information about the fail-safety of the NOR drivers.
Added compile time configuration information for the Block Map NOR dri-
ver.
5.0.1 1 200317 MD Corrected a sample.
5.0.1 0 200316 MD Corrected structure member names.
5.0.0 0 200301 MD Reworked version of the manual.
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
5
About this document
Assumptions
This document assumes that you already have a solid knowledge of the following:
• The software tools used for building your application (assembler, linker, C compiler).
• The C programming language.
• The target processor.
• DOS command line.
If you feel that your knowledge of C is not sufficient, we recommend The C Programming Lan-
guage by Kernighan and Richie (ISBN 0--13--1103628), which describes the standard in C pro-
gramming and, in newer editions, also covers the ANSI C standard.
How to use this manual
This manual explains all the functions and macros that the product offers. It assumes you have
a working knowledge of the C language. Knowledge of assembly programming is not required.
Typographic conventions for syntax
This manual uses the following typographic conventions:
Style Used for
Body Body text.
Text that you enter at the command prompt or that appears on
Keyword
the display (that is system functions, file- or pathnames).
Parameter Parameters in API functions.
Sample Sample code in program examples.
Sample comment Comments in program examples.
Reference to chapters, sections, tables and figures or other doc-
Reference
uments.
GUIElement Buttons, dialog boxes, menu names, menu commands.
Emphasis Very important sections.
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
6
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
7
Table of contents
1 Introduction to emFile .................................................................................................30
1.1 What is emFile ............................................................................................ 31
1.2 Features ......................................................................................................32
1.3 Basic concepts .............................................................................................33
1.3.1 emFile structure ................................................................................33
1.3.1.1 API layer ...............................................................................34
1.3.1.2 File system layer ....................................................................34
1.3.1.3 Storage layer .........................................................................34
1.3.1.4 Driver layer ...........................................................................34
1.3.1.5 Hardware layer ......................................................................34
1.3.2 Choice of file system type: FAT vs. EFS ............................................... 34
1.3.3 Fail safety ........................................................................................35
1.3.4 Wear leveling ....................................................................................35
1.4 Implementation notes ...................................................................................36
1.4.1 File system configuration ................................................................... 36
1.4.2 Runtime memory requirements ...........................................................36
1.4.3 Initializing the file system ..................................................................36
1.4.4 Development environment (compiler) ..................................................36
2 Getting started ............................................................................................................37
2.1 Package content and installation ....................................................................38
2.2 Using the Windows sample application ............................................................39
2.2.1 Building the sample application ...........................................................39
2.2.2 Overview of the sample application .....................................................39
2.2.3 Stepping through the sample application ..............................................40
2.3 Further source code examples .......................................................................45
2.4 Recommended project structure .....................................................................46
3 Running emFile on target hardware ...........................................................................47
3.1 Integrating emFile ........................................................................................48
3.2 Procedure to follow ......................................................................................49
3.3 Step 1: Creating a simple project without emFile .............................................50
3.4 Step 2: Adding emFile to the start project ......................................................51
3.4.1 Configuring the include path ...............................................................51
3.4.2 Select the start application .................................................................52
3.4.3 Build the project and test it ............................................................... 52
3.5 Step 3: Adding the device driver ................................................................... 53
3.5.1 Adding the device driver source to project ........................................... 53
3.5.2 Adding hardware routines to project ....................................................54
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
8
3.6 Step 4: Activating the driver .........................................................................55
3.6.1 Modifying the runtime configuration .....................................................55
3.7 Step 5: Adjusting the RAM usage .................................................................. 58
4 API functions ...............................................................................................................59
4.1 General information ......................................................................................60
4.1.1 Volume, file and directory names ........................................................60
4.2 API function overview ...................................................................................61
4.3 File system control functions .........................................................................68
4.3.1 FS_Init() ..........................................................................................69
4.3.2 FS_DeInit() ......................................................................................70
4.3.3 FS_Mount() ......................................................................................71
4.3.4 FS_MountEx() ...................................................................................72
4.3.5 FS_SetAutoMount() ...........................................................................73
4.3.6 FS_Sync() ........................................................................................74
4.3.7 FS_Unmount() ..................................................................................75
4.3.8 FS_UnmountForced() .........................................................................76
4.3.9 Volume mounting modes ....................................................................77
4.4 File system configuration functions .................................................................78
4.4.1 FS_AddDevice() ................................................................................79
4.4.2 FS_AddPhysDevice() ..........................................................................80
4.4.3 FS_AssignMemory() ...........................................................................81
4.4.4 FS_ConfigFileBufferDefault() ...............................................................82
4.4.5 FS_LOGVOL_Create() .........................................................................83
4.4.6 FS_LOGVOL_AddDevice() ...................................................................84
4.4.7 FS_SetFileBufferFlags() ......................................................................85
4.4.8 FS_SetFileBufferFlagsEx() ...................................................................86
4.4.9 FS_SetFileWriteMode() .......................................................................87
4.4.10 FS_SetFileWriteModeEx() ..................................................................88
4.4.11 FS_SetMemHandler() .......................................................................89
4.4.12 FS_SetMaxSectorSize() .................................................................... 90
4.4.13 FS_MEM_ALLOC_CALLBACK ..............................................................91
4.4.14 FS_MEM_FREE_CALLBACK ................................................................92
4.4.15 FS_WRITEMODE ..............................................................................93
4.5 File access functions .....................................................................................94
4.5.1 FS_FClose() ......................................................................................95
4.5.2 FS_FGets() .......................................................................................96
4.5.3 FS_FOpen() ......................................................................................97
4.5.4 FS_FOpenEx() ...................................................................................99
4.5.5 FS_FPrintf() ....................................................................................100
4.5.6 FS_FPuts() ......................................................................................101
4.5.7 FS_FRead() .....................................................................................102
4.5.8 FS_FSeek() .....................................................................................103
4.5.9 FS_FWrite() ....................................................................................105
4.5.10 FS_FTell() .....................................................................................106
4.5.11 FS_GetFileSize() ............................................................................107
4.5.12 FS_Read() .................................................................................... 108
4.5.13 FS_SetEndOfFile() ..........................................................................109
4.5.14 FS_SetFileSize() ............................................................................110
4.5.15 FS_SyncFile() ................................................................................111
4.5.16 FS_Truncate() ............................................................................... 112
4.5.17 FS_Verify() ................................................................................... 113
4.5.18 FS_Write() ....................................................................................114
4.5.19 File positioning reference ................................................................115
4.6 Operations on files .....................................................................................116
4.6.1 FS_CopyFile() ................................................................................. 117
4.6.2 FS_CopyFileEx() ..............................................................................118
4.6.3 FS_GetFileAttributes() ......................................................................119
4.6.4 FS_GetFileInfo() ..............................................................................120
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
9
4.6.5 FS_GetFileTime() .............................................................................121
4.6.6 FS_GetFileTimeEx() ..........................................................................122
4.6.7 FS_ModifyFileAttributes() ..................................................................123
4.6.8 FS_Move() ......................................................................................125
4.6.9 FS_Remove() ..................................................................................127
4.6.10 FS_Rename() ................................................................................128
4.6.11 FS_SetFileAttributes() .................................................................... 129
4.6.12 FS_SetFileBuffer() ..........................................................................130
4.6.13 FS_SetFileTime() ........................................................................... 132
4.6.14 FS_SetFileTimeEx() ........................................................................133
4.6.15 FS_WipeFile() ................................................................................134
4.6.16 File attributes ................................................................................135
4.6.17 FS_FILE_INFO ...............................................................................136
4.6.18 File time types ..............................................................................137
4.7 Directory functions .....................................................................................138
4.7.1 FS_CreateDir() ................................................................................139
4.7.2 FS_DeleteDir() ................................................................................140
4.7.3 FS_FindClose() ................................................................................141
4.7.4 FS_FindFirstFile() .............................................................................142
4.7.5 FS_FindNextFile() ............................................................................144
4.7.6 FS_FindNextFileEx() .........................................................................145
4.7.7 FS_MkDir() .....................................................................................146
4.7.8 FS_RmDir() .................................................................................... 147
4.7.9 FS_FIND_DATA ................................................................................148
4.8 Formatting functions ...................................................................................149
4.8.1 FS_Format() ...................................................................................150
4.8.2 FS_FormatLLIfRequired() ..................................................................151
4.8.3 FS_FormatLow() ..............................................................................152
4.8.4 FS_IsHLFormatted() .........................................................................153
4.8.5 FS_IsLLFormatted() .........................................................................154
4.8.6 FS_FORMAT_INFO ........................................................................... 155
4.9 Partitioning functions ..................................................................................156
4.9.1 FS_CreateGPT() .............................................................................. 157
4.9.2 FS_CreateMBR() ..............................................................................160
4.9.3 FS_GetGPTInfo() .............................................................................162
4.9.4 FS_GetPartitionInfoMBR() .................................................................164
4.9.5 FS_GetPartitionInfoGPT() ..................................................................166
4.9.6 FS_GetPartitioningScheme() ..............................................................168
4.9.7 FS_GPT_INFO ................................................................................. 169
4.9.8 FS_PARTITION_INFO_MBR ................................................................170
4.9.9 FS_PARTITION_INFO_GPT ................................................................ 171
4.9.10 Partitioning schemes ......................................................................172
4.10 File system structure checking ...................................................................173
4.10.1 FS_CheckAT() ................................................................................174
4.10.2 FS_CheckDir() ...............................................................................175
4.10.3 FS_CheckDisk() .............................................................................176
4.10.4 FS_CheckDisk_ErrCode2Text() .........................................................179
4.10.5 FS_InitCheck() ..............................................................................180
4.11 File system extended functions .................................................................. 185
4.11.1 FS_ConfigEOFErrorSuppression() ..................................................... 186
4.11.2 FS_ConfigPOSIXSupport() ...............................................................187
4.11.3 FS_ConfigWriteVerification() ............................................................188
4.11.4 FS_FileTimeToTimeStamp() ............................................................. 189
4.11.5 FS_FreeSectors() ...........................................................................190
4.11.6 FS_GetAutoMount() ........................................................................191
4.11.7 FS_GetFileId() ...............................................................................192
4.11.8 FS_GetFileWriteMode() ...................................................................193
4.11.9 FS_GetFileWriteModeEx() ................................................................194
4.11.10 FS_GetFSType() ...........................................................................195
4.11.11 FS_GetMaxSectorSize() .................................................................196
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH
10
4.11.12 FS_GetMemInfo() .........................................................................197
4.11.13 FS_GetMountType() ......................................................................198
4.11.14 FS_GetNumFilesOpen() .................................................................199
4.11.15 FS_GetNumFilesOpenEx() ..............................................................200
4.11.16 FS_GetNumVolumes() ...................................................................201
4.11.17 FS_GetVolumeAlias() ....................................................................202
4.11.18 FS_GetVolumeFreeSpace() ............................................................203
4.11.19 FS_GetVolumeFreeSpaceFirst() ......................................................204
4.11.20 FS_GetVolumeFreeSpaceKB() ........................................................ 206
4.11.21 FS_GetVolumeFreeSpaceNext() ......................................................207
4.11.22 FS_GetVolumeInfo() .....................................................................208
4.11.23 FS_GetVolumeInfoEx() ..................................................................210
4.11.24 FS_GetVolumeLabel() ...................................................................212
4.11.25 FS_GetVolumeName() ...................................................................213
4.11.26 FS_GetVolumeSize() .....................................................................214
4.11.27 FS_GetVolumeSizeKB() .................................................................215
4.11.28 FS_GetVolumeStatus() ..................................................................216
4.11.29 FS_IsVolumeMounted() .................................................................217
4.11.30 FS_Lock() ...................................................................................218
4.11.31 FS_LockVolume() .........................................................................219
4.11.32 FS_SetBusyLEDCallback() ............................................................. 221
4.11.33 FS_SetCharSetType() ....................................................................222
4.11.34 FS_SetFSType() ...........................................................................223
4.11.35 FS_SetMemCheckCallback() ...........................................................224
4.11.36 FS_SetTimeDateCallback() ............................................................225
4.11.37 FS_SetVolumeAlias() ....................................................................226
4.11.38 FS_SetVolumeLabel() ................................................................... 227
4.11.39 FS_TimeStampToFileTime() ........................................................... 228
4.11.40 FS_Unlock() ................................................................................ 229
4.11.41 FS_UnlockVolume() ......................................................................230
4.11.42 Disk checking error codes .............................................................231
4.11.43 Disk checking return values .......................................................... 232
4.11.44 Disk checking action codes ............................................................233
4.11.45 File system types .........................................................................234
4.11.46 Format types ...............................................................................235
4.11.47 FS_BUSY_LED_CALLBACK .............................................................236
4.11.48 FS_CHECKDISK_ON_ERROR_CALLBACK ..........................................237
4.11.49 FS_CHS_ADDR ............................................................................ 238
4.11.50 FS_DISK_INFO ............................................................................239
4.11.51 FS_FILETIME ...............................................................................241
4.11.52 FS_FREE_SPACE_DATA ................................................................. 242
4.11.53 FS_MEM_CHECK_CALLBACK ..........................................................243
4.11.54 FS_MEM_INFO .............................................................................244
4.11.55 FS_TIME_DATE_CALLBACK ............................................................245
4.11.56 Volume information flags ..............................................................246
4.12 Storage layer functions ............................................................................. 247
4.12.1 FS_STORAGE_Clean() .....................................................................248
4.12.2 FS_STORAGE_CleanOne() ...............................................................250
4.12.3 FS_STORAGE_DeInit() ....................................................................251
4.12.4 FS_STORAGE_FormatLowEx() ..........................................................252
4.12.5 FS_STORAGE_FreeSectors() ............................................................253
4.12.6 FS_STORAGE_GetCleanCnt() ...........................................................254
4.12.7 FS_STORAGE_GetCounters() ...........................................................255
4.12.8 FS_STORAGE_GetDeviceInfo() .........................................................256
4.12.9 FS_STORAGE_GetDeviceInfoEx() ..................................................... 257
4.12.10 FS_STORAGE_GetSectorUsage() .................................................... 258
4.12.11 FS_STORAGE_GetVolumeStatusEx() ...............................................259
4.12.12 FS_STORAGE_FindVolume() ...........................................................260
4.12.13 FS_STORAGE_Init() ......................................................................261
4.12.14 FS_STORAGE_IsLLFormattedEx() ................................................... 262
emFile User Guide & Reference Manual © 2002-2022 SEGGER Microcontroller GmbH