µC/FS
File System
Software Version 2.10a
CPU independent
User & Reference manual
Document revision 3
Micriµm Technologies Corporation
www.micrium.com
Empowering Embedded Systems
2/166 User's & reference manual for µC/FS FAT File System
2001-2004 Micrium Technologies Corporation
Disclaimer
The information in this document is subject to change without notice. While the
information herein is assumed to be accurate, Micriµm Technologies Corporation (the
vendor) assumes no responsibility for any errors or omissions.
The vendor makes and you receive no warranties or conditions, express, implied,
statutory or in any communications with you. The vendor specifically disclaims any
implied warranty of merchantability or fitness for a particular purpose.
Copyright notice
No part of this publication may be reproduced, stored in a retrieval system, or
transmitted, in any form or by any means, electronic, mechanical, photocopying,
recording, or otherwise, without the prior written permission of the vendor. 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. If you have received
this product as trial version for evaluation, you are entitled to evaluate it, but you may
under no circumstances use it in a product. If you want to do so, you need to obtain a
fully licensed version from the vendor.
2002-2004 Micrium Technologies Corporation
http://www.micrium.com/
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
Micrium Technologies Corporation
949 Crestview Circle
Weston, FL 33327-1848
U.S.A.
Phone : +1 954 217 2036
FAX : +1 954 217 2037
Email: support@micrium.com
Web: http://www.micrium.com/
User's & reference manual for µC/FS FAT File System 3/166
2001-2004 Micrium Technologies Corporation
Software and manual versions
This manual describes the software version 2.10. If any error occurs, please
inform us and we will try to assist you as soon as possible.
For further information on topics or routines not yet specified, please contact us.
Print date: 4/11/2004
Software Manual Date By Explanation
2.10a 3 040407 SR Added FS_DirEnt2Name, FS_DirEnt2Attr.
Added description of the FS_ATTR_xxx defines (file
attributes).
Debugging Windows sample project renewed.
Programming samples in this document revised.
µC/FS can be used in a C++ project/environment.
Added Hardware Layer to chapter “Basic concepts”.
Code clean up, revised documentation.
2.10 2 040311 SR Code clean up, revised documentation.
Configuration simplified.
MMC/SD Card driver improved, all kind of MMC/SD Card are
supported.
Added new default configuration file.
Added WinDrive driver to documentation.
Added FS_X_Log(), FS_X_Warn(), FS_X_ErrorOut()
2.00 2 031121 TW Code clean up, revised documentation.
Generic device driver added.
Generic flash memory chip driver added.
Device driver initialization improved.
New coding standards added.
Performance improvements
Added support for media with no partition table
Added timing diagram to MMC/SD driver
1.34 1 031010 TW Official successor of 1.32
Hardware interface routines of MMC/SD simplified.
MMC/SD partition table no longer needed.
Several improvements and bug fixes in MMC/SD driver.
1.32 1 030910 TW/TB FAT32 formatting added.
Directory entries with attribute ATTR_LONG_NAME are no
longer shown by FS_ReadDir.
FS_FWrite performance improved by optimizing directory
access.
FS_CMD_GET_DISKFREE can now be executed as first
command after a disk change took place.
Pointer to device information table is located in ROM now.
FS_Remove reports error when file does not exist or cannot
be removed.
FS_IoCtl commands FS_CMD_READ_SECTOR and
FS_CMD_WRITE_SECTOR added.
Non ANSI C conform construct in RAM disk and generic
FLASH driver removed.
Improved function comments.
FS__fat_fread return value corrected for element size bigger
than 1.
FS__fat_fwrite return value corrected for element size bigger
than 1.
FS__fat_FAT_alloc valid cluster check improved.
Switch FS_FAT_FWRITE_UPDATE_DIR added; default on.
Standard library function calls removed.
Expressions in code simplified.
SMC write performance improved by optional switch
FS_SMC_PAGE_BUFFER.
New cluster allocation performance improved.
Element FAT_DirAttr added in structure FS_DIRENT.
FS_FWrite performance improved by avoiding unnecessary
read operations.
1.30 1 030530 TB FS_IoCtl documentation added.
Switch FS_FAT_DISKINFO added.
Logical Block Read Cache implemented.
No open file bug when using FS_FOpen(name,"r+") corrected.
Additional cluster allocation bug when writing data with size
of a cluster corrected.
Command FS_CMD_FORMAT_AUTO added.
1.26 1 030113 TB Support for trial version added.
4/166 User's & reference manual for µC/FS FAT File System
2001-2004 Micrium Technologies Corporation
FS__fat_malloc returns cleared buffer.
MMC driver deactivates CS whenever allowed by
specification.
1.24 1 021205 TB FAT32 & POSIX like directory functions added
1.20 1 021010 TB IDE & CompactFlash driver added
1.10 1 020927 TB MultiMedia & SD card driver added
1.00 1 020830 KG Revised for language/grammar.
Version control table added.
Typographic conventions (section 1.3) changed into table.
Index added.
User's & reference manual for µC/FS FAT File System 5/166
2001-2004 Micrium Technologies Corporation
Contents
Disclaimer............................................................................................................................ 2
Copyright notice................................................................................................................... 2
Trademarks ......................................................................................................................... 2
Contact ................................................................................................................................ 2
Software and manual versions ............................................................................................ 3
Contents .............................................................................................................................. 5
1. About this document........................................................................................................ 7
1.1. Assumptions......................................................................................................... 7
1.2. How to use this manual........................................................................................ 7
1.3. Typographic Conventions for Syntax ................................................................... 7
2. Introduction to µC/FS....................................................................................................... 8
2.1. What is µC/FS?.................................................................................................... 8
2.2. Features............................................................................................................... 8
3. Basic concepts ................................................................................................................ 9
3.1. API Layer ............................................................................................................. 9
3.2. File System Layer ................................................................................................ 9
3.3. Logical Block Layer ............................................................................................ 10
3.4. Device Driver...................................................................................................... 10
3.5. Hardware Layer.................................................................................................. 10
4. Getting started ............................................................................................................... 11
4.1. Installation .......................................................................................................... 11
4.2. Use the Windows sample................................................................................... 11
4.3. Integrating µC/FS into your system .................................................................... 19
4.4. Filesystem startup aid ........................................................................................ 21
5. Configuration of µC/FS .................................................................................................. 24
5.1. Device driver support and configuration............................................................. 24
5.2. File system configuration.................................................................................... 25
5.3. FAT configuration............................................................................................... 25
5.4. OS support......................................................................................................... 26
5.5. Data types.......................................................................................................... 26
5.6. Miscellaneous configurations ............................................................................. 26
5.7. Sample configuration ......................................................................................... 27
6. API functions ................................................................................................................. 28
6.1. Filesystem control functions............................................................................... 29
6.2. File access functions.......................................................................................... 31
6.3. Direct input/output functions............................................................................... 34
6.4. File positioning functions.................................................................................... 36
6.5. Error-handling functions ..................................................................................... 38
6.6. Operations on files ............................................................................................. 41
6.7. Directory functions ............................................................................................. 42
6.8. Extended functions............................................................................................. 52
7. Device drivers................................................................................................................ 56
7.1. Device driver functions....................................................................................... 56
7.2. Device driver function table ................................................................................ 61
7.3. Integrating a new device driver .......................................................................... 61
8. RAM disk driver ............................................................................................................. 62
8.1. Configuration...................................................................................................... 62
9. SmartMedia Card Device Driver .................................................................................... 63
