µC/FS User's Manual U C FS

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 538

DownloadµC/FS User's Manual U C-FS-Manual
Open PDF In BrowserView PDF
600-uC-FS-001.book Page 1 Friday, August 17, 2012 4:51 PM

μC/ FS

TM

The Embedded File System

User’s Manual

600-uC-FS-001.book Page 2 Friday, August 17, 2012 4:51 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 3 Friday, August 17, 2012 4:51 PM

Table of Contents
Chapter 1
1-1
1-2
1-3
1-4

Introduction .......................................................................................... 15
μC/FS .................................................................................................... 15
Typical Usages ..................................................................................... 17
Why FAT? ............................................................................................. 17
Chapter Contents ................................................................................. 18

Chapter 2
2-1
2-1-1
2-1-2
2-1-3
2-1-4
2-1-5
2-1-6
2-1-7
2-1-8

μC/FS Architecture .............................................................................. 23
Architecture Components ................................................................... 25
Your Application ................................................................................... 25
μC-LIB (Libraries) ................................................................................. 25
POSIX API Layer .................................................................................. 25
FS Layer ............................................................................................... 26
File System Driver Layer ...................................................................... 27
Device Driver Layer .............................................................................. 27
μC-CPU ................................................................................................ 28
RTOS Layer .......................................................................................... 28

Chapter 3
3-1
3-2
3-3
3-4
3-5
3-6
3-7
3-8
3-9
3-10

μC/FS Directories and Files ................................................................. 29
Application Code ................................................................................. 32
CPU ....................................................................................................... 34
Board Support Package (BSP) ............................................................ 35
μC/CPU, CPU Specific Source Code .................................................. 36
μC/LIB, Portable Library Functions ..................................................... 38
μC/Clk, Time/Calendar Management .................................................. 39
μC/CRC, Checksums and Error Correction Codes ............................ 41
μC/FS Platform-Independent Source Code ........................................ 42
μC/FS FAT Filesystem Source Code ................................................... 45
μC/FS Memory Device Drivers ............................................................ 46

3

600-uC-FS-001.book Page 4 Friday, August 17, 2012 4:51 PM

Table of Contents

3-11
3-12
3-13

μC/FS Platform-Specific Source Code ............................................... 50
μC/FS OS Abstraction Layer ............................................................... 51
Summary .............................................................................................. 52

Chapter 4
4-1
4-2
4-3
4-4
4-5

Useful Information ................................................................................ 59
Nomenclature ....................................................................................... 59
μC/FS Device and Volume Names ...................................................... 61
μC/FS File and Directory Names and Paths ....................................... 62
μC/FS Name Lengths ........................................................................... 64
Resource Usage ................................................................................... 65

Chapter 5
5-1
5-2
5-3
5-4
5-5
5-6
5-7
5-8
5-8-1
5-8-2

Devices and Volumes .......................................................................... 67
Device Operations ............................................................................... 68
Using Devices ...................................................................................... 69
Using Removable Devices ................................................................... 71
Raw Device IO ...................................................................................... 72
Partitions .............................................................................................. 73
Volume Operations .............................................................................. 76
Using Volumes ..................................................................................... 77
Using Volume Cache ............................................................................ 79
Choosing Cache Parameters ............................................................... 81
Other Caching & Buffering Mechanisms ............................................. 82

Chapter 6
6-1
6-1-1
6-1-2
6-1-3
6-1-4
6-1-5
6-2
6-2-1
6-2-2
6-2-3

Files ...................................................................................................... 83
File Access Functions .......................................................................... 84
Opening Files ....................................................................................... 85
Getting Information About a File ......................................................... 86
Configuring a File Buffer ...................................................................... 87
File Error Functions .............................................................................. 88
Atomic File Operations Using File Lock .............................................. 88
Entry Access Functions ....................................................................... 89
File and Directory Attributes ................................................................ 90
Creating New Files and Directories ..................................................... 91
Deleting Files and Directories ............................................................. 92

4

600-uC-FS-001.book Page 5 Friday, August 17, 2012 4:51 PM

Chapter 7
7-1

Directories ............................................................................................ 93
Directory Access Functions ................................................................ 94

Chapter 8
8-1
8-2
8-3
8-3-1
8-3-2
8-3-3
8-3-4
8-3-5
8-4
8-5

POSIX API ............................................................................................. 95
Supported Functions ........................................................................... 96
Working Directory Functions ............................................................... 97
File Access Functions .......................................................................... 98
Opening, Reading & Writing Files ..................................................... 100
Getting or Setting the File Position ................................................... 103
Configuring a File Buffer .................................................................... 104
Diagnosing a File Error ...................................................................... 106
Atomic File Operations Using File Lock ............................................ 106
Directory Access Functions .............................................................. 107
Entry Access Functions ..................................................................... 109

Chapter 9
9-1
9-1-1
9-2

Device Drivers .................................................................................... 111
Provided Device Drivers .................................................................... 112
Driver Characterization ...................................................................... 113
Drivers comparison ............................................................................ 115

Chapter 10
10-1
10-2
10-2-1
10-3
10-3-1
10-3-2
10-4
10-5
10-6
10-7
10-7-1
10-7-2

FAT File System ................................................................................. 117
Why Embedded Systems Use FAT ................................................... 117
organization of a FAT Volume ........................................................... 118
organization of Directories and Directory Entries ............................ 119
Organization of the File Allocation Table .......................................... 120
FAT12 / FAT16 / FAT32 ...................................................................... 122
Short and Long File Names ............................................................... 123
Formatting .......................................................................................... 126
Sources of Corruption in FAT volumes ............................................. 127
Optional Journaling System .............................................................. 127
Licensing Issues ................................................................................. 129
Licenses for Long File Names (LFNs) ............................................... 129
Extended File Allocation Table (exFAT) ............................................ 129

Chapter 11
11-1
11-2

RAM Disk Driver ................................................................................. 131
Files and Directories .......................................................................... 131
Using the RAM Disk Driver ................................................................ 132
5

600-uC-FS-001.book Page 6 Friday, August 17, 2012 4:51 PM

Table of Contents

Chapter 12
12-1
12-2
12-2-1
12-2-2
12-2-3
12-3
12-3-1
12-3-2
12-3-3

SD/MMC Drivers ................................................................................ 135
Files and Directories .......................................................................... 137
Using the SD/MMC CardMode Driver ............................................... 138
SD/MMC CardMode Communication ............................................... 141
SD/MMC CardMode Communication Debugging ............................ 144
SD/MMC CardMode BSP Overview .................................................. 148
Using the SD/MMC SPI Driver ........................................................... 150
SD/MMC SPI Communication ........................................................... 153
SD/MMC SPI Communication Debugging ........................................ 154
SD/MMC SPI BSP Overview .............................................................. 157

Chapter 13
13-1
13-2
13-3
13-3-1
13-3-2
13-4
13-4-1
13-4-2
13-5
13-6
13-7
13-8
13-8-1
13-8-2
13-8-3
13-8-4

NAND Flash Driver ............................................................................. 159
Getting started .................................................................................. 160
Architecture overview ........................................................................ 167
NAND translation layer ...................................................................... 168
Translation layer configuration .......................................................... 171
Translation layer source files ............................................................. 178
Controller layer ................................................................................... 178
Generic controller layer implementation ........................................... 179
Part layer ............................................................................................ 181
Board support package - generic controller .................................... 185
Board support package - other controllers ...................................... 186
Performance considerations ............................................................. 186
Development guide ............................................................................ 188
BSP development guide - generic controller ................................... 188
Generic controller extension development guide ............................ 191
ECC module development guide ...................................................... 193
Controller layer development guide .................................................. 194

Chapter 14
14-1
14-2
14-3
14-3-1
14-3-2
14-3-3

NOR Flash Driver ............................................................................... 199
Files and Directories .......................................................................... 200
Driver & Device Characteristics ......................................................... 202
Using a Parallel NOR Device ............................................................. 204
Driver Architecture ............................................................................. 208
Hardware ............................................................................................ 208
NOR BSP Overview ............................................................................ 210

6

600-uC-FS-001.book Page 7 Friday, August 17, 2012 4:51 PM

14-4
14-4-1
14-4-2
14-5
14-5-1
14-5-2
14-5-3
14-5-4
14-5-5

Using a Serial NOR Device ................................................................ 211
Hardware ............................................................................................ 212
NOR SPI BSP Overview ..................................................................... 213
Physical-Layer Drivers ....................................................................... 214
FSDev_NOR_AMD_1x08, FSDev_NOR_AMD_1x16 .......................... 215
FSDev_NOR_Intel_1x16 ..................................................................... 215
FSDev_NOR_SST39 ........................................................................... 216
FSDev_NOR_STM25 .......................................................................... 216
FSDev_NOR_SST25 ........................................................................... 217

Chapter 15
15-1
15-2

MSC Driver ......................................................................................... 219
Files and Directories .......................................................................... 219
Using the MSC Driver ........................................................................ 220

Appendix A
A-1
A-1-1
A-1-2
A-1-3
A-1-4
A-1-5
A-2
A-2-1
A-2-2
A-2-3
A-2-4
A-2-5
A-2-6
A-2-7
A-2-8
A-2-9
A-2-10
A-2-11
A-2-12
A-2-13
A-2-14
A-2-15

μC/FS API Reference ......................................................................... 223
General File System Functions .......................................................... 225
FS_DevDrvAdd() ................................................................................. 226
FS_Init() ............................................................................................... 227
FS_VersionGet() .................................................................................. 228
FS_WorkingDirGet() ............................................................................ 229
FS_WorkingDirSet() ............................................................................ 230
Posix API Functions ........................................................................... 231
fs_asctime_r() ..................................................................................... 234
fs_chdir() ............................................................................................. 235
fs_clearerr() ......................................................................................... 236
fs_closedir() ........................................................................................ 237
fs_ctime_r() ......................................................................................... 238
fs_fclose() ........................................................................................... 239
fs_feof() ............................................................................................... 240
fs_ferror() ............................................................................................ 241
fs_fflush() ............................................................................................ 242
fs_fgetpos() ......................................................................................... 243
fs_flockfile() ........................................................................................ 244
fs_fopen() ............................................................................................ 245
fs_fread() ............................................................................................. 246
fs_fseek() ............................................................................................ 247
fs_fsetpos() ......................................................................................... 249

7

600-uC-FS-001.book Page 8 Friday, August 17, 2012 4:51 PM

Table of Contents

A-2-16
A-2-17
A-2-18
A-2-19
A-2-20
A-2-21
A-2-22
A-2-23
A-2-24
A-2-25
A-2-26
A-2-27
A-2-28
A-2-29
A-2-30
A-2-31
A-2-32
A-3
A-3-1
A-3-2
A-3-3
A-3-4
A-3-5
A-3-6
A-3-7
A-3-8
A-3-9
A-3-10
A-3-11
A-3-12
A-3-13
A-3-14
A-3-15
A-3-16
A-4
A-4-1
A-4-2
A-4-3
8

fs_ftell() ............................................................................................... 250
fs_ftruncate() ...................................................................................... 251
fs_ftrylockfile() .................................................................................... 252
fs_funlockfile() .................................................................................... 253
fs_fwrite() ............................................................................................ 254
fs_getcwd() ......................................................................................... 255
fs_localtime_r() ................................................................................... 256
fs_mkdir() ............................................................................................ 257
fs_mktime() ......................................................................................... 258
fs_opendir() ......................................................................................... 259
fs_readdir_r() ....................................................................................... 260
fs_remove() ......................................................................................... 261
fs_rename() ......................................................................................... 263
fs_rewind() .......................................................................................... 265
fs_rmdir() ............................................................................................. 266
fs_setbuf() ........................................................................................... 267
fs_setvbuf() ......................................................................................... 268
Device Functions ............................................................................... 270
FSDev_AccessLock() ......................................................................... 273
FSDev_AccessUnlock() ...................................................................... 274
FSDev_Close() .................................................................................... 275
FSDev_GetDevName() ....................................................................... 276
FSDev_GetDevCnt() ........................................................................... 277
FSDev_GetDevCntMax() .................................................................... 278
FSDev_GetNbrPartitions() .................................................................. 279
FSDev_Invalidate() ............................................................................. 280
FSDev_Open() .................................................................................... 281
FSDev_PartitionAdd() ......................................................................... 283
FSDev_PartitionFind() ........................................................................ 284
FSDev_PartitionInit() .......................................................................... 286
FSDev_Query() ................................................................................... 287
FSDev_Rd() ......................................................................................... 288
FSDev_Refresh() ................................................................................. 289
FSDev_Wr() ......................................................................................... 291
Directory Access Functions .............................................................. 292
FSDir_Close() ...................................................................................... 293
FSDir_IsOpen() ................................................................................... 294
FSDir_Open() ...................................................................................... 295

600-uC-FS-001.book Page 9 Friday, August 17, 2012 4:51 PM

A-4-4
A-5
A-5-1
A-5-2
A-5-3
A-5-4
A-5-5
A-5-6
A-5-7
A-6
A-6-1
A-6-2
A-6-3
A-6-4
A-6-5
A-6-6
A-6-7
A-6-8
A-6-9
A-6-10
A-6-11
A-6-12
A-6-13
A-6-14
A-6-15
A-6-16
A-6-17
A-7
A-7-1
A-7-2
A-7-3
A-7-4
A-7-5
A-7-6
A-7-7
A-7-8
A-7-9
A-7-10

FSDir_Rd() .......................................................................................... 296
Entry Access Functions ..................................................................... 297
FSEntry_AttribSet() ............................................................................. 298
FSEntry_Copy() .................................................................................. 300
FSEntry_Create() ................................................................................ 302
FSEntry_Del() ...................................................................................... 304
FSEntry_Query() ................................................................................. 306
FSEntry_Rename() .............................................................................. 307
FSEntry_TimeSet() .............................................................................. 309
File Functions ..................................................................................... 311
FSFile_BufAssign() ............................................................................. 313
FSFile_BufFlush() ............................................................................... 315
FSFile_Close() ..................................................................................... 316
FSFile_ClrErr() .................................................................................... 317
FSFile_IsEOF() .................................................................................... 318
FSFile_IsErr() ...................................................................................... 319
FSFile_IsOpen() .................................................................................. 320
FSFile_LockAccept() .......................................................................... 321
FSFile_LockGet() ................................................................................ 322
FSFile_LockSet() ................................................................................ 323
FSFile_Open() ..................................................................................... 324
FSFile_PosGet() .................................................................................. 326
FSFile_PosSet() .................................................................................. 327
FSFile_Query() .................................................................................... 329
FSFile_Rd() ......................................................................................... 330
FSFile_Truncate() ................................................................................ 332
FSFile_Wr() ......................................................................................... 333
Volume Functions .............................................................................. 335
FSVol_Close() ..................................................................................... 337
FSVol_Fmt() ........................................................................................ 338
FSVol_GetDfltVolName() .................................................................... 340
FSVol_GetVolCnt() .............................................................................. 341
FSVol_GetVolCntMax() ....................................................................... 342
FSVol_GetVolName() .......................................................................... 343
FSVol_IsDflt() ...................................................................................... 344
FSVol_IsMounted() ............................................................................. 345
FSVol_LabelGet() ................................................................................ 346
FSVol_LabelSet() ................................................................................ 348
9

600-uC-FS-001.book Page 10 Friday, August 17, 2012 4:51 PM

Table of Contents

A-7-11
A-7-12
A-7-13
A-7-14
A-8
A-8-1
A-8-2
A-8-3
A-9
A-9-1
A-9-2
A-9-3
A-10
A-10-1
A-10-2
A-10-3
A-11
A-11-1
A-11-2
A-11-3
A-11-4
A-11-5
A-11-6
A-11-7
A-11-8
A-11-9
A-12
A-12-1
A-12-2
A-12-3
A-12-4
A-12-5

FSVol_Open() ...................................................................................... 350
FSVol_Query() ..................................................................................... 352
FSVol_Rd() .......................................................................................... 353
FSVol_Wr() .......................................................................................... 355
Volume Cache Functions ................................................................... 356
FSVol_CacheAssign() ......................................................................... 357
FSVol_CacheInvalidate () ................................................................... 359
FSVol_CacheFlush () .......................................................................... 360
SD/MMC Driver Functions ................................................................. 361
FSDev_SD_xxx_QuerySD() ................................................................ 362
FSDev_SD_xxx_RdCID() .................................................................... 364
FSDev_SD_xxx_RdCSD() ................................................................... 366
NAND Driver Functions ...................................................................... 368
FSDev_NAND_LowFmt() .................................................................... 369
FSDev_NAND_LowMount() ................................................................ 370
FSDev_NAND_LowUnmount() ........................................................... 372
NOR Driver Functions ........................................................................ 373
FSDev_NOR_LowFmt() ...................................................................... 374
FSDev_NOR_LowMount() .................................................................. 375
FSDev_NOR_LowUnmount() .............................................................. 376
FSDev_NOR_LowCompact() .............................................................. 377
FSDev_NOR_LowDefrag() .................................................................. 378
FSDev_NOR_PhyRd() ......................................................................... 379
FSDev_NOR_PhyWr() ......................................................................... 381
FSDev_NOR_PhyEraseBlk() ............................................................... 383
FSDev_NOR_PhyEraseChip() ............................................................ 385
FAT System Driver Functions ............................................................ 386
FS_FAT_JournalOpen() ....................................................................... 387
FS_FAT_JournalClose() ...................................................................... 388
FS_FAT_JournalStart() ........................................................................ 389
FS_FAT_JournalStop() ........................................................................ 390
FS_FAT_VolChk() ................................................................................ 391

Appendix B
B-1
B-2
B-3
B-4

μC/FS Error Codes ............................................................................. 393
System Error Codes ........................................................................... 393
Buffer Error Codes ............................................................................. 393
Cache Error Codes ............................................................................ 394
Device Error Codes ............................................................................ 394

10

600-uC-FS-001.book Page 11 Friday, August 17, 2012 4:51 PM

B-5
B-6
B-7
B-8
B-9
B-10
B-11
B-12
B-13
B-14
B-15

Device Driver Error Codes ................................................................. 395
Directory Error Codes ........................................................................ 395
ECC Error Codes ................................................................................ 395
Entry Error Codes .............................................................................. 395
File Error Codes ................................................................................. 396
Name Error Codes ............................................................................. 397
Partition Error Codes ......................................................................... 397
Pools Error Codes .............................................................................. 397
File System Error Codes .................................................................... 398
Volume Error Codes ........................................................................... 398
OS Layer Error Codes ........................................................................ 399

Appendix C
C-1
C-2
C-3
C-4
C-4-1
C-4-2
C-4-3
C-4-4
C-4-5
C-4-6
C-4-7
C-4-8
C-5
C-5-1
C-5-2
C-5-3
C-5-4
C-5-5
C-5-6
C-5-7
C-5-8
C-5-9
C-5-10
C-5-11
C-5-12

μC/FS Porting Manual ........................................................................ 401
Date/Time Management .................................................................... 403
CPU Port ............................................................................................. 403
OS Kernel ........................................................................................... 404
Device Driver ...................................................................................... 412
NameGet() .......................................................................................... 414
Init() ..................................................................................................... 415
Open() ................................................................................................. 416
Close() ................................................................................................. 418
Rd() ..................................................................................................... 419
Wr() ...................................................................................................... 421
Query() ................................................................................................ 423
IO_Ctrl() ............................................................................................... 424
SD/MMC Cardmode BSP .................................................................. 425
FSDev_SD_Card_BSP_Open() ........................................................... 429
FSDev_SD_Card_BSP_Lock/Unlock() ............................................... 430
FSDev_SD_Card_BSP_CmdStart() .................................................... 431
FSDev_SD_Card_BSP_CmdWaitEnd() .............................................. 436
FSDev_SD_Card_BSP_CmdDataRd() ............................................... 440
FSDev_SD_Card_BSP_CmdDataWr() ................................................ 443
FSDev_SD_Card_BSP_GetBlkCntMax() ............................................ 446
FSDev_SD_Card_BSP_GetBusWidthMax() ....................................... 447
FSDev_SD_Card_BSP_SetBusWidth() .............................................. 448
FSDev_SD_Card_BSP_SetClkFreq() ................................................. 450
FSDev_SD_Card_BSP_SetTimeoutData() ......................................... 451
FSDev_SD_Card_BSP_SetTimeoutResp() ........................................ 452
11

600-uC-FS-001.book Page 12 Friday, August 17, 2012 4:51 PM

Table of Contents

C-6
C-7
C-7-1
C-7-2
C-7-3
C-7-4
C-7-5
C-7-6
C-7-7
C-8
C-9
C-9-1
C-9-2
C-9-3
C-9-4
C-9-5
C-9-6
C-10
C-10-1
C-10-2
C-10-3
C-10-4
C-10-5
C-10-6
C-11

SD/MMC SPI mode BSP .................................................................... 452
SPI BSP .............................................................................................. 453
Open() ................................................................................................. 457
Close() ................................................................................................. 459
Lock() / Unlock() ................................................................................. 460
Rd() ..................................................................................................... 461
Wr() ...................................................................................................... 462
ChipSelEn() /ChipSelDis() .................................................................. 463
SetClkFreq() ........................................................................................ 464
NAND Flash Physical-Layer Driver .................................................... 464
NOR Flash Physical-Layer Driver ...................................................... 464
Open() ................................................................................................. 467
Close() ................................................................................................. 468
Rd() ..................................................................................................... 469
Wr() ...................................................................................................... 470
EraseBlk() ........................................................................................... 471
IO_Ctrl() ............................................................................................... 472
NOR Flash BSP .................................................................................. 473
FSDev_NOR_BSP_Open() .................................................................. 474
FSDev_NOR_BSP_Close() ................................................................. 475
FSDev_NOR_BSP_Rd_XX() ................................................................ 476
FSDev_NOR_BSP_RdWord_XX() ....................................................... 477
FSDev_NOR_BSP_WrWord_XX() ....................................................... 478
FSDev_NOR_BSP_WaitWhileBusy() .................................................. 479
NOR Flash SPI BSP ........................................................................... 480

Appendix D
D-1
D-2
D-3
D-4
D-5
D-6
D-7
D-8
D-9

μC/FS Types and Structures ............................................................. 481
FS_CFG .............................................................................................. 482
FS_DEV_INFO ..................................................................................... 484
FS_DEV_NOR_CFG ............................................................................ 485
FS_DEV_RAM_CFG ............................................................................ 488
FS_DIR_ENTRY (struct fs_dirent) ...................................................... 489
FS_ENTRY_INFO ................................................................................ 490
FS_FAT_SYS_CFG ............................................................................. 492
FS_PARTITION_ENTRY ..................................................................... 494
FS_VOL_INFO ..................................................................................... 495

12

600-uC-FS-001.book Page 13 Friday, August 17, 2012 4:51 PM

Appendix E
E-1
E-2
E-3
E-4
E-5
E-6
E-7
E-8
E-9

μC/FS Configuration .......................................................................... 497
File System Configuration ................................................................. 498
Feature Inclusion Configuration ........................................................ 500
Name Restriction Configuration ........................................................ 503
Debug Configuration .......................................................................... 504
Argument Checking Configuration .................................................... 504
File System Counter Configuration ................................................... 505
FAT Configuration .............................................................................. 505
SD/MMC SPI Configuration ............................................................... 506
Trace Configuration ........................................................................... 507

Appendix F
F-1
F-2
F-3
F-3-1
F-3-2
F-3-3
F-3-4
F-3-5
F-3-6
F-3-7
F-3-8
F-3-9
F-3-10
F-3-11
F-3-12
F-3-13
F-3-14
F-3-15
F-3-16
F-3-17
F-4

Shell Commands ................................................................................ 509
Files and Directories .......................................................................... 510
Using the Shell Commands ............................................................... 511
Commands ......................................................................................... 514
fs_cat .................................................................................................. 515
fs_cd ................................................................................................... 516
fs_cp ................................................................................................... 518
fs_date ................................................................................................ 519
fs_df .................................................................................................... 520
fs_ls ..................................................................................................... 521
fs_mkdir .............................................................................................. 522
fs_mkfs ............................................................................................... 523
fs_mount ............................................................................................. 524
fs_mv .................................................................................................. 525
fs_od ................................................................................................... 526
fs_pwd ................................................................................................ 527
fs_rm ................................................................................................... 528
fs_rmdir ............................................................................................... 529
fs_touch .............................................................................................. 530
fs_umount ........................................................................................... 531
fs_wc ................................................................................................... 532
Configuration ...................................................................................... 533

13

600-uC-FS-001.book Page 14 Friday, August 17, 2012 4:51 PM

Table of Contents

Appendix G

Bibliography ....................................................................................... 535

Appendix H
H-1
H-1-1
H-1-2
H-1-3
H-1-4

μC/FS Licensing Policy ...................................................................... 537
μC/FS Licensing ................................................................................. 537
μC/FS Source Code ........................................................................... 537
μC/FS Maintenance Renewal ............................................................ 538
μC/FS Source Code Updates ............................................................ 538
μC/FS Support ................................................................................... 538

14

600-uC-FS-001.book Page 15 Friday, August 17, 2012 4:51 PM

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.

15

600-uC-FS-001.book Page 16 Friday, August 17, 2012 4:51 PM

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.

16

600-uC-FS-001.book Page 17 Friday, August 17, 2012 4:51 PM

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.

17

600-uC-FS-001.book Page 18 Friday, August 17, 2012 4:51 PM

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.
(A)

(1)

(B)

(2)

(C)

Introduction

µC/FS
Architecture
µC/FS Directories
and
Files

(3)

(4)

SD/MMC
Driver

Devices
and
Volumes

(5)

(6)
Files

(7)
Directories

(8)
POSIX
API

FAT
File System

Device
Drivers

µC/FS
Error
Codes
µC/FS
Porting
Manual

(11)

(D)

µC/FS
Types and
Structures

(12)

(E)

µC/FS
Configuration
Manual

(13)

(F)

µC/FS
Shell
Commands

RAM Disk
Driver

Useful Information

µC/FS API
Reference
Manual

(9)

(10)
NOR Flash
Driver
Mass Storage
Class (MSC)
Driver

(14)

(15)
IDE/CF
Driver

(G)
Bibliography

Figure 1-1 μC/FS book layout

18

600-uC-FS-001.book Page 19 Friday, August 17, 2012 4:51 PM

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.

19

600-uC-FS-001.book Page 20 Friday, August 17, 2012 4:51 PM

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 14, NAND Flash. 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.
20

600-uC-FS-001.book Page 21 Friday, August 17, 2012 4:51 PM

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”.

21

600-uC-FS-001.book Page 22 Friday, August 17, 2012 4:51 PM

Chapter 1

22

600-uC-FS-001.book Page 23 Friday, August 17, 2012 4:51 PM

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_’.

23

600-uC-FS-001.book Page 24 Friday, August 17, 2012 4:51 PM

Chapter 2

.c
where  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__bsp.c
For example, fs_dev_sd_spi_bsp.c contains the BSP functions for the driver SD/MMC
cards using SPI mode.

27

600-uC-FS-001.book Page 28 Friday, August 17, 2012 4:51 PM

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.

28

600-uC-FS-001.book Page 29 Friday, August 17, 2012 4:51 PM

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.

29

600-uC-FS-001.book Page 30 Friday, August 17, 2012 4:51 PM

Chapter 3

FS_CFG.H

APP.C/H
FS_APP.C/H

Platform Independent
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

Libraries

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

LIB_ASCII.C/H
LIB_DEF.H
LIB_MATH.C/H
LIB_MEM.C/H
LIB_STR.C/H

CLK.C/H
CLK_OS.C/H

Filesystem Driver
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

FS_FAT_FILE.C/H
FS_FAT_JOURNAL.C/H
FS_FAT_LFN.C/H
FS_FAT_SFN.C/H
FS_FAT_TYPE.H

ECC.H
EDC_CRC.C/H
ECC_HAMMING.C/H
CRC_UTIL.C/H

Device Drivers

OS Specific

FS_DEV_*.C/H

FS_OS.C/H

Platform Specific

CPU Specific

Board Support Package

FS_DEV_*_BSP.C

CPU.H
CPU_A.ASM
CPU_CORE.C/H

BSP.C/H

*.C
*.H

Figure 3-1 μC/FS Architecture

F3-1(1)

30

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().

600-uC-FS-001.book Page 31 Friday, August 17, 2012 4:51 PM

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.

31

600-uC-FS-001.book Page 32 Friday, August 17, 2012 4:51 PM

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
\
\
\
\
\*.*
\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.

32

600-uC-FS-001.book Page 33 Friday, August 17, 2012 4:51 PM

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.
\
Is the name of the manufacturer of the evaluation board. The ‘<’ and ‘>’ are not part of the
actual 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.
\
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.
\
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.

33

600-uC-FS-001.book Page 34 Friday, August 17, 2012 4:51 PM

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
\
\
\*.*
\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.
\
Is the name of the semiconductor manufacturer who provided the peripheral library. The ‘<’
and ‘>’ are not part of the actual name.
\
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.

34

600-uC-FS-001.book Page 35 Friday, August 17, 2012 4:51 PM

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
\
\
\
\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.
\
Is the name of the manufacturer of the evaluation board. The ‘<’ and ‘>’ are not part of the
actual 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.
\
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.
35

600-uC-FS-001.book Page 36 Friday, August 17, 2012 4:51 PM

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
\
\
\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.

36

600-uC-FS-001.book Page 37 Friday, August 17, 2012 4:51 PM

μ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.
\
This is the name of the CPU architecture for which μC/CPU was ported to. The ‘<’ and ‘>’
are not part of the actual name.
\
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.

37

600-uC-FS-001.book Page 38 Friday, August 17, 2012 4:51 PM

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
\
\
\lib_mem_a.asm
\Micrium
This directory contains all software components and projects provided by Micriμm.
38

600-uC-FS-001.book Page 39 Friday, August 17, 2012 4:51 PM

μ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
\
\clk_os.c
\Source
\clk.c
\clk.h
\Micrium
This directory contains all software components and projects provided by Micriμm.

39

600-uC-FS-001.book Page 40 Friday, August 17, 2012 4:51 PM

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.
\
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.

40

600-uC-FS-001.book Page 41 Friday, August 17, 2012 4:51 PM

μ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
\
\
\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.
41

600-uC-FS-001.book Page 42 Friday, August 17, 2012 4:51 PM

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.
\
The name of the CPU architecture that μC/CRC was ported to. The ‘<’ and ‘>’ are not part of
the actual name.
\
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
42

600-uC-FS-001.book Page 43 Friday, August 17, 2012 4:51 PM

μ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.

43

600-uC-FS-001.book Page 44 Friday, August 17, 2012 4:51 PM

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.

44

600-uC-FS-001.book Page 45 Friday, August 17, 2012 4:51 PM

μ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
45

600-uC-FS-001.book Page 46 Friday, August 17, 2012 4:51 PM

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
46

600-uC-FS-001.book Page 47 Friday, August 17, 2012 4:51 PM

μ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
47

600-uC-FS-001.book Page 48 Friday, August 17, 2012 4:51 PM

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.
48

600-uC-FS-001.book Page 49 Friday, August 17, 2012 4:51 PM

μ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_.*) 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__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_.*) 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_.*) 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.
49

600-uC-FS-001.book Page 50 Friday, August 17, 2012 4:51 PM

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



\fs_dev__bsp.c
\Micrium
This directory contains all software components and projects provided by Micriμm.

50

600-uC-FS-001.book Page 51 Friday, August 17, 2012 4:51 PM

μ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\
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.
\
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
\
\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.
51

600-uC-FS-001.book Page 52 Friday, August 17, 2012 4:51 PM

Chapter 3

\uC-FS
This is the main μC/FS directory.
\OS
This is the main OS directory.
\
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
\
\
\
\
\app.c
\app.h
\other
\BSP
\bsp.c
\bsp.h
52

600-uC-FS-001.book Page 53 Friday, August 17, 2012 4:51 PM

Summary

\other
\CPU
\
\
\*.*
\uC-FS
\APP\Template
\fs_app.c
\fs_app.h
\CFG\Template
\fs_cfg.h
\Dev

<-Cfg
<-Cfg
<-Cfg

\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
53

600-uC-FS-001.book Page 54 Friday, August 17, 2012 4:51 PM

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
\fs_dev_nor_template.h
\BSP\