User’s Manual
μC/
FSTM
The Embedded File System
600-uC-FS-001.book Page 1 Wednesday, October 10, 2012 12:03 PM
Micriµm
1290 Weston Road, Suite 306
Weston, FL 33326
USA
www.micrium.com
Designations used by companies to distinguish their products are often claimed as
trademarks. In all instances where Micriµm Press is aware of a trademark claim, the product
name appears in initial capital letters, in all capital letters, or in accordance with the
vendor’s capitalization preference. Readers should contact the appropriate companies for
more complete information on trademarks and trademark registrations. All trademarks and
registered trademarks in this book are the property of their respective holders.
Copyright © 2012 by Micriµm except where noted otherwise. All rights reserved. Printed in
the United States of America. No part of this publication may be reproduced or distributed
in any form or by any means, or stored in a database or retrieval system, without the prior
written permission of the publisher; with the exception that the program listings may be
entered, stored, and executed in a computer system, but they may not be reproduced for
publication.
The programs and code examples in this book are presented for instructional value. The
programs and examples have been carefully tested, but are not guaranteed to any particular
purpose. The publisher does not offer any warranties and does not guarantee the accuracy,
adequacy, or completeness of any information herein and is not responsible for any errors
or omissions. The publisher assumes no liability for damages resulting from the use of the
information in this book or for any infringement of the intellectual property rights of third
parties that would result from the use of this information.
600-uC-FS-001
600-uC-FS-001.book Page 2 Wednesday, October 10, 2012 12:03 PM
3
Table of Contents
Chapter 1 Introduction .......................................................................................... 15
1-1 µC/FS .................................................................................................... 15
1-2 Typical Usages ..................................................................................... 17
1-3 Why FAT? ............................................................................................. 17
1-4 Chapter Contents ................................................................................. 18
Chapter 2 C/FS Architecture .............................................................................. 23
2-1 Architecture Components ................................................................... 25
2-1-1 Your Application ................................................................................... 25
2-1-2 µC-LIB (Libraries) ................................................................................. 25
2-1-3 POSIX API Layer .................................................................................. 25
2-1-4 FS Layer ............................................................................................... 26
2-1-5 File System Driver Layer ...................................................................... 27
2-1-6 Device Driver Layer .............................................................................. 27
2-1-7 C-CPU ................................................................................................ 28
2-1-8 RTOS Layer .......................................................................................... 28
Chapter 3 µC/FS Directories and Files ................................................................. 29
3-1 Application Code ................................................................................. 32
3-2 CPU ....................................................................................................... 34
3-3 Board Support Package (BSP) ............................................................ 35
3-4 µC/CPU, CPU Specific Source Code .................................................. 36
3-5 µC/LIB, Portable Library Functions ..................................................... 38
3-6 µC/Clk, Time/Calendar Management .................................................. 39
3-7 µC/CRC, Checksums and Error Correction Codes ............................ 41
3-8 µC/FS Platform-Independent Source Code ........................................ 42
3-9 µC/FS FAT Filesystem Source Code ................................................... 45
3-10 µC/FS Memory Device Drivers ............................................................ 46
3-11 µC/FS Platform-Specific Source Code ............................................... 50
600-uC-FS-001.book Page 3 Wednesday, October 10, 2012 12:03 PM
4
Table of Contents
3-12 µC/FS OS Abstraction Layer ............................................................... 51
3-13 Summary .............................................................................................. 52
Chapter 4 Useful Information ................................................................................ 59
4-1 Nomenclature ....................................................................................... 59
4-2 C/FS Device and Volume Names ...................................................... 61
4-3 C/FS File and Directory Names and Paths ....................................... 62
4-4 C/FS Name Lengths ........................................................................... 64
4-5 Resource Usage ................................................................................... 65
Chapter 5 Devices and Volumes .......................................................................... 67
5-1 Device Operations ............................................................................... 68
5-2 Using Devices ...................................................................................... 69
5-3 Using Removable Devices ................................................................... 71
5-4 Raw Device IO ...................................................................................... 72
5-5 Partitions .............................................................................................. 73
5-6 Volume Operations .............................................................................. 76
5-7 Using Volumes ..................................................................................... 77
5-8 Using Volume Cache ............................................................................ 79
5-8-1 Choosing Cache Parameters ............................................................... 81
5-8-2 Other Caching and Buffering Mechanisms ......................................... 82
Chapter 6 Files ...................................................................................................... 83
6-1 File Access Functions .......................................................................... 84
6-1-1 Opening Files ....................................................................................... 85
6-1-2 Getting Information About a File ......................................................... 86
6-1-3 Configuring a File Buffer ...................................................................... 87
6-1-4 File Error Functions .............................................................................. 88
6-1-5 Atomic File Operations Using File Lock .............................................. 88
6-2 Entry Access Functions ....................................................................... 89
6-2-1 File and Directory Attributes ................................................................ 90
6-2-2 Creating New Files and Directories ..................................................... 91
6-2-3 Deleting Files and Directories ............................................................. 92
Chapter 7 Directories ............................................................................................ 93
7-1 Directory Access Functions ................................................................ 94
600-uC-FS-001.book Page 4 Wednesday, October 10, 2012 12:03 PM
5
Chapter 8 POSIX API ............................................................................................. 95
8-1 Supported Functions ........................................................................... 96
8-2 Working Directory Functions ............................................................... 97
8-3 File Access Functions .......................................................................... 98
8-3-1 Opening, Reading and Writing Files .................................................. 100
8-3-2 Getting or Setting the File Position ................................................... 103
8-3-3 Configuring a File Buffer .................................................................... 104
8-3-4 Diagnosing a File Error ...................................................................... 106
8-3-5 Atomic File Operations Using File Lock ............................................ 106
8-4 Directory Access Functions .............................................................. 107
8-5 Entry Access Functions ..................................................................... 109
Chapter 9 Device Drivers .................................................................................... 111
9-1 Provided Device Drivers .................................................................... 112
9-1-1 Driver Characterization ...................................................................... 113
9-2 Drivers comparison ............................................................................ 115
Chapter 10 FAT File System ................................................................................. 117
10-1 Why Embedded Systems Use FAT ................................................... 117
10-2 Organization of a FAT Volume ........................................................... 118
10-2-1 Organization of Directories and Directory Entries ............................ 119
10-3 Organization of the File Allocation Table .......................................... 120
10-3-1 FAT12 / FAT16 / FAT32 ...................................................................... 122
10-3-2 Short and Long File Names ............................................................... 123
10-4 Formatting .......................................................................................... 126
10-5 Sources of Corruption in FAT Volumes ............................................. 127
10-6 Optional Journaling System .............................................................. 127
10-7 Licensing Issues ................................................................................. 129
10-7-1 Licenses for Long File Names (LFNs) ............................................... 129
10-7-2 Extended File Allocation Table (exFAT) ............................................ 129
Chapter 11 RAM Disk Driver ................................................................................. 131
11-1 Files and Directories .......................................................................... 131
11-2 Using the RAM Disk Driver ................................................................ 132
600-uC-FS-001.book Page 5 Wednesday, October 10, 2012 12:03 PM
6
Table of Contents
Chapter 12 SD/MMC Drivers ................................................................................ 135
12-1 Files and Directories .......................................................................... 137
12-2 Using the SD/MMC CardMode Driver ............................................... 138
12-2-1 SD/MMC CardMode Communication ............................................... 141
12-2-2 SD/MMC CardMode Communication Debugging ............................ 144
12-2-3 SD/MMC CardMode BSP Overview .................................................. 148
12-3 Using the SD/MMC SPI Driver ........................................................... 150
12-3-1 SD/MMC SPI Communication ........................................................... 153
12-3-2 SD/MMC SPI Communication Debugging ........................................ 154
12-3-3 SD/MMC SPI BSP Overview .............................................................. 157
Chapter 13 NAND Flash Driver ............................................................................. 159
13-1 Getting Started ................................................................................... 160
13-2 Architecture Overview ....................................................................... 167
13-3 NAND Translation Layer .................................................................... 168
13-3-1 Translation Layer Configuration ........................................................ 171
13-3-2 Translation Layer Source Files .......................................................... 178
13-4 Controller Layer .................................................................................. 178
13-4-1 Generic Controller Layer Implementation ......................................... 179
13-4-2 Part Layer ........................................................................................... 181
13-5 Board Support Package - Generic Controller .................................. 185
13-6 Board Support Package - Other Controllers .................................... 186
13-7 Performance Considerations ............................................................. 187
13-8 Development Guide ........................................................................... 188
13-8-1 BSP Development Guide - Generic Controller ................................. 189
13-8-2 Generic Controller Extension Development Guide ........................... 191
13-8-3 ECC Module Development Guide ..................................................... 193
13-8-4 Controller Layer Development Guide ................................................ 194
Chapter 14 NOR Flash Driver ............................................................................... 199
14-1 Files and Directories .......................................................................... 200
14-2 Driver and Device Characteristics ..................................................... 202
14-3 Using a Parallel NOR Device ............................................................. 204
14-3-1 Driver Architecture ............................................................................. 208
14-3-2 Hardware ............................................................................................ 208
14-3-3 NOR BSP Overview ............................................................................ 210
600-uC-FS-001.book Page 6 Wednesday, October 10, 2012 12:03 PM
7
14-4 Using a Serial NOR Device ................................................................ 211
14-4-1 Hardware ............................................................................................ 212
14-4-2 NOR SPI BSP Overview ..................................................................... 213
14-5 Physical-Layer Drivers ....................................................................... 214
14-5-1 FSDev_NOR_AMD_1x08, FSDev_NOR_AMD_1x16 .......................... 215
14-5-2 FSDev_NOR_Intel_1x16 ..................................................................... 215
14-5-3 FSDev_NOR_SST39 ........................................................................... 216
14-5-4 FSDev_NOR_STM25 .......................................................................... 216
14-5-5 FSDev_NOR_SST25 ........................................................................... 217
Chapter 15 MSC Driver ......................................................................................... 219
15-1 Files and Directories .......................................................................... 219
15-2 Using the MSC Driver ........................................................................ 220
Appendix A µC/FS API Reference ......................................................................... 223
A-1 General File System Functions .......................................................... 225
A-1-1 FS_DevDrvAdd() ................................................................................. 226
A-1-2 FS_Init() ............................................................................................... 227
A-1-3 FS_VersionGet() .................................................................................. 228
A-1-4 FS_WorkingDirGet() ............................................................................ 229
A-1-5 FS_WorkingDirSet() ............................................................................ 230
A-2 Posix API Functions ........................................................................... 231
A-2-1 fs_asctime_r() ..................................................................................... 234
A-2-2 fs_chdir() ............................................................................................. 235
A-2-3 fs_clearerr() ......................................................................................... 236
A-2-4 fs_closedir() ........................................................................................ 237
A-2-5 fs_ctime_r() ......................................................................................... 238
A-2-6 fs_fclose() ........................................................................................... 239
A-2-7 fs_feof() ............................................................................................... 240
A-2-8 fs_ferror() ............................................................................................ 241
A-2-9 fs_fflush() ............................................................................................ 242
A-2-10 fs_fgetpos() ......................................................................................... 243
A-2-11 fs_flockfile() ........................................................................................ 244
A-2-12 fs_fopen() ............................................................................................ 245
A-2-13 fs_fread() ............................................................................................. 246
A-2-14 fs_fseek() ............................................................................................ 247
A-2-15 fs_fsetpos() ......................................................................................... 249
600-uC-FS-001.book Page 7 Wednesday, October 10, 2012 12:03 PM
8
Table of Contents
A-2-16 fs_ftell() ............................................................................................... 250
A-2-17 fs_ftruncate() ...................................................................................... 251
A-2-18 fs_ftrylockfile() .................................................................................... 252
A-2-19 fs_funlockfile() .................................................................................... 253
A-2-20 fs_fwrite() ............................................................................................ 254
A-2-21 fs_getcwd() ......................................................................................... 255
A-2-22 fs_localtime_r() ................................................................................... 256
A-2-23 fs_mkdir() ............................................................................................ 257
A-2-24 fs_mktime() ......................................................................................... 258
A-2-25 fs_opendir() ......................................................................................... 259
A-2-26 fs_readdir_r() ....................................................................................... 260
A-2-27 fs_remove() ......................................................................................... 261
A-2-28 fs_rename() ......................................................................................... 263
A-2-29 fs_rewind() .......................................................................................... 265
A-2-30 fs_rmdir() ............................................................................................. 266
A-2-31 fs_setbuf() ........................................................................................... 267
A-2-32 fs_setvbuf() ......................................................................................... 268
A-3 Device Functions ............................................................................... 270
A-3-1 FSDev_AccessLock() ......................................................................... 273
A-3-2 FSDev_AccessUnlock() ...................................................................... 274
A-3-3 FSDev_Close() .................................................................................... 275
A-3-4 FSDev_GetDevName() ....................................................................... 276
A-3-5 FSDev_GetDevCnt() ........................................................................... 277
A-3-6 FSDev_GetDevCntMax() .................................................................... 278
A-3-7 FSDev_GetNbrPartitions() .................................................................. 279
A-3-8 FSDev_Invalidate() ............................................................................. 280
A-3-9 FSDev_Open() .................................................................................... 281
A-3-10 FSDev_PartitionAdd() ......................................................................... 283
A-3-11 FSDev_PartitionFind() ........................................................................ 284
A-3-12 FSDev_PartitionInit() .......................................................................... 286
A-3-13 FSDev_Query() ................................................................................... 287
A-3-14 FSDev_Rd() ......................................................................................... 288
A-3-15 FSDev_Refresh() ................................................................................. 289
A-3-16 FSDev_Wr() ......................................................................................... 291
A-4 Directory Access Functions .............................................................. 292
A-4-1 FSDir_Close() ...................................................................................... 293
A-4-2 FSDir_IsOpen() ................................................................................... 294
A-4-3 FSDir_Open() ...................................................................................... 295
600-uC-FS-001.book Page 8 Wednesday, October 10, 2012 12:03 PM
9
A-4-4 FSDir_Rd() .......................................................................................... 296
A-5 Entry Access Functions ..................................................................... 297
A-5-1 FSEntry_AttribSet() ............................................................................. 298
A-5-2 FSEntry_Copy() .................................................................................. 300
A-5-3 FSEntry_Create() ................................................................................ 302
A-5-4 FSEntry_Del() ...................................................................................... 304
A-5-5 FSEntry_Query() ................................................................................. 306
A-5-6 FSEntry_Rename() .............................................................................. 307
A-5-7 FSEntry_TimeSet() .............................................................................. 309
A-6 File Functions ..................................................................................... 311
A-6-1 FSFile_BufAssign() ............................................................................. 313
A-6-2 FSFile_BufFlush() ............................................................................... 315
A-6-3 FSFile_Close() ..................................................................................... 316
A-6-4 FSFile_ClrErr() .................................................................................... 317
A-6-5 FSFile_IsEOF() .................................................................................... 318
A-6-6 FSFile_IsErr() ...................................................................................... 319
A-6-7 FSFile_IsOpen() .................................................................................. 320
A-6-8 FSFile_LockAccept() .......................................................................... 321
A-6-9 FSFile_LockGet() ................................................................................ 322
A-6-10 FSFile_LockSet() ................................................................................ 323
A-6-11 FSFile_Open() ..................................................................................... 324
A-6-12 FSFile_PosGet() .................................................................................. 326
A-6-13 FSFile_PosSet() .................................................................................. 327
A-6-14 FSFile_Query() .................................................................................... 329
A-6-15 FSFile_Rd() ......................................................................................... 330
A-6-16 FSFile_Truncate() ................................................................................ 332
A-6-17 FSFile_Wr() ......................................................................................... 333
A-7 Volume Functions .............................................................................. 335
A-7-1 FSVol_Close() ..................................................................................... 337
A-7-2 FSVol_Fmt() ........................................................................................ 338
A-7-3 FSVol_GetDfltVolName() .................................................................... 340
A-7-4 FSVol_GetVolCnt() .............................................................................. 341
A-7-5 FSVol_GetVolCntMax() ....................................................................... 342
A-7-6 FSVol_GetVolName() .......................................................................... 343
A-7-7 FSVol_IsDflt() ...................................................................................... 344
A-7-8 FSVol_IsMounted() ............................................................................. 345
A-7-9 FSVol_LabelGet() ................................................................................ 346
A-7-10 FSVol_LabelSet() ................................................................................ 348
600-uC-FS-001.book Page 9 Wednesday, October 10, 2012 12:03 PM
10
Table of Contents
A-7-11 FSVol_Open() ...................................................................................... 350
A-7-12 FSVol_Query() ..................................................................................... 352
A-7-13 FSVol_Rd() .......................................................................................... 353
A-7-14 FSVol_Wr() .......................................................................................... 355
A-8 Volume Cache Functions ................................................................... 356
A-8-1 FSVol_CacheAssign() ......................................................................... 357
A-8-2 FSVol_CacheInvalidate () ................................................................... 359
A-8-3 FSVol_CacheFlush () .......................................................................... 360
A-9 SD/MMC Driver Functions ................................................................. 361
A-9-1 FSDev_SD_xxx_QuerySD() ................................................................ 362
A-9-2 FSDev_SD_xxx_RdCID() .................................................................... 364
A-9-3 FSDev_SD_xxx_RdCSD() ................................................................... 366
A-10 NAND Driver Functions ...................................................................... 368
A-10-1 FSDev_NAND_LowFmt() .................................................................... 369
A-10-2 FSDev_NAND_LowMount() ................................................................ 370
A-10-3 FSDev_NAND_LowUnmount() ........................................................... 372
A-11 NOR Driver Functions ........................................................................ 373
A-11-1 FSDev_NOR_LowFmt() ...................................................................... 374
A-11-2 FSDev_NOR_LowMount() .................................................................. 375
A-11-3 FSDev_NOR_LowUnmount() .............................................................. 376
A-11-4 FSDev_NOR_LowCompact() .............................................................. 377
A-11-5 FSDev_NOR_LowDefrag() .................................................................. 378
A-11-6 FSDev_NOR_PhyRd() ......................................................................... 379
A-11-7 FSDev_NOR_PhyWr() ......................................................................... 381
A-11-8 FSDev_NOR_PhyEraseBlk() ............................................................... 383
A-11-9 FSDev_NOR_PhyEraseChip() ............................................................ 385
A-12 FAT System Driver Functions ............................................................ 386
A-12-1 FS_FAT_JournalOpen() ....................................................................... 387
A-12-2 FS_FAT_JournalClose() ...................................................................... 388
A-12-3 FS_FAT_JournalStart() ........................................................................ 389
A-12-4 FS_FAT_JournalStop() ........................................................................ 390
A-12-5 FS_FAT_VolChk() ................................................................................ 391
Appendix B C/FS Error Codes ............................................................................. 393
B-1 System Error Codes ........................................................................... 393
B-2 Buffer Error Codes ............................................................................. 393
B-3 Cache Error Codes ............................................................................ 394
B-4 Device Error Codes ............................................................................ 394
600-uC-FS-001.book Page 10 Wednesday, October 10, 2012 12:03 PM
11
B-5 Device Driver Error Codes ................................................................. 395
B-6 Directory Error Codes ........................................................................ 395
B-7 ECC Error Codes ................................................................................ 395
B-8 Entry Error Codes .............................................................................. 395
B-9 File Error Codes ................................................................................. 396
B-10 Name Error Codes ............................................................................. 397
B-11 Partition Error Codes ......................................................................... 397
B-12 Pools Error Codes .............................................................................. 397
B-13 File System Error Codes .................................................................... 398
B-14 Volume Error Codes ........................................................................... 398
B-15 OS Layer Error Codes ........................................................................ 399
Appendix C µC/FS Porting Manual ........................................................................ 401
C-1 Date/Time Management .................................................................... 403
C-2 CPU Port ............................................................................................. 403
C-3 OS Kernel ........................................................................................... 404
C-4 Device Driver ...................................................................................... 412
C-4-1 NameGet() .......................................................................................... 414
C-4-2 Init() ..................................................................................................... 415
C-4-3 Open() ................................................................................................. 416
C-4-4 Close() ................................................................................................. 418
C-4-5 Rd() ..................................................................................................... 419
C-4-6 Wr() ...................................................................................................... 421
C-4-7 Query() ................................................................................................ 423
C-4-8 IO_Ctrl() ............................................................................................... 424
C-5 SD/MMC Cardmode BSP .................................................................. 425
C-5-1 FSDev_SD_Card_BSP_Open() ........................................................... 429
C-5-2 FSDev_SD_Card_BSP_Lock/Unlock() ............................................... 430
C-5-3 FSDev_SD_Card_BSP_CmdStart() .................................................... 431
C-5-4 FSDev_SD_Card_BSP_CmdWaitEnd() .............................................. 436
C-5-5 FSDev_SD_Card_BSP_CmdDataRd() ............................................... 440
C-5-6 FSDev_SD_Card_BSP_CmdDataWr() ................................................ 443
C-5-7 FSDev_SD_Card_BSP_GetBlkCntMax() ............................................ 446
C-5-8 FSDev_SD_Card_BSP_GetBusWidthMax() ....................................... 447
C-5-9 FSDev_SD_Card_BSP_SetBusWidth() .............................................. 448
C-5-10 FSDev_SD_Card_BSP_SetClkFreq() ................................................. 450
C-5-11 FSDev_SD_Card_BSP_SetTimeoutData() ......................................... 451
C-5-12 FSDev_SD_Card_BSP_SetTimeoutResp() ........................................ 452
600-uC-FS-001.book Page 11 Wednesday, October 10, 2012 12:03 PM
12
Table of Contents
C-6 SD/MMC SPI mode BSP .................................................................... 452
C-7 SPI BSP .............................................................................................. 453
C-7-1 Open() ................................................................................................. 457
C-7-2 Close() ................................................................................................. 459
C-7-3 Lock() / Unlock() ................................................................................. 460
C-7-4 Rd() ..................................................................................................... 461
C-7-5 Wr() ...................................................................................................... 462
C-7-6 ChipSelEn() /ChipSelDis() .................................................................. 463
C-7-7 SetClkFreq() ........................................................................................ 464
C-8 NAND Flash Physical-Layer Driver .................................................... 464
C-9 NOR Flash Physical-Layer Driver ...................................................... 464
C-9-1 Open() ................................................................................................. 467
C-9-2 Close() ................................................................................................. 468
C-9-3 Rd() ..................................................................................................... 469
C-9-4 Wr() ...................................................................................................... 470
C-9-5 EraseBlk() ........................................................................................... 471
C-9-6 IO_Ctrl() ............................................................................................... 472
C-10 NOR Flash BSP .................................................................................. 473
C-10-1 FSDev_NOR_BSP_Open() .................................................................. 474
C-10-2 FSDev_NOR_BSP_Close() ................................................................. 475
C-10-3 FSDev_NOR_BSP_Rd_XX() ................................................................ 476
C-10-4 FSDev_NOR_BSP_RdWord_XX() ....................................................... 477
C-10-5 FSDev_NOR_BSP_WrWord_XX() ....................................................... 478
C-10-6 FSDev_NOR_BSP_WaitWhileBusy() .................................................. 479
C-11 NOR Flash SPI BSP ........................................................................... 480
Appendix D C/FS Types and Structures ............................................................. 481
D-1 FS_CFG .............................................................................................. 482
D-2 FS_DEV_INFO ..................................................................................... 484
D-3 FS_DEV_NOR_CFG ............................................................................ 485
D-4 FS_DEV_RAM_CFG ............................................................................ 488
D-5 FS_DIR_ENTRY (struct fs_dirent) ...................................................... 489
D-6 FS_ENTRY_INFO ................................................................................ 490
D-7 FS_FAT_SYS_CFG ............................................................................. 492
D-8 FS_PARTITION_ENTRY ..................................................................... 494
D-9 FS_VOL_INFO ..................................................................................... 495
600-uC-FS-001.book Page 12 Wednesday, October 10, 2012 12:03 PM
13
Appendix E C/FS Configuration .......................................................................... 497
E-1 File System Configuration ................................................................. 498
E-2 Feature Inclusion Configuration ........................................................ 500
E-3 Name Restriction Configuration ........................................................ 503
E-4 Debug Configuration .......................................................................... 504
E-5 Argument Checking Configuration .................................................... 504
E-6 File System Counter Configuration ................................................... 505
E-7 FAT Configuration .............................................................................. 505
E-8 SD/MMC SPI Configuration ............................................................... 506
E-9 Trace Configuration ........................................................................... 507
Appendix F Shell Commands ................................................................................ 509
F-1 Files and Directories .......................................................................... 510
F-2 Using the Shell Commands ............................................................... 511
F-3 Commands ......................................................................................... 514
F-3-1 fs_cat .................................................................................................. 515
F-3-2 fs_cd ................................................................................................... 516
F-3-3 fs_cp ................................................................................................... 518
F-3-4 fs_date ................................................................................................ 519
F-3-5 fs_df .................................................................................................... 520
F-3-6 fs_ls ..................................................................................................... 521
F-3-7 fs_mkdir .............................................................................................. 522
F-3-8 fs_mkfs ............................................................................................... 523
F-3-9 fs_mount ............................................................................................. 524
F-3-10 fs_mv .................................................................................................. 525
F-3-11 fs_od ................................................................................................... 526
F-3-12 fs_pwd ................................................................................................ 527
F-3-13 fs_rm ................................................................................................... 528
F-3-14 fs_rmdir ............................................................................................... 529
F-3-15 fs_touch .............................................................................................. 530
F-3-16 fs_umount ........................................................................................... 531
F-3-17 fs_wc ................................................................................................... 532
F-4 Configuration ...................................................................................... 533
600-uC-FS-001.book Page 13 Wednesday, October 10, 2012 12:03 PM
14
Table of Contents
Appendix G Bibliography ....................................................................................... 535
Appendix H µC/FS Licensing Policy ...................................................................... 537
H-1 µC/FS Licensing ................................................................................. 537
H-1-1 µC/FS Source Code ........................................................................... 537
H-1-2 µC/FS Maintenance Renewal ............................................................ 538
H-1-3 µC/FS Source Code Updates ............................................................ 538
H-1-4 µC/FS Support ................................................................................... 538
600-uC-FS-001.book Page 14 Wednesday, October 10, 2012 12:03 PM
15
Chapter
1
Introduction
Files and directories are common abstractions, which we encounter daily when sending an
e-mail attachment, downloading a new application or archiving old information. Those
same abstractions may be leveraged in an embedded system for similar tasks or for unique
ones. A device may serve web pages, play or record media (images, video or music) or log
data. The file system software which performs such actions must meet the general
expectations of an embedded environment—a limited code footprint, for instance—while
still delivering good performance.
1-1 µC/FS
µC/FS is a compact, reliable, high-performance file system. It offers full-featured file and
directory access with flexible device and volume management including support for
partitions.
Source Code: µC/FS is provided in ANSI-C source to licensees. The source code is written
to an exacting coding standard that emphasizes cleanness and readability. Moreover,
extensive comments pepper the code to elucidate its logic and describe global variables and
functions. Where appropriate, the code directly references standards and supporting
documents.
Device Drivers: Device drivers are available for most common media including SD/MMC
cards, NAND flash, NOR flash. Each of these is written with a clear, layered structure so that
it can easily be ported to your hardware. The device driver structure is simple—basically
just initialization, read and write functions—so that µC/FS can easily be ported to a new
medium.
600-uC-FS-001.book Page 15 Wednesday, October 10, 2012 12:03 PM
16
Chapter 1
Devices and Volumes: Multiple media can be accessed simultaneously, including multiple
instances of the same type of medium (since all drivers are re-entrant). DOS partitions are
supported, so more than one volume can be located on a device. In addition, the logical
device driver allows a single volume to span several (typically identical) devices, such as a
bank of flash chips.
FAT: All standard FAT variants and features are supported including FAT12/FAT16/FAT32
and long file names, which encompasses Unicode file names. Files can be up to 4-GB and
volumes up to 8-TB (the standard maximum). An optional journaling module provides total
power fail-safety to the FAT system driver.
Application Programming Interface (API): µC/FS provides two APIs for file and
directory access. A proprietary API with parallel argument placement and meaningful return
error codes is provided, with functions like FSFile_Wr(), FSFile_Rd() and
FSFile_PosSet(). Alternatively, a standard POSIX-compatible API is provided, including
functions like fs_fwrite(), fs_fread() and fs_fsetpos() that have the same arguments
and return values as the POSIX functions fwrite(), fread() and fsetpos().
Scalable: The memory footprint of µC/FS can be adjusted at compile-time based on the
features you need and the desired level of run-time argument checking. For applications
with limited RAM, features such as cache and read/write buffering can be disabled; for
applications with sufficient RAM, these features can be enabled in order to gain better
performance.
Portable: µC/FS was designed for resource-constrained embedded applications. Although
µC/FS can work on 8- and 16-bit processors, it will work best with 32- or 64-bit CPUs.
RTOS: µC/FS does not assume the presence of a RTOS kernel. However, if you are using a
RTOS, a simple port layer is required (consisting of a few semaphores), in order to prevent
simultaneous access to core structures from different tasks. If you are not using a RTOS, this
port layer may consist of empty functions.
600-uC-FS-001.book Page 16 Wednesday, October 10, 2012 12:03 PM
17
Typical Usages
1-2 TYPICAL USAGES
Applications have sundry reasons for non-volatile storage. A subset require (or benefit from)
organizing data into named files within a directory hierarchy on a volume—basically, from
having a file system. Perhaps the most obvious expose the structure of information to the
user, like products that store images, video or music that are transferred to or from a PC. A
web interface poses a similar opportunity, since the URLs of pages and images fetched by
the remote browser would resolve neatly to locations on a volume.
Another typical use is data logging. A primary purpose of a device may be to collect data
from its environment for later retrieval. If the information must persist across device reset
events or will exceed the capacity of its RAM, some non-volatile memory is necessary. The
benefit of a file system is the ability to organize that information logically, with a fitting
directory structure, through a familiar API.
A file system can also store programs. In a simple embedded CPU, the program is stored at
a fixed location in a non-volatile memory (usually flash). If an application must support
firmware updates, a file system may be a more convenient place, since the software handles
the details of storing the program. The boot-loader, of course, would need to be able to
load the application, but since that requires only read-only access, no imposing program is
required. The ROM boot-loaders in some CPUs can check the root directory of a SD card for
a binary in addition to the more usual locations such as external NAND or NOR flash.
1-3 WHY FAT?
File Allocation Table (FAT) is a simple file system, widely supported across major OSs.
While it has been supplanted as the format of hard drives in Windows PCs, removable
media still use FAT because of its wide support. That is suitable for embedded systems,
which would often be challenged to muster the resources for the modern file systems
developed principally for large fixed disks.
µC/FS supports FAT because of the interoperability requirements of removable media,
allowing that a storage medium be removed from an embedded device and connected to a
PC. All variants and extensions are supported to specification.
600-uC-FS-001.book Page 17 Wednesday, October 10, 2012 12:03 PM
18
Chapter 1
A notorious weakness of FAT (exacerbated by early Windows system drivers) is its non-fail
safe architecture. Certain operations leave the file system in an inconsistent state, albeit
briefly, which may corrupt the disk or force a disk check upon unexpected power failure.
µC/FS minimizes the problem by ordering modifications wisely. The problem is completely
solved in an optional journaling module which logs information about pending changes so
those can be resumed on start-up after a power failure.
1-4 CHAPTER CONTENTS
Figure 1-1 shows the layout and flow of the book. This diagram should be useful to
understand the relationship between chapters. The first (leftmost) column lists chapters that
should be read in order to understand µC/FS’s structure. The chapters in the second column
give greater detail about the application of µC/FS. Each of the chapters in the third column
examines a storage technology and its device driver. Finally, the fourth column lists the
appendices, the topmost being the µC/FS reference, configuration and porting manuals.
Reference these sections regularly when designing a product using µC/FS.
Figure 1-1 µC/FS book layout
Introduction
µC/FS
Architecture
µC/FS Directories
and
Files
µC/FS
Porting
Manual
µC/FS
Error
Codes
µC/FS
Configuration
Manual
µC/FS
Shell
Commands
Bibliography
(1)
(2)
(3)
(4)
Useful Information
(5)
Devices
and
Volumes
(6)
POSIX
API
(7)
Files
(8)
Directories
(9)
(10)
(B)
(C)
(G)
(E)
(F)
Device
Drivers
FAT
File System
RAM Disk
Driver
(11)
µC/FS
Types and
Structures
(D)
µC/FS API
Reference
Manual
(A)
SD/MMC
Driver
(12)
(15)
Mass Storage
Class (MSC)
Driver
(14)
NOR Flash
Driver
(13)
NAND Flash
Driver
600-uC-FS-001.book Page 18 Wednesday, October 10, 2012 12:03 PM
19
Chapter Contents
Chapter 1, “Introduction”. This chapter.
Chapter 2, “C/FS Architecture”. This chapter contains a simplified block diagram of the
various different µC/FS modules and their relationships. The relationships are then
explained.
Chapter 3, “µC/FS Directories and Files”. This chapter explains the directory structure
and files needed to build a µC/FS-based application. Learn about the files that are needed,
where they should be placed, which module does what, and more.
Chapter 4, “Useful Information”. In this chapter, you will learn the nomenclature used
in µC/FS to access files and folders and the resources needed to use µC/FS in your
application.
Chapter 5, “Devices and Volumes”. Every file and directory accessed with µC/FS is a
constituent of a volume (a collection of files and directories) on a device (a physical or
logical sector-addressed entity). This chapter explains how devices and volumes are
managed.
Chapter 6, “Files”. µC/FS complements the POSIX API with its own file access API. This
chapter explains this API.
Chapter 7, “Directories”. µC/FS complements the POSIX API with its own directory
access API. This chapter explains this API.
Chapter 8, “POSIX API”. The best-known API for accessing and managing files and
directories is specified within the POSIX standard (IEEE Std 1003.1), which is based in part
in the ISO C standard (ISO/IEC 9899). This chapter explains how to use this API and
examines some of its pitfalls and shortcomings.
Chapter 10, “FAT File System”. This chapter details the low-level architecture of the FAT
file system. Though the API of µC/FS is file system agnostic, the file system type does affect
performance, reliability and security, as explained here as well.
Chapter 9, “Device Drivers”. All hardware accesses are eventually performed by a device
driver. This chapter describes the drivers available with µC/FS and broadly profiles
supported media types in terms of cost, performance and complexity.
600-uC-FS-001.book Page 19 Wednesday, October 10, 2012 12:03 PM
20
Chapter 1
Chapter 11, “RAM Disk Driver”. This chapter demonstrates the use of the simplest
storage medium, the RAM disk.
Chapter 12, “SD/MMC Drivers”. SD and MMC cards are flash-based removable storage
devices commonly used in consumer electronics. For embedded CPUs, a SD/MMC card is
an appealing medium because of its simple and widely-supported physical interfaces (one
choice is SPI). This chapter describes the interface and function of these devices.
Chapter 13, “NAND Flash Driver”. NAND flash is the first category of flash media. Write
speeds are fast (compared to NOR flash), at the expense of slower read speeds and
complexities such as bit-errors and page program limitations. This chapter describes the
functions of these devices and the architecture of the supporting driver.
Chapter 14, “NOR Flash Driver”. NOR flash is the second category of flash media. They
suffer slow write speeds, balanced with blazingly-fast read speeds. Importantly, they are not
plagued by the complications of NAND flash, which simplifies interfacing with them. This
chapter describes the function of these devices and the architecture of the supporting driver.
Chapter 15, “MSC Driver”. The now-common USB drive implements the Mass Storage
Class (MSC) protocol, and a CPU with a USB host interface can access these devices with
appropriate software. The MSC driver, discussed in this chapter, with µC/USB-Host is just
such appropriate software.
Appendix A, “µC/FS API Reference”. The reference manual describes every API
function. The arguments and return value of each function are given, supplemented by
notes about its use and an example code listing.
Appendix B, “C/FS Error Codes”. This appendix provides a brief explanation of µC/FS
error codes defined in fs_err.h.
Appendix C, “µC/FS Porting Manual”. The portability of µC/FS relies upon ports to
interface between its modules and the platform or environment. Most of the ports constitute
the board support package (BSP), which is interposed between the file system suite (or
driver) and hardware. The OS port adapts the software to a particularly OS kernel. The
porting manual describes each port function.
Appendix D, “C/FS Types and Structures”. This appendix provides a reference to the
µC/FS types and structures.
600-uC-FS-001.book Page 20 Wednesday, October 10, 2012 12:03 PM
21
Chapter Contents
Appendix E, “C/FS Configuration”. µC/FS is configured via defines in a single
configuration file, fs_cfg.h. The configuration manual specifies each define and the
meaning of possible values.
Appendix F, “Shell Commands”. A familiar method of accessing a file system, at least to
engineers and computer scientists, is the command line. In an embedded system, a UART is
a port over which commands can be executed easily, even for debug purposes. A set of
shell commands have been developed for µC/FS that mirror the syntax of UNIX utilities, as
described in this chapter.
Appendix G, “Bibliography”.
Appendix H, “µC/FS Licensing Policy”.
600-uC-FS-001.book Page 21 Wednesday, October 10, 2012 12:03 PM
22
Chapter 1
600-uC-FS-001.book Page 22 Wednesday, October 10, 2012 12:03 PM
23
Chapter
2
C/FS Architecture
µC/FS was written from the ground up to be modular and easy to adapt to different CPUs
(Central Processing Units), RTOSs (Real-Time Operating Systems), storage media and
compilers. Figure 2-1 shows a simplified block diagram of the different µC/FS modules and
their relationships.
Notice that all of the µC/FS files start with ‘fs_’. This convention allows you to quickly
identify which files belong to µC/FS. Also note that all functions and global variables start
with ‘FS’, and all macros and #defines start with ‘FS_’.
600-uC-FS-001.book Page 23 Wednesday, October 10, 2012 12:03 PM
24
Chapter 2
Figure 2-1 C/FS architecture
ȝ
&)6
326,;$3,/D\HU
IVBDSL
5726&38 'HYLFH
7LPH
PDQDJHPHQW
)LOH6\VWHP'ULYHU/D\HU
IVBIDW
IVBIDWBGLU
IVBIDWBHQWU\
IVBIDWBILOH
IVBIDWBIDW
IVBIDWBIDW
IVBIDWBIDW
IVBIDWBOIQ
IVBIDWBVIQ
IVBIDWBW\SHK
IVBIDWBMRXUQDO
'HYLFH'ULYHU/D\HU
125
IVBGHYBQRU
,'(
IVBGHYBLGH
5$0'LVN
IVBGHYBUDP
6'00&
IVBGHYBVGBVSL
IVBGHYBVGBFDUG
IVBGHYBVG
)6/D\HU
IV
IVBEXI
IVBFDFKH
IVBFIJBIVK
IVBFWUK
IVBGHIK
IVBGHY
IVBHQWU\
IVBHUUK
IVBILOH
IVBSDUWLWLRQ
IVBV\V
IVBYRO
IVBW\SHK
IVBXQLFRGH
IVBXWLO
IVBGLU
IVBLQFK
86%06&
IVBGHYBPVF
ȝ
&/,%
OLEBDVFLL
OLEBGHIK
OLEBPHP
OLEBVWU
<RXU$SSOLFDWLRQ
IVBFIJK
ȝ
&&5&
HGFBFUF
HFFBKDPPLQJ
HFFK
FUFBXWLO
ȝ
&&ON/D\HU
FON
5726/D\HU
IVBRVFK
'HYLFH'ULYHU%63
IVBGHYBGULYHU!BEVSF
ȝ
&&38
FSXBDDVP
FSXK
FSXBGHIK
600-uC-FS-001.book Page 24 Wednesday, October 10, 2012 12:03 PM
25
Architecture Components
2-1 ARCHITECTURE COMPONENTS
µC/FS consists of a set of modular software components. It also requires a few external
components (provided with the release) be compiled into the application and a few
configuration and BSP files be adapted to the application.
2-1-1 YOUR APPLICATION
Your application needs to provide configuration information to µC/FS in the form of one C
header file named fs_cfg.h.
Some of the configuration data in fs_cfg.h consist of specifying whether certain features
will be present. For example, LFN support, volume cache and file buffering are all enabled
or disabled in this file. In all, there are about 30 #define to set. However, most of these can
be set to their default values.
2-1-2 µC-LIB (LIBRARIES)
Because µC/FS is designed to be used in safety critical applications, all ‘standard’ library
functions like strcpy(), memset(), etc., have been re-written to follow the same quality as
the rest of the file system software.
2-1-3 POSIX API LAYER
Your application interfaces to µC/FS using the well-known stdio.h API (Application
Programming Interface). Alternately, you can use µC/FS’s own file and directory interface
functions. Basically, POSIX API layer is a layer of software that converts POSIX file access
calls to µC/FS file access calls.
600-uC-FS-001.book Page 25 Wednesday, October 10, 2012 12:03 PM
26
Chapter 2
2-1-4 FS LAYER
This layer contains most of the CPU-, RTOS- and compiler-independent code for µC/FS.
There are three categories of files in this section:
1 File system object-specific files:
■Devices (fs_dev.*)
■Directories (fs_dir.*)
■Entries (fs_entry.*)
■Files (fs_file.*)
■Partitions (fs_partition.*)
■Volumes (fs_vol.*)
2 Support files:
■Buffer management (fs_buf.*)
■Cache management (fs_cache.*)
■Counter management (fs_ctr.h)
■File system driver (fs_sys.*)
■Unicode encoding support (fs_unicode.*)
■Utility functions (fs_util.*)
3 Miscellaneous header files:
■Master µC/FS header file (fs.h)
■Error codes (fs_err.h)
■Aggregate header file (fs_inc.h)
■Miscellaneous data types (fs_type.h)
■Miscellaneous definitions (fs_def.h)
■Configuration definitions (fs_cfg_fs.h)
600-uC-FS-001.book Page 26 Wednesday, October 10, 2012 12:03 PM
27
Architecture Components
2-1-5 FILE SYSTEM DRIVER LAYER
The file system driver layer understands the organization of a particular file system type,
such as FAT. The current version of µC/FS only supports FAT file systems. fs_fat*.*
contains the file system driver which should be used for FAT12/FAT16/FAT32 disks with or
without Long File Name (LFN) support.
2-1-6 DEVICE DRIVER LAYER
The device driver layer understands about types of file system media (SD/MMC card, NOR
flash, etc.). In order for the device drivers to be independent of your CPU, we use additional
files to encapsulate such details as the access of registers, reading and writing to a data bus
and setting clock rates.
Each device driver is named according to the pattern
fs_dev_<dev drv name>.c
where <dev drv name> is the an identifier for the device driver. For example, the driver for
SD/MMC cards using SPI mode is called fs_dev_sd_spi.c. Most device drivers require a
BSP layer, with code for accessing registers, reading from or writing to a data bus, etc. This
file is named according to the pattern
fs_dev_<dev drv name>_bsp.c
For example, fs_dev_sd_spi_bsp.c contains the BSP functions for the driver SD/MMC
cards using SPI mode.
600-uC-FS-001.book Page 27 Wednesday, October 10, 2012 12:03 PM
28
Chapter 2
2-1-7 C-CPU
µC/FS can work with either an 8, 16, 32 or even 64-bit CPU, but needs to have information
about the CPU you are using. The µC-CPU layer defines such things as the C data type
corresponding to 16-bit and 32-bit variables, whether the CPU is little- or big-endian and,
how interrupts are disabled and enabled on the CPU, etc.
CPU specific files are found in the …\uC-CPU directory and, in order to adapt µC/FS to a
different CPU, you would need to either modify the cpu*.* files or, create new ones based
on the ones supplied in the uC-CPU directory. In general, it’s much easier to modify existing
files because you have a better chance of not forgetting anything.
2-1-8 RTOS LAYER
µC/FS does not require an RTOS. However, if µC/FS is used with an RTOS, a set of functions
must be implemented to prevent simultaneous access of devices and core µC/FS structures
by multiple tasks.
µC/FS is provided with a no-RTOS (which contains just empty functions), a C/OS-II and a
µC/OS-III interface. If you use a different RTOS, you can use the fs_os.* for µC/OS-II as a
template to interface to the RTOS of your choice.
600-uC-FS-001.book Page 28 Wednesday, October 10, 2012 12:03 PM
29
Chapter
3
µC/FS Directories and Files
µC/FS is fairly easy to use once you understand which source files are needed to make up a
µC/FS-based application. This chapter will discuss the modules available for µC/FS and how
everything fits together.
Figure 3-1 shows the µC/FS architecture and its relationship with the hardware. Memory
devices may include actual media both removable (SD/MMC, CF cards) and fixed (NAND
flash, NOR flash) as well as any controllers for such devices. Of course, your hardware
would most likely contain other devices such as UARTs (Universal Asynchronous Receiver
Transmitters), ADCs (Analog to Digital Converters) and Ethernet controller(s). Moreover,
your application may include other middleware components like an OS kernel, networking
(TCP/IP) stack or USB stack that may integrate with µC/FS.
A Windows™-based development platform is assumed. The directories and files make
references to typical Windows-type directory structures. However, since µC/FS is available
in source form then it can certainly be used on Unix, Linux or other development platforms.
This, of course, assumes that you are a valid µC/FS licensee in order to obtain the source
code.
The names of the files are shown in upper case to make them ‘stand out’. The file names,
however, are actually lower case.
600-uC-FS-001.book Page 29 Wednesday, October 10, 2012 12:03 PM
30
Chapter 3
Figure 3-1 µC/FS Architecture
F3-1(1) The application code consist of project or product files. For convenience, we
simply called these app.c and app.h but your application can contain any
number of files and they do not have to be called app.*. The application code
is typically where you would find main().
APP.C/H
FS_APP.C/H
Platform Independent
Platform Specific
FS_DEV_*_BSP.C
CPU Specific
CPU.H
CPU_A.ASM
CPU_CORE.C/H
Board Support Package
BSP.C/H
FS_CFG.H
Libraries
LIB_ASCII.C/H
LIB_DEF.H
LIB_MATH.C/H
LIB_MEM.C/H
LIB_STR.C/H
*.C
*.H
FS_ERR.H
FS_FILE.C/H
FS_INC.H
FS_PARTITION.C/H
FS_SYS.C/H
FS_TYPE.H
FS_UNICODE.C/H
FS_UTIL.C/H
FS_VOL.C/H
FS.C/H
FS_API.C/H
FS_BUF.C/H
FS_CACHE.C/H
FS_CFG_FS.H
FS_CTR.H
FS_DEF.H
FS_DEV.C/H
FS_DIR.C/H
FS_ENTRY.C/H
Filesystem Driver
FS_FAT_FILE.C/H
FS_FAT_JOURNAL.C/H
FS_FAT_LFN.C/H
FS_FAT_SFN.C/H
FS_FAT_TYPE.H
FS_FAT.C/H
FS_FAT_DIR.C/H
FS_FAT_ENTRY.C/H
FS_FAT_FAT12.C/H
FS_FAT_FAT16.C/H
FS_FAT_FAT32.C/H
Device Drivers
FS_DEV_*.C/H
ECC.H
EDC_CRC.C/H
ECC_HAMMING.C/H
CRC_UTIL.C/H
CLK.C/H
CLK_OS.C/H
OS Specific
FS_OS.C/H
600-uC-FS-001.book Page 30 Wednesday, October 10, 2012 12:03 PM
31
F3-1(2) Quite often, semiconductor manufacturers provide library functions in source
form for accessing the peripherals on their CPU (Central Processing Unit) or
MCU (Micro Controller Unit). These libraries are quite useful and often save
valuable time. Since there is no naming convention for these files, *.c and *.h
are assumed.
F3-1(3) The Board Support Package (BSP) is code that you would typically write to
interface to peripherals on your target board. For example you can have code
to turn on and off LEDs (light emitting diodes), functions to turn on and off
relays, and code to read switches and temperature sensors.
F3-1(4) µC/CPU is an abstraction of basic CPU-specific functionality. These files define
functions to disable and enable interrupts, data types (e.g., CPU_INT08U,
CPU_FP32) independent of the CPU and compiler and many more functions.
F3-1(5) µC/LIB consists of a group of source files to provide common functions for
memory copy, string manipulation and character mapping. Some of the
functions replace stdlib functions provided by the compiler. These are provided
to ensure that they are fully portable from application to application and (most
importantly) from compiler to compiler.
F3-1(6) µC/Clk is an independant clock/calendar management module, with source
code for easily managing date and time in a product. µC/FS uses the date and
time information from µC/Clk to update files and directories with the proper
creation/modification/access time.
F3-1(7) µC/CRC is a stand-alone module for calculating checksums and error correction
codes. This module is used by some of µC/FS device drivers.
F3-1(8) This is the µC/FS platform-independent code, free of dependencies on CPU
and memory device. This code is written in highly-portable ANSI C code. This
code is only available to µC/FS licensees.
F3-1(9) This is the µC/FS system driver for FAT file systems. This code is only available
to µC/FS licensees.
600-uC-FS-001.book Page 31 Wednesday, October 10, 2012 12:03 PM
32
Chapter 3
F3-1(10) This is the collection of device drivers for µC/FS. Each driver supports a certain
device type, such as SD/MMC cards, NAND flash or NOR flash. Drivers are only
available to µC/FS licensees.
F3-1(11) This is the µC/FS code that is adapted to a specific platform. It consists of small
code modules written for specific drivers called ports that must be adapted to
the memory device controllers or peripherals integrated into or attached to the
CPU. The requirements for these ports are described in Appendix C, Porting
Manual.
F3-1(12) µC/FS does not require an RTOS. However, if µC/FS is used with an RTOS, a
set of functions must be implemented to prevent simultaneous access of
devices and core µC/FS structures by multiple tasks.
F3-1(13) This µC/FS configuration file defines which µC/FS features (fs_cfg.h) are
included in the application.
3-1 APPLICATION CODE
When Micriµm provides you with example projects, we typically place those in a directory
structure as shown below. Of course, you can use whatever directory structure suits your
project/product.
\Micrium
\Software
\EvalBoards
\<manufacturer>
\<board name>
\<compiler>
\<project name>
\*.*
\Micrium
This is where we place all software components and projects provided by Micriµm. This
directory generally starts from the root directory of your computer.
600-uC-FS-001.book Page 32 Wednesday, October 10, 2012 12:03 PM
33
Application Code
\Software
This sub-directory contains all the software components and projects.
\EvalBoards
This sub-directory contains all the projects related to the evaluation boards supported by
Micriµm.
\<manufacturer>
Is the name of the manufacturer of the evaluation board. The ‘<’ and ‘>’ are not part of the
actual name.
\<board name>
This is the name of the evaluation board. A board from Micriµm will typically be called
uC-Eval-xxxx where ‘xxxx’ will represent the CPU or MCU used on the evaluation board.
The ‘<’ and ‘>’ are not part of the actual name.
\<compiler>
This is the name of the compiler or compiler manufacturer used to build the code for the
evaluation board. The ‘<’ and ‘>’ are not part of the actual name.
\<project name>
This is the name of the project that will be demonstrated. For example a simple µC/FS
project might have a project name of ‘FS-Ex1’. The ‘-Ex1’ represents a project containing
only µC/FS. A project name of FS-Probe-Ex1 would represent a project containing µC/FS as
well as µC/Probe. The ‘<’ and ‘>’ are not part of the actual name.
\*.*
These are the source files for the project/product. You are certainly welcomed to call the
main files APP*.* for your own projects but you don’t have to. This directory also contains
the configuration file FS_CFG.H and other files as needed by the project.
600-uC-FS-001.book Page 33 Wednesday, October 10, 2012 12:03 PM
34
Chapter 3
3-2 CPU
As shown below is the directory where we place semiconductor manufacturer peripheral
interface source files. Of course, you can use whatever directory structure suits your
project/product.
\Micrium
\Software
\CPU
\<manufacturer>
\<architecture>
\*.*
\Micrium
This is where we place all software components and projects provided by Micriµm.
\Software
This sub-directory contains all the software components and projects.
\CPU
This sub-directory is always called CPU.
\<manufacturer>
Is the name of the semiconductor manufacturer who provided the peripheral library. The ‘<’
and ‘>’ are not part of the actual name.
\<architecture>
This is the name of the specific library and is generally associated with a CPU name or an
architecture.
\*.*
These are the library source files. The names of the files are determined by the
semiconductor manufacturer.
600-uC-FS-001.book Page 34 Wednesday, October 10, 2012 12:03 PM
35
Board Support Package (BSP)
3-3 BOARD SUPPORT PACKAGE (BSP)
The BSP is generally found with the evaluation or target board because the BSP is specific
to that board. In fact, if well written, the BSP should be used for multiple projects.
\Micrium
\Software
\EvalBoards
\<manufacturer>
\<board name>
\<compiler>
\BSP
\*.*
\Micrium
This is where we place all software components and projects provided by Micriµm.
\Software
This sub-directory contains all the software components and projects.
\EvalBoards
This sub-directory contains all the projects related to evaluation boards.
\<manufacturer>
Is the name of the manufacturer of the evaluation board. The ‘<’ and ‘>’ are not part of the
actual name.
\<board name>
This is the name of the evaluation board. A board from Micriµm will typically be called uC
Eval xxxx where ‘xxxx’ will be the name of the CPU or MCU used on the evaluation board.
The ‘<’ and ‘>’ are not part of the actual name.
\<compiler>
This is the name of the compiler or compiler manufacturer used to build the code for the
evaluation board. The ‘<’ and ‘>’ are not part of the actual name.
\BSP
This directory is always called BSP.
600-uC-FS-001.book Page 35 Wednesday, October 10, 2012 12:03 PM
36
Chapter 3
\*.*
These are the source files of the BSP. Typically all the file names start with BSP_ but they
don’t have to. It’s thus typical to find bsp.c and bsp.h in this directory. Again, the BSP code
should contain functions such as LED control functions, initialization of timers, interface to
Ethernet controllers and more.
3-4 µC/CPU, CPU SPECIFIC SOURCE CODE
µC/CPU consists of files that encapsulate common CPU-specific functionality as well as
CPU- and compiler-specific data types.
\Micrium
\Software
\uC-CPU
\cpu_core.c
\cpu_core.h
\cpu_def.h
\Cfg\Template
\cpu_cfg.h
\<architecture>
\<compiler>
\cpu.h
\cpu_a.asm
\cpu_c.c
\Micrium
This directory contains all software components and projects provided by Micriµm.
\Software
This sub-directory contains all the software components and projects.
\uC-CPU
This is the main µC/CPU directory.
600-uC-FS-001.book Page 36 Wednesday, October 10, 2012 12:03 PM
37
µC/CPU, CPU Specific Source Code
cpu_core.c contains C code that is common to all CPU architectures. Specifically, this
file contains functions to measure the interrupt disable time of the
CPU_CRITICAL_ENTER() and CPU_CRITICAL_EXIT() macros, a function that emulates a
count leading zeros instruction and a few other functions.
cpu_core.h contains the function prototypes of the functions provided in cpu_core.c
as well as allocation of the variables used by this module to measure interrupt disable
time.
cpu_def.h contains miscellaneous #define constants used by the µC/CPU module.
\Cfg\Template
This directory contains a configuration template file (cpu_cfg.h) that you will need to copy
to your application directory in order to configure the µC/CPU module based on your
application requirements.
cpu_cfg.h determines whether you will enable measurement of the interrupt disable
time, whether your CPU implements a count leading zeros instruction in assembly
language or whether it will need to be emulated in C and more.
\<architecture>
This is the name of the CPU architecture for which µC/CPU was ported to. The ‘<’ and ‘>’
are not part of the actual name.
\<compiler>
This is the name of the compiler or compiler manufacturer used to build the code for the
µC/CPU port. The ‘<’ and ‘>’ are not part of the actual name.
The files in this directory contain the µC/CPU port.
cpu.h contains type definitions to make µC/FS and other modules independent of the
CPU and compiler word sizes. Specifically, you will find the declaration of the
CPU_INT16U, CPU_INT32U, CPU_FP32 and many other data types. Also, this file specifies
whether the CPU is a big- or little-endian machine and contains function prototypes for
functions that are specific to the CPU architecture and more.
600-uC-FS-001.book Page 37 Wednesday, October 10, 2012 12:03 PM
38
Chapter 3
cpu_a.asm contains the assembly language functions to implement the code to disable
and enable CPU interrupts, count leading zeros (if the CPU supports that instruction)
and other CPU specific functions that can only be written in assembly language. This
file could also contain code to enable caches, setup MPUs and MMU and more. The
functions provided in this file are accessible from C.
cpu_c.c contains C code of functions that are specific to the specific CPU architecture
but written in C for portability. As a general rule, if a function can be written in C then
it should, unless there are significant performance benefits by writing it in assembly
language.
3-5 µC/LIB, PORTABLE LIBRARY FUNCTIONS
µC/LIB consists of library functions that are meant to be highly portable and not tied to any
specific compiler. This was done to facilitate third party certification of Micriµm products.
\Micrium
\Software
\uC-LIB
\lib_ascii.c
\lib_ascii.h
\lib_def.h
\lib_math.c
\lib_math.h
\lib_mem.c
\lib_mem.h
\lib_str.c
\lib_str.h
\Cfg\Template
\lib_cfg.h
\Ports
\<architecture>
\<compiler>
\lib_mem_a.asm
\Micrium
This directory contains all software components and projects provided by Micriµm.
600-uC-FS-001.book Page 38 Wednesday, October 10, 2012 12:03 PM
39
µC/Clk, Time/Calendar Management
\Software
This sub-directory contains all the software components and projects.
\uC-LIB
This is the main µC/LIB directory.
\Cfg\Template
This directory contains a configuration template file (lib_cfg.h) that must be copied to the
application directory to configure the µC/LIB module based on application requirements.
lib_cfg.h determines whether to enable assembly-language optimization (assuming
there is an assembly-language file for the processor, i.e. lib_mem_a.asm) and a few
other #defines.
3-6 µC/CLK, TIME/CALENDAR MANAGEMENT
µC/Clk consists of functions that are meant to centralize time management in one
independant module. This way, the same time info can be easily shared across all Micrium
products.
\Micrium
\Software
\uC-Clk
\Cfg
\Template
\clk_cfg.h
\OS
\<rtos_name>
\clk_os.c
\Source
\clk.c
\clk.h
\Micrium
This directory contains all software components and projects provided by Micriµm.
600-uC-FS-001.book Page 39 Wednesday, October 10, 2012 12:03 PM
40
Chapter 3
\Software
This sub-directory contains all the software components and projects.
\uC-Clk
This is the main µC/Clk directory.
\Cfg\Template
This directory contains a configuration template file (clk_cfg.h) that must be copied to the
application directory to configure the µC/Clk module based on application requirements.
clk_cfg.h determines whether clock will be managed by the RTOS or in your
application. A few other #defines are used to enable/disable some features of µC/Clk
and to configure some parameteres, like the clock frequency.
\OS
This is the main OS directory.
\<rtos_name>
This is the directory that contains the file to perform RTOS abstraction. Note that the file for
the selected RTOS abstraction layer must always be named clk_os.c.
µC/Clk has been tested with µC/OS-II, µC/OS-III and the RTOS layer files for these RTOS
are found in the following directories:
\Micrium\Software\uC-Clk\OS\uCOS-II\clk_os.c
\Micrium\Software\uC-Clk\OS\uCOS-III\clk_os.c
\Source
This directory contains the CPU-independant source code for µC/Clk. All file in this
directory should be included in the build (assuming the presence of the source code).
Features that are not required will be compiled out based on the value of #define constants
in clk_cfg.h.
600-uC-FS-001.book Page 40 Wednesday, October 10, 2012 12:03 PM
41
µC/CRC, Checksums and Error Correction Codes
3-7 µC/CRC, CHECKSUMS AND ERROR CORRECTION CODES
µC/CRC consists of functions to compute different error detection and correction codes. The
functions are speed-optimized to avoid the important impact on performances that these
CPU-intensive calcutions may present.
\Micrium
\Software
\uC-CRC
\Cfg
\Template
\crc_cfg.h
\Ports
\<architecture>
\<compiler>
\ecc_hamming_a.asm
\edc_crc_a.asm
\Source
\edc_crc.h
\edc_crc.c
\ecc_hamming.h
\ecc_hamming.c
\ecc.h
\crc_util.h
\crc_util.c
\Micrium
This directory contains all software components and projects provided by Micriµm.
\Software
This sub-directory contains all the software components and projects.
\uC-CRC
This is the main µC/CRC directory.
\Cfg\Template
This directory contains a configuration template file (crc_cfg.h) that must be copied to the
application directory to configure the µC/CRC module based on application requirements.
600-uC-FS-001.book Page 41 Wednesday, October 10, 2012 12:03 PM
42
Chapter 3
crc_cfg.h determines whether to enable assembly-language optimization
(assuming there is an assembly-language file for the processor) and a few other
#defines.
\<architecture>
The name of the CPU architecture that µC/CRC was ported to. The ‘<’ and ‘>’ are not part of
the actual name.
\<compiler>
The name of the compiler or compiler manufacturer used to build code for the µC/CRC
port. The ‘<’ and ‘>’ are not part of the actual name.
ecc_hamming_a.asm contains the assembly language functions to optimize the
calculation speed of Hamming code.
edc_crc_a.asm contains the assembly language functions to optimize the calculation
speed of CRC (cyclic redundancy checks).
\Source
This is the directory that contains all the CPU independent source code files. of µC/CRC.
3-8 µC/FS PLATFORM-INDEPENDENT SOURCE CODE
The files in these directories are available to µC/FS licensees (see Appendix H, Licensing
Policy).
\Micrium
\Software
\uC-FS
\APP\Template
\fs_app.c
\fs_app.h
\Cfg\Template
\fs_cfg.h
\OS\Template
\fs_os.c
\fs_os.h
600-uC-FS-001.book Page 42 Wednesday, October 10, 2012 12:03 PM
43
µC/FS Platform-Independent Source Code
\Source
\fs_c
\fs.h
\fs_api.c
\fs_api.h
\fs_buf.c
\fs_buf.h
\fs_cache.c
\fs_cache.h
\fs_cfg_fs.h
\fs_ctr.h
\fs_def.h
\fs_dev.c
\fs_dev.h
\fs_dir.c
\fs_dir.h
\fs_entry.c
\fs_entry.h
\fs_err.h
\fs_file.c
\fs_file.h
\fs_inc.h
\fs_partition.c
\fs_partition.h
\fs_sys.c
\fs_sys.h
\fs_type.h
\fs_unicode.c
\fs_unicode.h
\fs_util.c
\fs_util.h
\fs_vol.c
\fs_vol.h
\Micrium
This is where we place all software components and projects provided by Micriµm.
600-uC-FS-001.book Page 43 Wednesday, October 10, 2012 12:03 PM
44
Chapter 3
\Software
This sub-directory contains all the software components and projects.
\uC-FS
This is the main µC/FS directory.
\APP\Template
This directory contains a template of the code for initializing the file system.
\Cfg\Template
This directory contains a configuration template file (lib_cfg.h) that is required to be copied
to the application directory to configure the µC/FS module based on application
requirements.
fs_cfg.h specifies which features of µC/FS you want in your application. If µC/FS is
provided in linkable object code format then this file will be provided to show you
what features are available in the object file. See Appendix B, µC/FS Configuration
Manual.
\Source
This directory contains the platform-independent source code for µC/FS. All the files in this
directory should be included in your build (assuming you have the source code). Features
that you don’t want will be compiled out based on the value of #define constants in
fs_cfg.h.
fs.c/h contains core functionality for µC/FS including FS_Init() (called to initialize
µC/FS) and FS_WorkingDirSet()/FS_WorkingDirGet() (used to get and set the
working directory).
fs_api.c/h contains the code for the POSIX-compatible API. See Chapter x, API for
details about the POSIX-compatible API.
fs_buf.c/h contains the code for the buffer management (used internally by µC/FS).
fs_dev.c/h contains code for device management. See Chapter x, Devices for details
about devices.
600-uC-FS-001.book Page 44 Wednesday, October 10, 2012 12:03 PM
45
µC/FS FAT Filesystem Source Code
fs_dir.c/h contains code for directory access. See Chapter x, Directories for details
about directory access.
fs_entry.c/h contains code for entry access. See Chapter x, Entries for details about
entry access.
fs_file.c/h contains code for file access. See Chapter x, Files for details about file
access.
fs_inc.h is a master include file that includes all
fs_sys.c/h contains the code for system driver management (used internally by
µC/FS).
fs_unicode.c/h contains the code for handling Unicode strings (used internally by
µC/FS).
3-9 µC/FS FAT FILESYSTEM SOURCE CODE
The files in these directories are available to µC/FS licensees (see Appendix H, Licensing
Policy).
\Micrium
\Software
\uC-FS
\FAT
\fs_fat.c
\fs_fat.h
\fs_fat_dir.c
\fs_fat_dir.h
\fs_fat_entry.c
\fs_fat_entry.h
\fs_fat_fat12.c
\fs_fat_fat12.h
\fs_fat_fat16.c
\fs_fat_fat16.h
\fs_fat_fat32.c
600-uC-FS-001.book Page 45 Wednesday, October 10, 2012 12:03 PM
46
Chapter 3
\fs_fat_fat32.h
\fs_fat_file.c
\fs_fat_file.h
\fs_fat_journal.c
\fs_fat_journal.h
\fs_fat_lfn.c
\fs_fat_lfn.h
\fs_fat_sfn.c
\fs_fat_sfn.h
\fs_fat_type.h
\Micrium
This is where we place all software components and projects provided by Micriµm.
\Software
This sub-directory contains all the software components and projects.
\uC-FS
This is the main µC/FS directory.
\FAT
This directory contains the FAT system driver for µC/FS. All the files in this directory should
be included in your build (assuming you have the source code).
3-10 µC/FS MEMORY DEVICE DRIVERS
These files are generic drivers to use with differenty memory devices.
\Micrium
\Software
\uC-FS
\Dev
\MSC
\fs_dev_msc.c
\fs_dev_msc.h
\NAND
600-uC-FS-001.book Page 46 Wednesday, October 10, 2012 12:03 PM
47
µC/FS Memory Device Drivers
\fs_dev_nand.c
\fs_dev_nand.h
\Ctrlr
\fs_dev_nand_ctrlr_gen.c
\fs_dev_nand_ctrlr_gen.h
\fs_dev_nand_ctrlr_gen_soft_ecc.c
\fs_dev_nand_ctrlr_gen_soft_ecc.h
\fs_dev_nand_ctrlr_gen_micron_ecc.c
\fs_dev_nand_ctrlr_gen_micron_ecc.h
\Part
\fs_dev_nand_part_static.c
\fs_dev_nand_part_static.h
\fs_dev_nand_part_onfi.c
\fs_dev_nand_part_onfi.h
\Cfg\Template
fs_dev_nand_cfg.h
\BSP\Template
\fs_dev_nand_ctrlr_gen_bsp.c
\NOR
\fs_dev_nor.c
\fs_dev_nor.h
\PHY
\fs_dev_nor_amd_1x08.c
\fs_dev_nor_amd_1x08.h
\fs_dev_nor_amd_1x16.c
\fs_dev_nor_amd_1x16.h
\fs_dev_nor_intel.c
\fs_dev_nor_intel.h
\fs_dev_nor_sst25.c
\fs_dev_nor_sst25.h
\fs_dev_nor_sst39.c
\fs_dev_nor_sst39.h
\fs_dev_nor_stm25.c
\fs_dev_nor_stm25.h
\fs_dev_nor_stm29_1x08.c
\fs_dev_nor_stm29_1x08.h
\fs_dev_nor_stm29_1x16.c
\fs_dev_nor_stm29_1x16.h
600-uC-FS-001.book Page 47 Wednesday, October 10, 2012 12:03 PM
48
Chapter 3
\Template
\fs_dev_nor_template.c
\fs_dev_nor_template.h
\BSP\Template
\fs_dev_nor_bsp.c
\BSP\Template (SPI GPIO)
\fs_dev_nor_bsp.c
\BSP\Template (SPI)
\fs_dev_nor_bsp.c
\RAMDisk
\fs_dev_ram.c
\fs_dev_ram.h
\SD
\fs_dev_sd.c
\fs_dev_sd.h
\Card
\fs_dev_sd_card.c
\fs_dev_sd_card.h
\BSP\Template
\fs_dev_sd_card_bsp.c
\SPI
\fs_dev_sd_spi.c
\fs_dev_sd_spi.h
\BSP\Template
\fs_dev_sd_spi.bsp.c
\Template
\fs_dev_template.c
\fs_dev_template.h
\Micrium
This directory contains all software components and projects provided by Micriµm.
\Software
This sub-directory contains all the software components and projects.
\uC-FS
This is the main µC/FS directory.
600-uC-FS-001.book Page 48 Wednesday, October 10, 2012 12:03 PM
49
µC/FS Memory Device Drivers
\Dev
This is where you will find the device driver files for the storage devices you are planning
on using.
\MSC
This directory contains the MSC (Mass Storage Class - USB drives) driver files.
fs_dev_msc.* are device driver for MSC devices. This driver is designed to work with
µC/USB host stack.
For more details on this driver, please refer to Chapter 15, “MSC Driver” on page 219.
\NAND
This directory contains the NAND driver files.
fs_dev_nand.* are the device driver for NAND devices. These files require a set of
controller-layer functions (defined in a file named fs_dev_nand_ctrlr_<type>.*) as
well as BSP functions specific to particular hardware and associated with chosen
controller-layer (to be defined in a file named fs_dev_nand_ctrlr_<type>_bsp.c).
Note that in the case of the “generic” controller-layer implementation, some controller
extensions files (defined in files named fs_dev_nand_ctrlr_<ext_name>.*) may also
be required.
For more details on this driver, please refer to Chapter 13, “NAND Flash Driver” on
page 159.
\NOR
This directory contains the NOR driver files.
fs_dev_nor.* are the device driver for NOR devices. These files require a set of
physical-layer functions (defined in a file name fs_dev_nor_<physical type>.*) as
well as BSP functions (to be defined in a file named fs_dev_nor_bsp.c) to work with
a particular hardware setup.
For more details on this driver, please refer to Chapter 14, “NOR Flash Driver” on page 199.
600-uC-FS-001.book Page 49 Wednesday, October 10, 2012 12:03 PM
50
Chapter 3
\RAMDisk
This directory contains the RAM disk driver files.
fs_dev_ramdisk.* constitue the RAM disk driver.
For more details on this driver, please refer to Chapter 11, “RAM Disk Driver” on page 131.
\SD
This directory contains the SD/MMC driver files.
fs_dev_sd.* are device driver for SD devices. Theses files require to be used with
either the fs_dev_sd_spi.* (for SPI/one-wire mode) or fs_dev_sd_card.* (for
Card/4-wires mode) files. These files require a set of BSP functions to be defined in a
file named either fs_dev_sd_spi_bsp.c or fs_dev_sd_card_bsp.c to work with a
particular hardware setup.
For more details on this driver, please refer to Chapter 12, “SD/MMC Drivers” on page 135.
3-11 µC/FS PLATFORM-SPECIFIC SOURCE CODE
These files are provided by the µC/FS device driver developer. See Chapter 17, Porting
µC/FS. However, the µC/FS source code is delivered with port examples.
\Micrium
\Software
\uC-FS
\Examples
\BSP
\Dev
<memory type>
<manufacturer>
<board name>
\fs_dev_<memory type>_bsp.c
\Micrium
This directory contains all software components and projects provided by Micriµm.
600-uC-FS-001.book Page 50 Wednesday, October 10, 2012 12:03 PM
51
µC/FS OS Abstraction Layer
\Software
This sub-directory contains all the software components and projects.
\uC-FS
This is the main µC/FS directory.
\Examples
This is where you will find the device driver BSP example files.
\Dev\<memory type>
This is where you will find the examples BSP for one memory type. The ‘<’ and ‘>’ are not
part of the actual name. The memory types supported by µC/FS are the following: NAND,
NOR, SD\CARD, SD\SPI.
\<manufacturer>
The name of the manufacturer of the evaluation board. The ‘<’ and ‘>’ are not part of the
actual name.
3-12 µC/FS OS ABSTRACTION LAYER
This directory contains the RTOS abstraction layer which allows the use of µC/FS with
nearly any commercial of in-house RTOS, or without any RTOS at all. The abstraction layer
for the selected RTOS is placed in a sub-directory under OS as follows:
\Micrium
\Software
\uC-FS
\OS
\<rtos_name>
\fs_os.c
\fs_os.h
\Micrium
This directory contains all software components and projects provided by Micriµm.
\Software
This sub-directory contains all the software components and projects.
600-uC-FS-001.book Page 51 Wednesday, October 10, 2012 12:03 PM
52
Chapter 3
\uC-FS
This is the main µC/FS directory.
\OS
This is the main OS directory.
\<rtos_name>
This is the directory that contains the files to perform RTOS abstraction. Note that files for
the selected RTOS abstraction layer must always be named fs_os.*.
µC/FS has been tested with µC/OS-II, µC/OS-III and without an RTOS. The RTOS layer files
are found in the following directories:
\Micrium\Software\uC-Clk\OS\None\fs_os.*
\Micrium\Software\uC-Clk\OS\Template\fs_os.*
\Micrium\Software\uC-Clk\OS\uCOS-II\fs_os.*
\Micrium\Software\uC-Clk\OS\uCOS-III\fs_os.*
3-13 SUMMARY
Below is a summary of all the directories and files involved in a µC/FS-based project. The
‘<-Cfg’ on the far right indicates that these files are typically copied into the application
(i.e., project) directory and edited based on project requirements.
\Micrium
\Software
\EvalBoards
\<manufacturer>
\<board name>
\<compiler>
\<project name>
\app.c
\app.h
\other
\BSP
\bsp.c
\bsp.h
600-uC-FS-001.book Page 52 Wednesday, October 10, 2012 12:03 PM
53
Summary
\other
\CPU
\<manufacturer>
\<architecture>
\*.*
\uC-FS
\APP\Template
\fs_app.c <-Cfg
\fs_app.h <-Cfg
\CFG\Template
\fs_cfg.h <-Cfg
\Dev
\MSC
\fs_dev_msc.c
\fs_dev_msc.h
\NAND
\fs_dev_nand.c
\fs_dev_nand.h
\Ctrlr
\fs_dev_nand_ctrlr_gen.c
\fs_dev_nand_ctrlr_gen.h
\fs_dev_nand_ctrlr_gen_soft_ecc.c
\fs_dev_nand_ctrlr_gen_soft_ecc.h
\fs_dev_nand_ctrlr_gen_micron_ecc.c
\fs_dev_nand_ctrlr_gen_micron_ecc.h
\Part
\fs_dev_nand_part_static.c
\fs_dev_nand_part_static.h
\fs_dev_nand_part_onfi.c
\fs_dev_nand_part_onfi.h
\Cfg\Template
fs_dev_nand_cfg.h
\BSP\Template
\fs_dev_nand_ctrlr_gen_bsp.c
\NOR
\fs_dev_nor.c
\fs_dev_nor.h
600-uC-FS-001.book Page 53 Wednesday, October 10, 2012 12:03 PM
54
Chapter 3
\PHY
\fs_dev_nor_amd_1x08.c
\fs_dev_nor_amd_1x08.h
\fs_dev_nor_amd_1x16.c
\fs_dev_nor_amd_1x16.h
\fs_dev_nor_intel.c
\fs_dev_nor_intel.h
\fs_dev_nor_sst25.c
\fs_dev_nor_sst25.h
\fs_dev_nor_sst39.c
\fs_dev_nor_sst39.h
\fs_dev_nor_stm25.c
\fs_dev_nor_stm25.h
\fs_dev_nor_stm29_1x08.c
\fs_dev_nor_stm29_1x08.h
\fs_dev_nor_stm29_1x16.c
\fs_dev_nor_stm29_1x16.h
\Template
\fs_dev_nor_template.c <-Cfg
\fs_dev_nor_template.h <-Cfg
\BSP\<template>
\fs_dev_nor_bsp.c <-Cfg
\RAMDisk
\fs_dev_ram.c
\fs_dev_ram.h
\SD
\fs_dev_sd.c
\fs_dev_sd.h
\Card
\fs_dev_sd_card.c
\fs_dev_sd_card.h
\BSP\Template
\fs_dev_sd_card_bsp.c <-Cfg
\SPI
\fs_dev_sd_spi.c
\fs_dev_sd_spi.h
\BSP\Template
\fs_dev_sd_spi.bsp.c <-Cfg
600-uC-FS-001.book Page 54 Wednesday, October 10, 2012 12:03 PM
55
Summary
\Template
\fs_dev_template.c <-Cfg
\fs_dev_template.h <-Cfg
\FAT
\fs_fat.c
\fs_fat.h
\fs_fat_dir.c
\fs_fat_dir.h
\fs_fat_entry.c
\fs_fat_entry.h
\fs_fat_fat12.c
\fs_fat_fat12.h
\fs_fat_fat16.c
\fs_fat_fat16.h
\fs_fat_fat32.c
\fs_fat_fat32.h
\fs_fat_file.c
\fs_fat_file.h
\fs_fat_journal.c
\fs_fat_journal.h
\fs_fat_lfn.c
\fs_fat_lfn.h
\fs_fat_sfn.c
\fs_fat_sfn.h
\fs_fat_type.h
\OS
\<template>
\fs_os.c <-Cfg
\fs_os.h <-Cfg
\<rtos_name>
\fs_os.c
\fs_os.h
\Source
\fs_c
\fs.h
\fs_api.c
\fs_api.h
\fs_buf.c
600-uC-FS-001.book Page 55 Wednesday, October 10, 2012 12:03 PM
56
Chapter 3
\fs_buf.h
\fs_cache.c
\fs_cache.h
\fs_cfg_fs.h
\fs_ctr.h
\fs_def.h
\fs_dev.c
\fs_dev.h
\fs_dir.c
\fs_dir.h
\fs_entry.c
\fs_entry.h
\fs_err.h
\fs_file.c
\fs_file.h
\fs_inc.h
\fs_partition.c
\fs_partition.h
\fs_sys.c
\fs_sys.h
\fs_type.h
\fs_unicode.c
\fs_unicode.h
\fs_util.c
\fs_util.h
\fs_vol.c
\fs_vol.h
\OS
\<architecture>
\<compiler>
\os_cpu.h
\os_cpu_a.asm
\os_cpu_c.c
\uC-CPU
\cpu_core.c
\cpu_core.h
\cpu_def.h
\Cfg\Template
600-uC-FS-001.book Page 56 Wednesday, October 10, 2012 12:03 PM
57
Summary
\cpu_cfg.h <-Cfg
\<architecture>
\<compiler>
\cpu.h
\cpu_a.asm
\cpu_c.c
\uC-Clk
\Cfg
\Template
\clk_cfg.h <-Cfg
\OS
\<rtos_name>
\clk_os.c
\Source
\clk.c
\clk.h
\uC-CRC
\Cfg
\Template
\crc_cfg.h <-Cfg
\Ports
\<architecture>
\<compiler>
\ecc_hamming_a.asm
\edc_crc_a.asm
\Source
\edc_crc.h
\edc_crc.c
\ecc_hamming.h
\ecc_hamming.c
\ecc.h
\uC-LIB
\lib_ascii.c
\lib_ascii.h
\lib_def.h
\lib_math.c
\lib_math.h
\lib_mem.c
600-uC-FS-001.book Page 57 Wednesday, October 10, 2012 12:03 PM
58
Chapter 3
\lib_mem.h
\lib_str.c
\lib_str.h
\Cfg\Template
\lib_cfg.h <-Cfg
600-uC-FS-001.book Page 58 Wednesday, October 10, 2012 12:03 PM
59
Chapter
4
Useful Information
4-1 NOMENCLATURE
This manual uses a set of terms to consistently describe operation of µC/FS and its hardware
and software environment. The following is a small list of these terms, with definitions.
A file system suite is software which can find and access files and directories. Using “file
system suite” rather than “file system” eliminates any need for disambiguation among the
second term’s several meanings, which include “a system for organizing directories and
files”, “a collection of files and directories stored on a drive” and (commonly) the software
which will be referred to as a file system suite. The term file system will always mean a
collection of files and directories stored on a drive (or, in this document, volume).
A device driver (or just driver) is a code module which allows the general-purpose file
system suite to access a specific type of device. A device driver is registered with the file
system suite.
A device is an instance of a device type that is accessed using a device driver. An
addressable area (typically of 512 bytes) on a device is a sector. A sector is the smallest area
that (from the file system suite’s point of view) can be atomically read or written.
Several devices can use the same device driver. These are distinguished by each having a
unique unit number. Consequently, <DEVICE NAME>:<UNIT NUMBER>: is a unique device
identifier if all devices are required to have unique names. That requirement is enforced in
this file system suite.
600-uC-FS-001.book Page 59 Wednesday, October 10, 2012 12:03 PM
60
Chapter 4
A logical device is the combination of two or more separate devices. To form a logical
device, the sector address spaces of the constituent devices are concatenated to form a
single continuous address space.
A device can be partitioned, or subdivided into one or more regions (called partitions)
each consisting of a number of consecutive sectors. Typically, structures are written to the
device instructing software as to the location and size of these partitions. This file system
suite supports DOS partitions.
A volume is a device or device partition with a file system. A device or device partition
must go through a process called mounting to become a volume, which includes finding
the file system and making it ready for use. The name by which a volume is addressed may
also be called the volume’s mount point.
A device or volume may be formatted to create a new file system on the device. For
disambiguation purposes, this process is also referred to as high-level formatting. The
volume or device will automatically be mounted once formatting completes.
For certain devices, it is either necessary or desirable to perform low-level formatting.
This is the process of associating logical sector numbers with areas of the device.
A file system driver is a code module which allows the general-purpose file system suite
to access a specific type of file system. For example, this file system suite includes a FAT file
system driver.
FAT (File Allocation Table) is a common file system type, prevalent in removable media
that must work with various OSs. It is named after its primary data structure, a large table
that records what clusters of the disk are allocated. A cluster, or group of sectors, is the
minimum data allocation unit of the FAT file system.
600-uC-FS-001.book Page 60 Wednesday, October 10, 2012 12:03 PM
61
C/FS Device and Volume Names
4-2 C/FS DEVICE AND VOLUME NAMES
Devices are specified by name. For example, a device can be opened:
FSDev_Open(“sd:0:”, (void *)0, &err);
In this case, “sd:0:” is the device name. It is a concatenation of:
sd The name of the device driver
:A single colon
0The unit number
:A final colon
The unit number allows multiple devices of the same type; for example, there could be
several SD/MMC devices connected to the CPU: “sd:0:”, “sd:1”, “sd:2”…
The maximum length of a device name is FS_CFG_MAX_DEV_NAME_LEN; this must be at least
three characters larger than the maximum length of a device driver name,
FS_CFG_MAX_DEV_DRV_NAME_LEN. A device name (or device driver name) must not contain
the characters:
: \ /
Volumes are also specified by name. For example, a volume can be formatted:
FSVol_Fmt(“vol:”, (void *)0, &err);
Here, “vol:” is the volume name. µC/FS imposes no restrictions on these names, except
that they must end with a colon (‘:’), must be no more than FS_CFG_MAX_VOL_NAME_LEN
characters long, and must not contain either of the characters ‘\’ or ‘/’:
600-uC-FS-001.book Page 61 Wednesday, October 10, 2012 12:03 PM
62
Chapter 4
It is typical to name a volume the same as a device; for example, a volume may be opened:
FSVol_Open(“sd:0:” (a)
“sd:0:” (b)
(void *)0,
&err);
In this case, the name of the volume (a) is the same as the name as the device (b). When
multiple volumes exist in the same application, the volume name should be prefixed to the
file or directory path name:
p_file = fs_fopen(“sd:0:\\dir01\file01.txt”, “w”); // File on SD card
p_file = fs_fopen(“ram:0:\\dir01\file01.txt”, “w”); // File on RAM disk
4-3 C/FS FILE AND DIRECTORY NAMES AND PATHS
Files and directories are identified by a path string; for example, a file can be opened:
p_file = fs_fopen(“\\test\\file001.txt”, “w”);
In this case, “\\test\\file001.txt” is the path string.
An application specifies the path of a file or directory using either an absolute or a relative path.
An absolute path is a character string which specifies a unique file, and follows the pattern:
<vol_name>:<... Path ...><File>
where
<vol_name> is the name of the volume, identical to the string specified in
FSVol_Open().
<... Path ...> is the file path, which must always begin and end with a ‘\’.
<File> is the file (or leaf directory) name, including any extension.
600-uC-FS-001.book Page 62 Wednesday, October 10, 2012 12:03 PM
63
C/FS File and Directory Names and Paths
For example:
p_file = fs_fopen(“sd:0:\\file.txt”, “w”); (a)
p_file = fs_fopen(“\\file.txt”, “w”); (b)
p_file = fs_fopen(“sd:0:\\dir01\\file01.txt”, “w”); (c)
p_file = fs_opendir(“sd:0:\\”) (d)
p_file = fs_opendir(“\\”) (e)
p_file = fs_opendir(“sd:0:\\dir01\\”) (f)
Which demonstrate (a) opening a file in the root directory of a specified volume; (b)
opening a file in the root directory on a default volume; (c) opening a file in a non-root
directory; (d) opening the root directory of a specified volume; (e) opening the root
directory of the default volume; (f) opening a non-root directory.
Relative paths can be used if working directories are enabled (FS_CFG_WORKING_DIR_EN is
DEF_ENABLED — see Appendix E on page 501). A relative path begins with neither a
volume name nor a ‘\’:
<... Relative Path ...><File>
where
<... Relative Path ...> is the file path, which must not begin with a ‘\’ but
must end with a ‘\’.
<File> is the file (or leaf directory) name, including any
extension.
Two special path components can be used. “..” moves the path to the parent directory. “.”
keeps the path in the same directory (basically, it does nothing).
A relative path is appended to the current working directory of the calling task to form the
absolute path of the file or directory. The working directory functions, fs_chdir() and
fs_getcwd(), can be used to set and get the working directory.
600-uC-FS-001.book Page 63 Wednesday, October 10, 2012 12:03 PM
64
Chapter 4
4-4 C/FS NAME LENGTHS
The configuration constants FS_CFG_MAX_PATH_NAME_LEN, FS_CFG_MAX_FILE_NAME_LEN
and FS_CFG_MAX_VOL_NAME_LEN in fs_cfg.h set the maximum length of path names, file
names and volume names. The constant FS_CFG_MAX_FULL_NAME_LEN is defined in
fs_cfg_fs.h to describe the maximum full name length. The path name begins with a path
separator character and includes the file name; the file name is just the portion of the path
name after the last (non-final) path separator character. The full name is composed of an
explicit volume name (optional) and a path name; the maximum full name length can be
calculated:
FullNameLenmax = VolNameLenmax + PathNameLenmax
Figure 2-3 demonstrates these definitions.
Figure 4-1 File, path and volume name lengths
No maximum parent name length is defined, though one may be derived. The parent name
must be short enough so that the path of a file in the directory would be valid. Strictly, the
minimum file name length is 1 character, though some OSs may enforce larger values
(eleven on some Windows systems), thereby decreasing the maximum parent name length.
ParentNameLenmax = PathNameLenmax - FileNameLenmin - 1
The constants FS_CFG_MAX_DEV_DRV_NAME_LEN and FS_CFG_MAX_DEV_NAME_LEN in
fs_cfg.h set the maximum length of device driver names and device names, as shown in
Figure 2-4. The device name is between three and five characters longer than the device
driver name, since the unit number (the integer between the colons of the device name)
must be between 0 and 255.
P\YROXPH?0\'LU?0\'LU?0\'LU?P\BYHU\BYHU\BORQJBILOHBQDPHW[W
ILOHQDPH
SDWKQDPH
IXOOQDPH
YROXPHQDPH
SDUHQWQDPH
600-uC-FS-001.book Page 64 Wednesday, October 10, 2012 12:03 PM
65
Resource Usage
Figure 4-2 Device and device driver name lengths
Each of the maximum name length configurations specifies the maximum string length
without the NULL character. Consequently, a buffer which holds one of these names must be
one character longer than the define value.
4-5 RESOURCE USAGE
µC/FS resource usage, of both ROM and RAM, depends heavily on application usage. How
many (and which) interface functions are referenced determines the code and constant data
space requirements. The greater the quantity of file system objects (buffers, files, directories,
devices and volumes), the more RAM needed.
Table 2-1 give the ROM usage for the file system core, plus additional components that can
be included optionally, collected on IAR EWARM v6.40.1. The ‘core’ ROM size includes all
file system components and functions (except those itemized in the table); this is
significantly larger than most installations because most applications use a fraction of the
API.
Table 4-1 ROM requirements
Component ROM, Thumb Mode ROM, ARM Mode
High Size Opt High Speed Opt High Size Opt High Speed Opt
Core* 43.1 kB 59.2 kB 66.5 kB 91.2 kB
OS port (μC/OS-III) 1.1 kB 1.4 kB 1.8 kB 2.2 kB
LFN support 4.3 kB 5.2 kB 6.9 kB 8.2 kB
Directories 1.7 kB 2.1 kB 2.7 kB 3.3 kB
Volume check 0.9 kB 1.0 kB 1.4 kB 1.6 kB
Partitions 1.3 kB 1.8 kB 2.2 kB 2.9 kB
VGFDUG
GHYLFHGULYHUQDPH
GHYLFHQDPH
600-uC-FS-001.book Page 65 Wednesday, October 10, 2012 12:03 PM
66
Chapter 4
*Includes code and data for all file system components and functions except those itemized in the table.
RAM requirements are summarized in Table 2-2. The total depends on the number of each
object allocated and the maximum sector size (set by values passed to FS_Init() in the file
system configuration structure), and various name length configuration parameters (see
Appendix E, “FS_CFG_MAX_PATH_NAME_LEN” on page 503).
Table 4-2 RAM characteristics
§ The number of tasks that use relative path names
See also section 9-1-1 “Driver Characterization” on page 113 for ROM/RAM characteristics of
file system suite drivers.
Item RAM (bytes)
Core 932
Per device 44 + FS_CFG_MAX_DEV_NAME_LEN
Per volume 152 + FS_CFG_MAX_VOL_NAME_LEN
Per file 144
Per directory 100
Per buffer 36 + MaxSectorSize
Per device driver 8 bytes
Working directories ((FS_CFG_MAX_PATH_NAME_LEN * 2) + 8) * TaskCnt§
600-uC-FS-001.book Page 66 Wednesday, October 10, 2012 12:03 PM
67
Chapter
5
Devices and Volumes
To begin reading files from a medium or creating files on a medium, that medium (hereafter
called a device) and the driver which will be used to access it must be registered with the
file system. After that, a volume must be opened on that device (analogous to “mounting”).
This operation will succeed if and only if the device responds and the file system control
structures (for FAT, the Boot Parameter Block or BPB) are located and validated.
In this manual, as in the design of µC/FS, the terms ‘device’ and ‘volume’ have distinct,
non-overlapping meanings. We define a ‘device’ as a single physical or logical entity which
contains a continuous sequence of addressable sectors. An SD/MMC card is a physical
device.
We define a ‘volume’ as a collection of files and directories on a device.
These definitions were selected so that multiple volumes could be opened on a device (as
shown in Figure 5-1) without requiring ambiguous terminology.
Figure 5-1 Device and volume architecture
partition1 partition1 partition2
ide:0: ide:1:
ide:0: ide:1a: ide:1b:
Device layer
Volume layer
600-uC-FS-001.book Page 67 Wednesday, October 10, 2012 12:03 PM
68
Chapter 5
5-1 DEVICE OPERATIONS
The ultimate purpose of a file system device is to hold data. Consequently, two major
operations that can occur on a device are the reading and writing of individual sectors. Five
additional operations can be performed which affect not just individual sectors, but the
whole device:
■A device can be opened. During the opening of a device, it is initialized and its
characteristics are determined (sector size, number of sectors, vendor).
■A device can be partitioned. Partitioning divides the final unallocated portion of the
device into two parts, so that a volume could be located on each (see section 5-5
“Partitions” on page 73).
■A device can be low-level formatted. Some device must be low-level formatted before
being used.
■A device can be (high-level) formatted. (High-level) formatting writes the control
information for a file system to a device so that a volume on it can be mounted.
Essentially, (high-level) formatting is the process of creating a volume on an empty
device or partition.
■A device can be closed. During the closing of a device, it is uninitialized (if necessary)
and associated structures are freed.
These operations and the corresponding API functions are discussed in this section. For
information about using device names, see section 4-2 “C/FS Device and Volume Names”
on page 61.
Function Description
FSDev_AccessLock() Acquire exclusive access to a device.
FSDev_AccessUnlock() Release exclusive access to a device.
FSDev_Close() Remove device from file system.
FSDev_GetNbrPartitions() Get number of partitions on a device.
FSDev_Invalidate() Invalidate files and volumes open on a device.
FSDev_IO_Ctrl() Perform device I/O control operation.
600-uC-FS-001.book Page 68 Wednesday, October 10, 2012 12:03 PM
