Home

uC/GUI user manual

1. Figure 3 5 Adding template to your project In the configuration files are all runtime configuration functions of the file system located The configuration files include a start configuration which allows a quick and easy start with every driver The most important function for the beginning is FS_X_AddDevices It activates and configures if required the driver Driver which not not require hardware routines has to configured before they can be used User s A reference manual for uC FS 2004 2007 Micrium 30 CHAPTER 3 Running yC FS on target hardware 3 4 1 Modifying the runtime configuration The example on the next page adds a single CFI compliant NOR flash chip with a 16 bit interface and a size of 256 Mbytes to the file system The base address the start address and the size of the NOR flash are defined using the macros FLASHO BASE ADDR FLASHO START ADDR and FLASHO SIZE Normally only the Defines configurable section of the configuration files reguires changes for typi cal embedded systems The Public code section which includes the time and date functions and FS X AddDevices does not reguire modifications in most systems Example RRR RRR EERE RRR EERE ERE EKER REE EK RE KER EERE kkk kkk kk kk kkk kkk kk kkk kk kkk k kkk x Defines configurable This section is the only section which reguires changes for typical embedded systems using t
2. pDirEnt should point to a valid FS_DIRENT structure FS_DirEnt2Attr checks if the pointer is valid To get a valid pointer FS ReadDir should be called before using FS DirEnt2Attr Refer to FS_ReadDir on page 135 for more information Example void MainTask void FS_DIR pDir FS DIRENT pDirEnt char acBuffer 200 pDir FS_OpenDir Open root directory of default device if pDir do char acName 20 U8 Attr pDirEnt FS_ReadDir pDir FS_DirEnt2Name pDirEnt acName FS_DirEnt2Attr pDirEnt amp Attr if void pDirEnt NULL break No more files sprintf _acBuffer s s Attributes s s s s n acName Attr amp FS ATTR DIRECTORY Dir a Attr amp FS_ATTR_ARCHIVE 2 MAM z Ba Attr amp FS ATTR READ ONLY R a sees Attr amp FS_ATTR_HIDDEN zo ME p Ta Attr amp FS_ATTR_SYSTEM S 2 N FS_X_Log acBuffer while 1 FS CloseDir pDir else FS_X_ErrorOut Unable to open directory n User s amp reference manual for uC FS 2004 2007 Micrium 128 CHAPTER 4 API functions 4 14 3 FS DirEnt2Name Description Retrieves the name of the directory entry referred to by pDirEnt Prototype void FS DirEnt2Name FS DIRENT pDirEnt char pBuffer Parameter Description pDirEnt Pointer to a directory entry read by FS Read
3. Prototype int FS GetVolumeInfo const char sVolume FS DISK INFO plInfo Parameter Description sVolume Volume name as a string pinfo Pointer to a FS DISK INFO structure Table 4 56 FS GetVolumeInfo parameter list Return Value 0 If volume information could be retrieved successfully 1 In case of error for example if the volume could not be found Additional Information Valid values for sVolume have the following structure DevName UnitNum where e DevName is the name of a device If not specified the first device in the volume table will be used UnitNum is the number of the unit of the device If not specified unit O will be used Note that to specify UnitNum also DevName has to be specified Example include FS h include lt stdio h gt void MainTask void FS DISK INFO Info if FS GetVolumeInfo ram amp Info 1 printf Failed to get volume information n else printf Number of total clusters d n Number of free clusters d n Sectors per cluster d n Bytes per sector d n Info NumTotalClusters Info NumFreeClusters Info SectorsPerCluster Info BytesPerSector User s amp reference manual for uC FS 2004 2007 Micrium 93 4 9 7 FS GetVolumeLabel Description Returns a volume label name if one exists Prototype int FS GetVolumeLabel const char sVo
4. Prototype int pfWriteEx U8 Unit U32 PageIndex const void pData unsigned Off unsigned NumBytes const void pSpare unsigned OffSpare unsigned NumBytesSpare Parameter Meaning Unit Unit number 0 N PageIndex Number of page that should be written pData Pointer to a buffer of data which should be written oze Byte offset within the page which needs to be smaller than the page size NumBytes Number of bytes to write pSpare Pointer to a buffer data which should be written to the spare area Offset from the start of the spare area to the point where spare data should be written First byte of the spare area has the same offset as the page size Example Page size 512 PES OffSpare 512 gt First byte of spare area OffSpare 513 gt Second byte of spare area Page size 2048 OffSpare 2048 gt First byte of spare area OffSpare 2049 gt Second byte of spare area NumBytesSpare Number of spare bytes to write Table 5 17 pfWriteEx parameter list Return value 0 Data successfully transferred 0 An error has occurred User s amp reference manual for uC FS 2004 2007 Micrium 166 5 3 7 Hardware functions CHAPTER 5 Device drivers Routine Explanation FS NAND HW X SetAdd Mode nd and ALE high for the specified FS NAND HW X SetCmdM
5. Description Gets the amount of free space on a specific device Prototype U32 FS GetFreeSpace const char pDevice Parameter Description pDevice Name of a device Table 4 53 FS GetFreeSpace parameter list Return Value Amount of free space in bytes Free space larger than 4 Gbytes is truncated to OxFFFFFFFF the maximum value of a U32 User s amp reference manual for uC FS 2004 2007 Micrium 89 4 9 4 FS GetNumVolumes Description Retrieves the number of available volumes Prototype int FS GetNumVolumes void Return Value The number of available volumes Additional Information This function can be used to get the name of each available volume Refer to FS GetVolumeName on page 94 for getting more information User s amp reference manual for uC FS 2004 2007 Micrium 90 CHAPTER 4 API functions 4 9 4 1 FS GetTotalSpacef Description Gets the amount of total space on a specific device Prototype U32 FS GetTotalSpace const char pDevice Parameter Description pDevice Name of a device Table 4 54 FS GetTotalSpace parameter list Return Value Number of total space in bytes If the total space is larger than 4 Gbytes it is trun cated to OxFFFFFFFF the maximum value of an U32 User s amp reference manual for uC FS 2004 2007 Micrium 91 4 9 5 FS _GetVolumeFreeSpace Description Gets amount of free space
6. B FS FAT FWRITE UPDATE B FS FAT SUPPORT FAT32 B FS FAT OPTIMIZE SEO CLUSTERS Setting this macro to 1 writing to a file always updates the directory entry of the file always after writ ing to the file guarding the new data against unexpected RESET ON Directory entry is updated with every write operation This is slower but has the advantage that data written without close in case of unexpected RESET is not lost OFF Directory entry is updated when file is closed This is faster but has the disadvantage that any data written between open and unexpected RESET is lost To enable support for FAT32 media define this macro to 1 This macro enables a speed opti mization when reading large con tinuous files sequentially ON Higher speed Bigger code OFF Lower speed Smaller code Table 6 3 FAT configuration macros User s amp reference manual for uC FS 2004 2007 Micrium 273 Type Macro Default Description When retrieving the free disk amount on large FAT32 volumes this may take a long time since the FAT table can extend to many MBytes To improve this this macro should be set to 1 This will B FS FAT USE FSINFO SECTOR 1 enable the feature of using the FAT32 specific FSInfo sector This sector stores the information of the free clusters that are available and the last known free cluster ON Higher speed Bigger code OFF Low
7. Prototype void FS NAND SetPhyType U8 Unit const FS NAND PHY TYPE pPhyType Parameter Meaning Unit Unit number 0 N pPhyType Pointer to physical type Table 5 8 FS NAND SetPhyType parameter list Permitted values for parameter pPhyType Supports the following NAND devices 512 bytes per page and 8 bit width Supports the following NAND devices 2048 bytes per page and 8 bit width Supports the following NAND devices 2048 bytes per page and 16 bit width FS NAND PHY 512x8 FS NAND PHY 2048x8 FS NAND PHY 2048x16 User s amp reference manual for uC FS 2004 2007 Micrium 156 CHAPTER 5 Device drivers Permitted values for parameter pPhyType Supports the following NAND devices 512 bytes per page and 8 bit width 2048 bytes per page and 8 bit width 2048 bytes per page and 16 bit width Supports the following NAND devices FS_NAND_PHY_x8 512 bytes per page and 8 bit width 2048 bytes per page and 8 bit width Supports ATMEL DataFlashes The physi cal layer driver accesses these chips using the SPI mode To use the driver with ATMEL DataFlash chips in your sys tem you will have to provide basic I O functions which are divergend to the hardware functions of the other physical layers Refer to FS_NAND_PHY_x FS NAND PHY DataFlash Additional information This function needs to be called for every NAN
8. _GetDriverName _AddDevice _Read _Write _Toctl NULL _GetStatus _GetNumUnits Yi User s amp reference manual for yC FS E FS_RAMDISK_Driver 2004 2007 Micrium 265 5 8 3 Integrating a new driver There is an empty skeleton driver called generic in the Sample Driver DriverTem plate folder This driver can be easily modified to get any block oriented storage device working with the file system To add the driver to UC FS FS AddDevice should be called from within FS X AddDevices to mount the device driver to uC FS before accessing the device or its units Refer to FS X AddDevices on page 262 for more information User s amp reference manual for uC FS 2004 2007 Micrium 266 CHAPTER 5 Device drivers User s amp reference manual for uC FS 2004 2007 Micrium 267 Chapter 6 uC FS Configuration uC FS can be used without the need for changing any of the compile time flags All compile time configuration flags are preconfigured with valid values which matchs the reguirements of the most applications Device drivers can be added to runtime The default configuration of uC FS can be changed via compile time flags which can be added to FS Conf h FS Conf h is the main configuration file for the file system Every driver folder includes a configuration file e g ConfigRamDisk c with imple mentations of runtime configuration functions explained in this chapter The co
9. ROM Module Kbytes ucC FS NAND driver 4 5 In addition one of the following physical layers is reguired Baers ROM Physical layer Description Kbytes Physical layer for small NAND devices with an FS_NAND_PHY_512x8 8 bit interface 1 1 f Physical layer for large NAND devices with an FS_NAND_PHY_2048x8 8 bit interface 1 0 l Physical layer for large NAND devices with an FS_NAND_PHY_2048x16 16 bit interface 1 0 Physical layer for large and small NAND FS_NAND_PHY_x8 devices with an 8 bit interface 28 RE NAND a Physical layer for large and small NAND 3 3 U m devices with an 8 bit or 16 bit interface 5 3 10 2 Static RAM usage Static RAM usage is the amount of RAM reguired by the driver for variables inside of the driver The number of bytes can be seen in a list file Static RAM usage of the NAND driver 32 bytes 5 3 10 3 Run time RAM usage Run time RAM usage is the amount of RAM allocated by the driver at runtime The amount reguired depends on the runtime configuration and the connected device The approximately RAM usage for the NAND driver can be calculated as follows Every NAND device reguires 160 2 NumberOfUsedBlocks 4 SectorsPerBlock 1 04 MaxSectorSize Example 2 GBit NAND flash with 2K pages 2048 blocks used 512 byte sectors One block consists of 64 pages each page holds 4 sectors of 512 bytes User s amp reference manual for uC FS 2004 2007 Micrium 187 Sector
10. Table 5 1 List of default device driver labels To add a driver to uC FS FS Addi 5 1 2 Unit number Device should be called with the proper identifier to mount the device driver to uC FS before accessing the device or its units Refer to FS_AddDevice on page 44 for detailed information Most driver functions as well as most of the underlying hardware functions receive the unit number as the first parameter The unit number allows differentiation between the different instances of the same device types If there are for example 2 NAND flashes which operate as 2 different devices the first one is identified as Unit 0 the second one as Unit 1 If there is just a single instance as in most sys tems the unit parameter can be ignored by the underlying hardware functions User s amp reference manual for uC FS 2004 2007 Micrium 143 RAM disk driver uC FS comes with a simple RAM disk driver that makes it possible to use a portion of your system RAM as drive for data storage This can be very helpful to examine your system performance and may also be used as a in system test procedure 5 2 1 Supported hardware The RAM driver can be used with every target with enough RAM The size of the disk is defined as the number of sectors reserved for the drive 5 2 2 Theory of operation A RAM disk is a portion of memory that you allocate to use as a partition The RAM disk driver takes some of your memory an
11. 256 FS NOR GetSectorInfo parameter list 257 FS NOR DISK INFO list of structure elements 259 FS NOR SECTOR INFO list of structure elements 260 FS Windrive Configure parameter list 262 Device driver functions cece cece cece eeeee eee eeeeaeeeees 263 FS DEVICE TYPE List of structure member variables 264 FS X Alloc parameter list 2 269 General file system configuration macros 271 FAT configuration macros r 272 EFS configuration macros 0 274 Operating system support macros 274 Debug level macros ccccccececceeeseeeenseeeeeeeeesaenes 275 Miscellaneous configuration macros 275 FS X OS Init parameter list o 279 FS X OS Lock parameter list cccceeeeeeee eee 280 FS X OS Unlock parameter list 281 FS X Log parameter list n 284 FS X Warn parameter list cccccccceeeeeeeeeeeeees 285 FS X ErrorOut parameter list 0 ees 286 Arm7 sample configuration 290 Performance valus for sample configurations 293 Differences between uC FS v 2 x v 3 x API differences Differences between uC FS v 2 x v 3 x removed replaced configuration macros 298 Table 10 3 values Table 10 4 vice drivers Table 10 5 299 User s amp reference manual for uC FS Differences between uC FS v 2 x v 3 x changed default 298 Differences between uC FS
12. 1 Setting the mode of the cache module was not successful Additional Information This function is only usable with the FS CACHE RW and FS CACHE RW OUOTA module after the FS CACHE RW cache has been assigned to a volume The cache module needs to be configured with this function Otherwise neither read nor write opera tions are cached User s amp reference manual for uC FS 2004 2007 Micrium 119 Example include FS h static char _acCache 100 1024 Use a 100 Kbyte cache void Function void Assign a cache to the first available device FS AssignCache _acCache sizeof acCache FS CACH Set the FS CACHE RW module to cache all sectors Sectors are cached for read and write Write back operation to volume are delayed 7 FS CACHE SetMode FS SECTOR TYPE MASK ALL FS CACHE MODE WB Do some work DoWork FS CACHE Clean DoOtherWork Disable cache FS AssignCache NULL 0 Lu _RW User s amp reference manual for uC FS 2004 2007 Micrium 120 CHAPTER 4 API functions 4 12 4 FS CACHE _ SetQuota Description Sets the quotas for the different sector types in the CacheRW Ouota cache module Prototype int FS CACHE SetMode const char pDevName int TypeMask U32 NumSectors Parameter Description pDevName is the name of a device If not specified the first device in the volume table will be used Speci
13. ATMEL AT45DB011B AT45DB021B AT45DB041B AT45DB081B AT45DB161B AT45DB321C AT45BR3214B AT45DCB002 AT45DCB004 Table 5 4 List of supported serial flash devices User s amp reference manual for uC FS 2004 2007 Micrium 150 CHAPTER 5 Device drivers 5 3 1 3 Pin description NAND flashes Pin Driver Device m CHIP ENABLE CE The CE input enables the device Signal is active low If the signal is inactive device is in standby mode Ex WRITE ENABLE WE The WE input controls writes to the I O port Commands address and data are latched on the rising edge of the WE pulse READ ENABLE RE The RE input is the serial data out control When active low the device outputs data COMMAND LATCH ENABLE CLE This pin should be low when writing commands to the command regis ter ALE ADDRESS LATCH ENABLE When active an address can be written te WRITE PROTECT WP Typically connected to VCC recommended but may also be connected to port pin READY BUSY OUTPUT The R B output indicates the status of the device operation When low R B it indicates that a program erase or read operation is in process It returns to high state when the operation is completed It is an open drain output Should be connected to a port pin with pull up If avail able a port pin which can trigger an interrupt should be used DATA INPUTS OUTPUTS I O 1 07 The I O pins are used to input command address and data and t
14. st ER UNUSED ir this y n a ter chain into file y n ain da n n n a KKAXAZAZAZXAZAZ KA A AA Z AH A AZ AZ A Z AZ AZ A ZK A KA K EX K sizeof aBuffer 5 _OnError 1 2004 2007 Micrium 112 CHAPTER 4 API functions 4 11 2 FS_FAT_CheckDisk_ErrCode2Text Description Returns an error string to a specific check disk error code Prototype const char FS FAT CheckDisk ErrCode2Text int ErrCode Parameter Description ErrCode Check disk error code Table 4 76 FS FAT CheckDisk ErrCode2Text parameter list Return value The following error codes are defined as Code Description FS ERRCODE OFILE A file of size zero has allocated cluster s A cluster chain for a specific file is longer than FS ERRCODE SHORTEN CLUSTER its file size A cluster is cross linked used for multiple files directories FS ERRCODE FEW CLUSTER Too few clusters allocated to file A cluster is marked as used but not assigned to a file or directory FS ERRCODE CLUSTER NOT EOC A cluster is not marked as end of chain FS ERRCODE INVALID CLUSTER A cluster is not a valid cluster Table 4 77 FS FAT CheckDisk ErrCode2Text list of error code values FS ERRCODE CROSSLINK I D_CLUSTI i pe FS ERRCODE CLUSTER UNUSED Typically this function is used in the callba
15. 13 38 5V 3 3V power Voltage Sense Signals VS1 is grounded so that the VSI VSZ o A CompactFlash Storage Card or CF Card CIS can be read at 3 3 volts and VS2 is reserved by PCMCIA for a secondary voltage Table 5 71 True IDE pin functions User s amp reference manual for uC FS 2004 2007 Micrium 226 CHAPTER 5 Device drivers sa Dir Pin Description name IORDY O 42 This output signal may be used as IORDY WE I 36 This input signal is not used and should be connected to VCC by the host This output signal is asserted low when the device is TOSES 9 a expecting a word data transfer cycle Table 5 71 True IDE pin functions Continued User s amp reference manual for uC FS 2004 2007 Micrium Sample block schematic IDE interface IDE Controller Compact Flash Card A0 2 gt A0 2 D0 15 gt D0 15 cso gt CEO CS1 gt CE1 IORD gt IORD IOWR gt IOWR RESET yp RESET IORDY lt IORDY INTRO lt lt INTRO 101S16 101S16 Open DASP Open PDIAG Open INPACK CSEL 1 Master Mode A3 10 CSEL OE ATASEL GND e GND WE REG VCC ee VCC MPU For card detection cot CD2 VS1 lt VS2 User s amp reference manual for uC FS 227 2004 2007 Micrium CHAPTER 5 Device drivers Memory card mode pin functions Slama Dir Pin Description name These address lines along with the REG sig
16. FS MMC CMD FLAG DATATRANSFER the card The card may be in busy state after sending this FS MMC CMD FLAG SETBUSY command The card host controller may wait after the card ready for next command The card host controller should send the initial ization seguence to the card This tells the card host controller to use all 4 DAT line rather than DAT line Note that this com mand flag is only set when FS MMC SUPPORT 4BIT MODE is set The card host controller shall stop transferring data to the card This flags tells the card controller that the sent command initiate a data transfer This flags tells the card controller that the sent FS MMC CMD FLAG INITIALIZE FS MMC CMD FLAG USE SD4MODE FS MMC CMD FLAG STOP TRANS FS MMC CMD FLAG DATATRANSFER FS MMC CMD FLAG WRITETRANSFER command initiate a data transfer and will write to the card The card may be in busy state after sending this FS MMC CMD FLAG SETBUSY command The card host controller may wait after the card ready for next command Table 5 65 FS MMC HW X SendCmdf list of possible commands User s amp reference manual for uC FS 2004 2007 Micrium 216 CHAPTER 5 Device drivers After sending a command to the MMC SD card the card may respond to the com mand The type format of the expected respon
17. PS PS ES FS_MULTI_HANDLE_SAFE VERIFY WRITE i MAX SECTOR SIZI SUPPORT FAT SUPPORT EFS SUPPORT CACH Uzi DIRECTORY DELIMITER 512 AN Defines the maximum sector size uC FS should handle This is required if you intend to use sector sizes greater than 512 bytes Defines if uC FS should use the FAT file system layer Note FAT amp EFS cannot be used simultaneously Defines if uC FS should use the optional EFS file system layer Determines whether FS_AssignChache can be used FS_AssignChache allows run time assigment of a cache Refer to FS_AssignCache on page 115 for further information Note FS AssignCache needs to be called to activate the cache functionality for a specific device If you intend to open a file simul taneously for read write set this macro to 1 Defines the character that should be used to delimit directories Verify every write sector opera tion tests the driver and hard ware This switch should always off for production code It is nor mally switched on only when investigating driver problems Table 6 2 General file system configuration macros User s amp reference manual for uC FS 2004 2007 Micrium 272 6 2 2 FAT configuration CHAPTER 6 HCIFS Configuration The current version of uC FS supports FAT12 FAT16 FAT32 Type Macro Default Description
18. Hi Init if CmdFlags amp FS MMC CMD FLAG USE_SD4MODE 4 bit mode CmdCon 1 lt lt 7 Set WIDE bit if CmdFlags amp FS MMC CMD FLAG STOP TRANS Abort transfer CmdCon 1 lt lt 13 Set ABORT bit ___SDMMC_CMD Cmd ___SDMMC__CMDCON CmdCon ___SDMMC_ARGUMENT Arg _StartMMCClock Unit User s amp reference manual for uC FS 2004 2007 Micrium 5 4 7 11 FS_MMC_HW_X_WriteData Description Writes a number of block to the card Prototype int FS MMC HW X WriteData U8 Unit const void pBuffer 217 unsigned NumBytes unsigned NumBlocks Parameter Meaning Unit Unit number 0 N pBuffer Pointer to a buffer for data to send NumBytes Number of bytes for each block to send NumBlocks Number of blocks to send Table 5 67 FS MMC HW X WriteData parameter list Return value Return Flag Meaning FS MMC CARD NO ERROR FS MMC CARD WRITE CRC ERROR occurred All data have been sent successfully and card has programmed the data During the data transfer to the card a CRC error Table 5 68 FS MMC HW X WriteData list of return values Additional Information This function is used to write a specified number of blocks to the card Each block is NumBytes long Example int FS MMC HW X WriteData U8 Unit
19. If you do have to control the WE line make sure that timing is according to your NAND flash device specifications Example void FS NAND HW X Write x8 U8 Unit U8 pBuffer unsigned NumBytes SET_DATA20UTPUT do NANI NANI O NONA R WE WE is active low ET DATA pBuffer pBu r NAND SET WE disable WE while NumBytes U E Fh U User s amp reference manual for uC FS 2004 2007 Micrium 176 CHAPTER 5 Device drivers 5 3 7 10 FS NAND HW X Write x16 Description Writing data to a 16 bit NAND flash using the I O 0 15 lines of the NAND flash device Prototype void FS NAND HW X Write x16 U8 Unit const U8 pBuffer unsigned NumBytes Parameter Meaning Unit Unit number 0 N pBuffer Pointer to a buffer of data which should be written NumBytes Number of bytes that should be transferred to the NAND flash Table 5 28 FS NAND HW X Write x16 parameter list Additional Information When writing data to the device usually you will not have to take care of handling the WE line because that is done automatically by the hardware If you do have to control the WE line make sure that timing is according to your NAND flash device specifications User s amp reference manual for uC FS 2004 2007 Micrium 177 5 3 7 11 FS NAND HW X Delayus Description Delays for a specified period of time Prot
20. Parameter Description sVolume Volume name pData Pointer to the data which should be written to the device SectorIndex Index of the sector to which data should be written Table 4 102 FS_WriteSector parameter list Return value 0 On success l 0 On error Additional information This function is obsolete Use instead FS STORAGE Init on page 104 User s amp reference manual for uC FS 2004 2007 Micrium 140 CHAPTER 4 API functions User s amp reference manual for uC FS 2004 2007 Micrium 141 Chapter 5 Device drivers uC FS has been designed to cooperate with any kind of hardware To use specific hardware with UC FS a so called device driver for that hardware is required The device driver consists of basic I O functions for accessing the hardware and a global table that holds pointers to these functions User s amp reference manual for uC FS 2004 2007 Micrium 142 CHAPTER 5 5 1 General information 5 1 1 Default device driver names By default the following identifiers are used for each driver Device drivers Driver Device Identifier Name Harddisk CompactFlash FS IDE Driver ide MMC SD SPI mode FS_MMC_SPI Driver mmc MMC SD Card mode FS MMC CardMode Driver mmc NAND flash FS NAND Driver nand NOR flash FS_NOR_Driver nor RAM disk FS_RAMDISK Driver Mess WINDrive FS_WINDRIVE_ Driver win
21. This function can be used to add an additional device driver You may also increase FS_NUM_VOLUMES to add additional space for more drives Example include FS h static int _DevGetName U8 Unit return static int _DevAddDevice void if _NumUnits gt NUM_UNITS return 1 return _NumUnits static int _DevRead U8 Unit U32 Sector void pBuffer return 0 static int _DevWrite U8 Unit U32 Sector void pBuffer return 0 static int _DevIloCtl U8 Unit I32 Cmd 132 Aux void pBuffer return 0 User s amp reference manual for UC FS 2004 2007 Micrium 43 static int _DevIloCtl U8 Unit I32 Cmd 132 Aux void pBuffer return 0 static int DevInitMedium U8 Unit return 0 static int _DevGetStatus U8 Unit return 0 static int _DevGetStatus U8 Unit return 0 struct FS DEVICE TYPE FS_xxx_Driver const char pfGetName U8 Unit int pfAddDevice void int pfRead U8 Unit U32 SectorNo void pBuffer U32 NumSectors int pfWrite U8 Unit U32 SectorNo const void pBuffer U32 NumSectors U8 RepeatSame int pfloCtl U8 Unit 132 Cmd I32 Aux void pBuffer int pfInitMedium U8 Unit int pfGetStatus U8 Unit int pfGetNumUnits void void AddDevices void FS_AddDevice amp FS xxx Driver User s amp reference manual for uC FS 2004 2007 Micrium 44 CHAP
22. 5 3 7 8 FS NAND HW X Read x16 Description Reads data from a 16 bit NAND flash device using the I O 0 15 lines Prototype void FS NAND HW X Read x16 U8 Unit U8 pBuffer unsigned NumBytes Parameter Meaning Unit Unit number 0 N pBuffer Pointer to a buffer to store the read data NumBytes Number of bytes that should be stored into the buffer Table 5 26 FS NAND HW X Read x16 parameter list Additional Information When reading from the device usually you will not have to take care of handling the RE line because that is done automatically by the hardware If you do have to control the RE line make sure that timing is according to your NAND flash device specification User s amp reference manual for uC FS 2004 2007 Micrium 175 5 3 7 9 FS NAND HW X Write x8 Description Writes data to an 8 bit NAND flash using the 1 0 0 7 lines of the NAND flash device Prototype void FS NAND HW X Write x8 U8 Unit const U8 pBuffer unsigned NumBytes Parameter Meaning Unit Unit number 0 N pBuffer Pointer to a buffer of data which should be written NumBytes Number of bytes that should be transferred to the NAND flash Table 5 27 FS NAND HW X Write x8 parameter list Additional Information When writing data to the device usually you will not have to take care of handling the WE line because that is done automatically by the hardware
23. Caching is enabled right after calling FS AssignCache FS CACHI 5 This module is also a pure read cache In con trast to the FS CACHE ALL this module does only cache the management sector of a file system for example FAT sectors Caching is enabled right after calling FS AssignCache FS CACHE RW FS CACHE Rw is a configurable cache module This module can be either used as read write or as read write cache Additionally the sec tors that should be cached are also config urable Refer to FS CACHE SetMode to configure the FS CACHE RW module z FS CACHE RW OUOTA FS CACHE RW OUOTA is a configurable cache module This module can be either used as read write or as read write cache To config ure the cache module properly FS CACHE SetMode and FS CACHE SetOuota need to be called Otherwise the functionality inside the cache is disabled Example include FS h static char _acCache 100 1024 Use a 100 Kbyte cache void Function void Assign a cache to the first available device FS_AssignCache _acCache sizeof _acCache FS_CACHE_ALL Do some work DoWork Disable the read cache FS_AssignCache NULL 0 User s amp reference manual for uC FS 2004 2007 Micrium 117 4 12 2 FS CACHE Clean Description Cleans a cache if sectors that are marked as dirty need to be written to the device Prototype
24. Description Locks a specific file system operation Prototype void FS X OS LockFileHandle unsigned LockIndex Parameter Meaning Index number of the binary semaphore mutex created before in FS X OS Init LockIndex Table 7 2 FS X OS Lock parameter list Additional Information This routine is called by the file system before it accesses the device or before using a critical internal data structure It blocks other threads from entering the same crit ical section using a resource semaphore mutex until FS X Unlock has been called with the same LockIndex When using a real time operating system you normally have to increment a counting resource semaphore User s amp reference manual for uC FS 2004 2007 Micrium 281 7 2 3 FS X OS Unlock Description Unlock FAT memory block table Prototype void FS X OS Unlock unsigned LockIndex Parameter Meaning Index number of the binary semaphore mutex created before in FS X OS Init Table 7 3 FS X OS Unlock parameter list LockIndex Additional Information This routine is called by the file system after accessing the device or after using a critical internal data structure When using a real time operating system you nor mally have to decrement a counting resource semaphore User s amp reference manual for uC FS 2004 2007 Micrium 282 CHAPTER 7 OS Integration 7 2 4 Examples OS inter
25. Description Renames an existing file or a directory Prototype int FS Rename const char sExistingName const char sNewName API functions Parameter Description sNewName directory sExistingName Pointer to a string that names an existing file or directory Pointer to a string that specifies the new name of the file or Table 4 29 FS Rename parameter list Return value 0 If the file was successfully renamed 1 In case of any error Additional Information Valid values for sExistingName and sNewName are the same as for FS FOpen Refer to FS_FOpen on page 48 for examples of valid names sNewName should only specify a valid file or directory name Example void MainTask void FS Rename ram subdirl subdir2 User s amp reference manual for uC FS 2004 2007 Micrium 65 4 6 8 FS_SetFileAttributes Description Sets attributes for a specified file or directory Prototype int FS SetFileAttributes const char pName U8 Attributes Parameter Description pName Pointer to a string that specifies the name of a file or directory Attributes Attributes to be set to the file or directory Table 4 30 FS SetFileAttributes parameter list Permitted values for parameter Attributes The file or directory is an archive file or direc FS ATTR ARCHIVE tory Applications can use this attribute to mark files for backup or re
26. NumSectors Number of sectors that should be written Table 4 74 FS STORAGE WriteSectors parameter list Return value 0 On success I 0 On error User s amp reference manual for uC FS 2004 2007 Micrium 110 CHAPTER 4 API functions 4 11 FAT related functions 4 11 1 FS FAT CheckDisk Description Checks and repairs a FAT volume Prototype int FS FAT CheckDisk const char sVolumeName void pBuffer U32 BufferSize int MaxRecursionLevel FS OUERY F TYPE pfOnError Parameter Description sVolumeName Volume name as a string pBuffer Pointer to a buffer that will be used by FS FAT CheckDisk BufferSize Size of the specified buffer The maximum directory recursion depth FS FAT CheckDisk should check pfOnError Pointer to a callback function for the error handling Table 4 75 FS_FAT_CheckDisk parameter list MaxRecursionLevel Return value 0 Ok 1 An error has be found and repaired retry is required 2 User specified an abort of checkdisk operation thru callback Additional Information This function can be used to check if there are any errors on a specific volume and if necessary repair the found error The buffer that pBuffer points to should be at least 4 Kbyte The minimum size of the buffer can be calculated as follows 12 Bytes x Bytes per sector x 8 Fat type where FAT type is either 12 16 or 32 The type FS_QUERY_F_T
27. Parameter Description Unit Unit number 0 N PhysSectorIndex Index of physical sector pDiskInfo Pointer to a structure of type FS NOR DISK INFO Table 5 88 FS NOR GetSectorInfo parameter list Additional information Refer to Structure FS NOR SECTOR INFO on page 260 for more information about the structure elements Example EF kkkkkkkkkkkk kkk kkk kkk kkk kk kk kkhk k kkk kk kk k kk k k kk k k k k k k k k kk k k k k k k k k ShowDiskInfo k void ShowDiskInfo FS NOR DISK INFO pDiskInfo char acBuffer 80 FS X Log Disk Info n FS NOR GetDiskInfo 0 pDiskInfo sprintf acBuffer Physical sectors d n Logical sectors d n Used sectors d n pDiskInfo gt NumPhysSectors pDiskInfo gt NumLogSectors pDiskInfo gt NumUsedSectors FS X Log acBuffer RRR RRERERER EKER EKER kkk kkk kkk kkk RE KER kk kk kk kk k kk k EKER EKER k kk k k k k k k k kk ShowSectorInfo A void ShowSectorInfo FS_NOR_SECTOR_INFO pSecInfo U32 PhysSectorIndex char acBuffer 400 FS X Log Sector Info n FS NOR GetSectorInfo 0 PhysSectorIndex pSecInfo sprintf acBuffer Physical sector No Sdin Offset d n Size d n Erase Count d n Used logical sectors d n Free logical sectors d n Erasable logical sectors d n PhysSectorIndex pSecInfo gt Off pSecInfo gt Size pSecInfo gt EraseCnt pSecInfo gt NumUsedSectors pS
28. Read Reads data from a device Write Writes data to a device Table 5 92 Device driver functions User s amp reference manual for uC FS 2004 2007 Micrium 264 CHAPTER 5 5 8 2 Device driver function table uC FS uses function tables to call the appropiate driver function for a device Data structure typedef struct Device drivers const char pfGetName U8 Unit int pfAddDevice void int pfRead U8 Unit U32 SectorNo void pBuffer U32 NumSectors int pfwrite U8 Unit U32 SectorNo const void pBuffer U32 NumSectors U8 RepeatSame int pfIoctl U8 Unit 132 Cmd 132 AUX void pBuffer int pfInitMedium U8 Unit int pfGetStatus U8 Unit int pfGetNumUnits void FS DEVICE TYPE Elements of FS DEVICE TYPE Element Meaning pfGetName Pointer to a function that returns the name of the driver pfRead Pointer to the device read sector function pfWrite Pointer to the device write sector function pfToCt1l Pointer to the device IoCtl function pfInitMedium Pointer to the medium initialization function optional pfGetStatus Pointer to the device status function pfGetNumUnits Pointer to a function that returns the number of available devices Table 5 93 FS_DEVICE_TYPE List of structure member variables Example sample implementation taken from the RAM device driver const FS_DEVICE_TYP
29. void FS CACHE Clean const char pDevName T Parameter Description pDevName is the name of a device If not specified the first device in the volume table will be used Table 4 80 FS_CACHE_Clean parameter list pDevName Additional Information Because only write or read write caches need to be cleaned this function should be called for volumes where the FS CACHE Rw module is assigned The other cache mod ules ignore the cache clean operation Cleaning of the cache is also performed when the volume is unmounted through FS Unmount or disabling or reassigning the cache through FS AssignCache Example include FS h static char _acCache 100 1024 Use a 100 Kbyte Cache void Function void Assign a cache to the first available device FS AssignCache _acCache sizeof acCache FS CACH Set the FS CACHE RW module to cache all sectors Sectors are cached for read and write Write back operation to volume are delayed se FS CACHE SetMode FS SECTOR TYPE MASK ALL FS CACHE MODE FULL Do some work DoWork FS CACHE Clean DoOtherWork Disable cache FS AssignCache NULL 0 E ALL User s amp reference manual for uC FS 2004 2007 Micrium 118 CHAPTER 4 4 12 3 FS CACHE SetMode API functions Description Sets the mode for the cache Prototype int FS CACHE SetMode const char pDevN
30. 0 FS_Format ramc NULL User s amp reference manual for uC FS 1 1 as the first physical DISK_NUM_SECTORS DISK NUM SECTORS 2004 2007 Micrium 4 4 File access functions 4 4 1 FS FClosef Description Closes an open file Prototype int FS FClose FS FILE pFile 47 Parameter Description pFile Pointer to a data structure of type FS FILE Table 4 10 FS FClose parameter list Return value 0 File pointer has successfully been closed 1 Failed to close the file pointer Example void MainTask void FS FILE pFile pFile FS FOpen test txt r if pFile 0 access file as FS_FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 48 CHAPTER 4 API functions 4 4 2 FS FOpen Description Opens an existing file or creates a new file depending on the parameters Prototype FS FILE FS FOpen const char pName const char pMode Parameter Description TE Pointer to a string that specifies the name of the file to create or 2 open pMode Mode for opening the file Table 4 11 FS FOpen parameter list Return value Returns the address of an FS FILE data structure if the file could be opened in the reguested mode 0 in case of any error Additional Information A fully gualified file name looks like DevName UnitNum
31. Copy the compatible hardware function sample or the template into a subdirectory of your work directory and add it to your project The template file is located in the Sample Driver lt DRIVER_DIR gt directory the example implementations are located in the respective directories If you start the implementation of hardware routines with the hardware routine template refer to Device drivers on page 141 for detailed information about the implementation of the driver specific hardware func tions else refer to section Step 4 Activating the driver on page 29 Note You cannot run and test the project with the new driver on your hardware as long as you have not added the proper configuration file for the driver to your project Refer to section Step 4 Activating the driver on page 29 for more informa tion about the activation of the driver with the configuration file User s amp reference manual for uC FS 2004 2007 Micrium 29 3 4 Step 4 Activating the driver After adding the driver source and if required the hardware function implementation to the project copy also the Config lt DRIVERNAME gt c file for example ConfigMMC SPI c for the MMC SD card driver using the SPI mode into the config directory of your uC FS work directory Add it afterwards to your project as show below Example IAR Embedded Workbench IDE ti MC SD
32. Current time and date as U32 in a format suitable for the file system Additional Information The format of the time is arranged as follows Bit 0 4 2 second count 0 29 Bit 5 10 Minutes 0 59 Bit 11 15 Hours 0 23 Bit 16 20 Bit 21 24 Bit 25 31 Day of month 1 31 Month of year 1 12 Number of years since1980 0 127 Example U32 FS X GetTime U32 r U16 Sec Date void Min Hour Day Month Year Sec Min Hour Day Month Year FS X GET SECOND FS ET MINUTE FS X GET HOUR FS X GET DAY FS X GET MONTH FS X GET YEAR Mi D MM x oeeeca MD Sec 2 Min lt lt 5 Hour r Day Month lt lt 5 Year return r lt lt 11 lt lt 9 lt lt 16 6 1 3 2 Logging functions User s amp reference manual for uC FS Logging is used in higher debug levels only The typical target build does not use log ging and does therefore not require any of the logging functions For a release build without logging the functions may be eliminated from configuration file to save some space If the linker is not function aware and eliminates unreferenced functions automatically Refer to Debugging on page 283 for further information about the different logging functions 2004 2007 Micrium 6 2 Compile time configuration 6 2 1 271 General file system configuration Type Macro Default Description ES FS FS
33. FLASHO START ADDR FLASHO SIZE User s amp reference manual for uC FS 2004 2007 Micrium 31 After the driver has been added the configuration functions in this example FS NOR SetPhyType and FS NOR Configure should be called Detailed informa tion about the driver configuration can be found in the configuration section of the respective driver Refer to section Runtime configuration on page 262 for detailed information about the other runtime configuration of the file system Before compiling and running the sample application with the added driver you have to exclude ConfigRAMDisk c from project Note for drivers which reguire hardware routines If you have only added the template with empty function bodies until now the project should compile without errors or warning messages But you can only run the project on your hardware if you have finished the implementation of the hardware functions User s amp reference manual for uC FS 2004 2007 Micrium 32 CHAPTER 3 Running yC FS on target hardware 3 5 Step 5 Adjusting the RAM usage The file system needs RAM for management purposes in various places The amount of RAM required depends primarily on the configuration especially the drivers used The drivers which have their own level of management such as NOR NAND drivers in general need more RAM than the simple drivers for hard drives compact flash or SD cards Every driver needs to allocate RAM The file s
34. FS_FWrite acText 1 FS FClose pFile User s amp reference manual for uC FS strlen acText w pFile 2004 2007 Micrium 53 4 4 6 FS_Write Description Writes data to an open file Prototype U32 FS Write FS FILE pFile const void pData U32 NumBytes Parameter Description pFile Pointer to a data structure of type FS FILE pData Pointer to data to be written to the file NumBytes Pointer to a data structure of type FS FILE Table 4 15 FS Write parameter list Return value Number of bytes written Additional Information If there is less data transferred than specified you should check for possible errors by calling the FS FError function Example const char acText hello world n void MainTask void FS FILE pFile pFile FS FOpen test txt w if pFile 0 FS Write pFile acText strlen acText FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 54 CHAPTER 4 API functions 4 5 File positioning functions 4 5 1 FS FSeek Description Sets the current position of a file pointer Prototype int FS FSeek FS FILE pFile 132 Offset int Origin Parameter Description pFile Pointer to a data structure of type FS FILE Offset Offset for setting the file pointer position Origin Mode for positioning the file pointer Table 4 16 FS FSeek parame
35. MMC SD card pin description User s amp reference manual for uC FS 2004 2007 Micrium 190 CHAPTER 5 Device drivers 5 4 1 2 Pin description for MMC SD card in SPI mode eu Name Type Description Chip Select CS Input It sets the card active at low level and inactive at high level Master Out Slave In 2 MOSI Input Transmits data to the card V Supply Power supply ground SS ground Supply voltage ground Supply volt 4 VDD E Supply voltage Clock signal 5 SCLK Input It must be generated by the target system The card is always in slave mode Supply V 6 S52 ground Supply voltage ground Master In Slave Out Line to transfer data to the host The reserved pin is a floating input Therefore connect an external pull up resistor to it Otherwise non 7 MISO Output ped Mot veci expected high current consumption may occur due to the floating input The reserved pin is a floating input Therefore connect 9 Reserved Not used an external pull up resistor to it Otherwise non expected high current consumption may occur due to the floating input Table 5 39 MMC SD card SPI mode pin description Additional Information e The data transfer width is 8 bits e Data should be output on the falling edge and must remain valid until the next period Rising edge means data is sampled i e read e The bit order requires most significant bit MSB to be sent out first e Data polarity is
36. NumSectors Total number of sectors on the medium BytesPerSector Number of bytes per sector Table 4 50 FS_DEV_INFO list of structure elements User s amp reference manual for uC FS 2004 2007 Micrium 86 CHAPTER 4 API functions 4 9 Extended functions 4 9 1 FS FileTimeToTimeStamp Description Converts a given FS FILE TIME structure to a timestamp Prototype void FS FileTimeToTimeStamp const FS FILETIME pFileTime U32 pTimeStamp Parameter Description i Pointer to a data structure of type FS_FILETIME that holds the data pFileTime to be converted pTimeStamp Pointer to a U32 variable to store the timestamp Table 4 51 FS_FileTimeToTimeStamp parameter list Additional Information Refer to Structure FS_FILETIME on page 99 to get information about the FS_FILETIME data structure User s amp reference manual for uC FS 2004 2007 Micrium 4 9 2 FS_GetFileSize 87 Description Gets the current file size of a file Prototype U32 FS GetFileSize FS FILE pFile Parameter Description pFile Pointer to a data structure of type FS FILE Table 4 52 FS GetFileSize parameter list Return Value gt 0 File size in bytes 0 OxFFFFFFFE OXFFFFFFFF In case of any error User s amp reference manual for uC FS 2004 2007 Micrium 88 CHAPTER 4 API functions 4 9 3 FS GetFreeSpacef
37. Otherwise the return value is 0 pDirEnt should point to a valid FS DIRENT structure FS DirEnt2Name checks if the pointers are valid To get a valid pointer FS ReadDir should be called before using FS DirEnt2Size Refer to FS ReadDir on page 135 for more information Example void MainTask void U32 FileSize FS DIR pDir FS DIRENT pDirEnt pDir FS OpenDir Open root directory of default device pDirEnt FS ReadDir pDir Read the first directory entry FileSize FS DirEnt2Size pDirEnt if FileSize char ac 50 sprintf ac File size lu n FileSize FS_X_Log ac User s amp reference manual for uC FS 2004 2007 Micrium 130 4 14 5 FS DirEnt2Timef CHAPTER 4 API functions Description Returns the timestamp of the directory entry referred to by pDirEnt Prototype U32 FS DirEnt2Size FS DIRENT pDirEnt Parameter Description pDirEnt Pointer to a directory entry read by FS ReadDir Table 4 93 FS DirEnt2Time parameter list Return value The timestamp of the current directory entry Additional Information If pDirEnt is valid the timestamp of the directory entry will be returned Otherwise the retu pDirl rn value is O Ent should point to a valid FS_D the pointer is valid To get a valid pointer FS Read using FS Dirl R EN
38. U16 Minute U16 Second FS FILETIME Members Description Year Represents the year The year must be greater than 1980 Month Represents the month where January 1 February 2 etc Day Represents the day of the month 1 31 Hour Represents the hour of the day 0 23 Minute Represents the minute of the hour 0 59 Second Represents the second of the minute 0 59 Table 4 65 FS FILETIME list of structure member variables User s amp reference manual for uC FS 2004 2007 Micrium 100 CHAPTER 4 API functions 4 9 14 FS SetBusyLEDCallback Description Specifies callback function to control an LED which shows the state of a specific vol ume Prototype void FS SetBusyLEDCallback const char sVolumeName FS BUSY LED CALLBACK pfBusyLEDCallback Parameter Description sVolumeName Volume name as a string pfBusyLEDCallback Pointer to a busy LED function Table 4 66 FS SetBusyLEDCallback parameter list Additional Information If you intend to show any volume read write activity use this function to set the busy indication for the desired volume Type FS BUSY LED CALLBACK is defined as follows typedef void FS BUSY LED CALLBACK U8 OnOff The parameter onoff indicates whether the LED should be switched on or off Example include FS h void SetBusyLED U8 O
39. W IsPresent Checks if a device is present ATA I O register access functions Reads an IDE register Data from the IDE 9 register are read 16 bit wide FS IDE HW WriteReg Write an IDE register Data to the IDE Z register are written 16 bit wide FS IDE HW ReadData Reads data from the IDE data register FS IDE HW WriteData Writes data to the IDE data register Table 5 75 CompactFlash IDE device driver functions User s amp reference manual for uC FS 2004 2007 Micrium 240 CHAPTER 5 5 5 6 1 FS_IDE_HW_Reset Device drivers Description Resets the bus interface Prototype void FS IDE HW Reset U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 76 FS IDE HW Reset parameter list Additional Information This function is called when the driver detects a new media is present For ATA HD drives there is no action reguired and this function can be empty Example void FS IDE HW X Reset U8 Unit FS USE PARA Unit User s amp reference manual for uC FS 2004 2007 Micrium 241 5 5 6 2 FS_IDE_HW_Delay400ns Description Waits 400ns Prototype void FS IDE HW Delay400ns U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 77 FS IDE HW Delay400ns parameter list Additional Information FS IDE HW X Delay400ns is always
40. __SDMMC_ STATUS amp MMC STATUS READDATA TIMEOUT return FS MMC CARD READ TIMEOUT Continue reading data until FIFO is empty while __SDMMC_STATUS amp MMC STATUS FIFO EMPTY 0 amp amp i lt NumBytes gt gt 1 Any data in the FIFO if __SDMMC STATUS amp MMC STATUS FIFO EMPTY 0 pBuf SDMMC DATA FIFO pBuf i while NumBlocks return 0 User s amp reference manual for yC FS 2004 2007 Micrium 215 5 4 7 10 FS_MMC_HW_X_SendCmd Description Sends and setups the controller to send a specific command to card Prototype void FS MMC HW X SendCmd U8 Unit unsigned Cmd unsigned CmdFlags unsigned ResponseType U32 Arg Parameter Meaning Unit Unit number 0 N Cmd Command to be sent to the card CmdFlags Additional command flags that are necessary for this command Specifies the response format that is expected after sending this ResponseType command Arg Argument sent with command Table 5 64 FS MMC HW X SendCmd parameter list Additional Information This function should send the command specified by Cmd Each command may have some command flags One or a combination of these is possible Command Flag Meaning This flags tells the card controller that the sent command initiate a data transfer This flags tells the card controller that the sent FS MMC CMD FLAG WRITETRANSFER command initiate a data transfer and will write to
41. khk Micrium Inc 949 Crestview Circle Weston FL 33327 1848 uC FS c Copyright 2001 2006 Micrium Inc All rights reserved kkkkkxkxkxkxkxkxkkxkxkxkxkkkxkkkkkkxkkkkkxkxkkkkxkxkkkkkkxkkkkkkkxkkkkxkkkkkkkxkkkkkkxkxkkxkxx k uC FS file system for embedded applications uC FS is protected by international copyright laws Knowledge of the source code may not be used to write a similar product This file may only be used in accordance with a license and should not be re distributed in any way We appreciate your understanding and fairness File FS Conf h Purpose File system configuration END OF HEADER 7 ifndef FS CONF H_ define _FS_CONF_H_ define FS OS ils endif Avoid multiple inclusion 721 FS X OS Init Description Initializes the OS resources Specifically you will need to create at least NumLocks binary semaphores Prototype void FS X OS Init unsigned NumLocks Parameter Meaning NumLocks Number of binary semaphores mutexes that should be created Table 7 1 FS X OS Init parameter list Additional Information This function is called by FS Init You should create all resources required by the OS to support multithreading of the file system User s amp reference manual for uC FS 2004 2007 Micrium 280 CHAPTER 7 OS Integration 7 2 2 FS X OS Lock
42. prin ae o world n m B main c e Cstartup m C2 Output Building configuration Start Flash Debug Updating build tree main c Linking Total number of errors 0 Total number of warnings 0 Figure 3 1 Start project User s amp reference manual for uC FS 2004 2007 Micrium 24 CHAPTER 3 Running yC FS on target hardware 3 2 Step 2 Adding pC FS to the start project Add all source files in the following directories and their subdirectories to your project Application Config FS SampleXDriver RAM Sample os Optional add if you use an RTOS Add only the file compatible to the used operating system It is recommended to keep the provided folder structure Figure 3 2 pC FS project structure User s amp reference manual for uC FS 2004 2007 Micrium 25 Configuring the include path The include path is the path in which the compiler looks for include files In cases where the included files typically header files h do not reside in the same direc tory as the C file to compile an include path needs to be set In order to build the project with all added files you will need to add the following directories to your include path Config FSX Options for node Running emFile General Options C C
43. reference manual for uC FS 2004 2007 Micrium 115 4 12 File system cache functions 4 12 1 FS_AssignCache Description Adds a cache to a specific device Prototype 132 FS AssignCache const char pDevName void pCacheData U32 NumBytes FS INIT CACHE pfinit Parameter Description Devian pDevName is the name of a device If not specified the first device C in the volume table will be used pCacheData Pointer to a buffer that should be used as cache NumBytes Size of the specified buffer Pointer to the initialization function of the desired cache module The following values can be used Pree FS CACHE ALL o FS CACHE MAN FS CACHE RW FS CACHE RW OUOTA Table 4 79 FS AssignCache parameter list Return value gt 0 Buffer is used as cache for the specified device 0 Buffer cannot be used as cache for this device User s amp reference manual for uC FS 2004 2007 Micrium 116 CHAPTER 4 Additional Information API functions To disable the cache for a specific device call FS AssignCache with NumBytes 0 In this case the return value will be 0 There are four different available cache modules that can be assigned to a specific device These modules are the following Cache module Description FS CACHE ALL This module is a pure read cache All sectors that are read from a volume are cached This module does not need to be configured
44. reference manual for uC FS 2004 2007 Micrium 148 CHAPTER 5 Device drivers For example a typical NAND flash with a size of 256 Mbytes has 2048 blocks of 64 pages of 2112 bytes 2048 bytes for data 64 bytes 5 3 1 Supported hardware 5 3 1 1 Tested and compatible NAND flashes In general the driver supports almost all Single Level Cell NAND flashes SLC This includes NAND flashes with page sizes of 512 16 and 2048 64 bytes The table below shows the NAND flashes that have been tested or are compatible with a tested device Manufacturer Device Page size Bytes Size Bits HY27xS08281A 512 16 16Mx8 Hyni HY27xS08561M 512 16 32Mx8 HY27xS08121M 512 16 64Mx8 HY27xA081G1M 512 16 128Mx8 K9F640800xx 512 16 8Mx8 K9F6408U0xx 512 16 8Mx8 K9F280800xx 512 16 16Mx8 K9F2808U0xx 512 16 16Mx8 K9F560800xx 512 16 32Mx8 K9F5608D0xx 512 16 32Mx8 K9F5608U0xx 512 16 32Mx8 Samsung K9F1208Q0xx 512 16 64Mx8 K9F1208D0xx 512 16 64Mx8 K9F1208U0xx 512 16 64Mx8 K9F1208R0xx 512 16 64Mx8 K9K1GO8ROB 512 16 128Mx8 K9K1G08BOB 512 16 128Mx8 K9K1G08U0B 512 16 128Mx8 K9K1G08U0M 512 16 128Mx8 K9T1GJ8U0M 512 16 128Mx8 NAND128R3A 512 16 16Mx8 NAND128W3A 512 16 16Mx8 NAND256R3A 512 16 32Mx8 STMi rosl ctr ni e NAND256W3A 512 16 32Mx8 NAND512R3A 512 16 64Mx8 NAND512W3A 512 16 64Mx8 NAND01GR3A 512 16 128Mx8 NAND01GW3A 512 16 128Mx8 TC5816BFT 512 16 2Mx8 TC58V32AFT 512 16 4Mx8 TC58V64BFTX 512 16 8Mx8 Toshiba TC58256AF
45. unsigned NumBytes int i const U16 pBuf const void pBuffer unsigned NumBlocks pBuf const U16 pBuffer do while __SDMMC_STATUS amp MMC STATUS FIFO EMPTY 0 for i 0 i lt NumBytes gt gt 1 i __SDMMC_DATA_ FIFO pBuf _StartMMCClock Unit if __SDMMC_ STATUS amp MMC STATUS WRITE CRC ERROR return FS MMC CARD WRITE CRC ERROR while NumBlocks Wait until transfer operation has ended while __SDMMC_STATUS amp MMC STATUS DATA TRANFER DONE 0 Wait until write operation has ended while __SDMMC_STATUS amp MMC STATUS DATA PROGRAM DONE 0 return 0 User s amp reference manual for uC FS 2004 2007 Micrium 218 CHAPTER 5 Device drivers 5 4 7 12 FS MMC HW X Delay Description Waits for a specific time in ms Prototype void FS MMC HW X Delay int ms Parameter Meaning ms Milliseconds to wait Table 5 69 FS MMC HW X Delay parameter list Additional Information The delay specified is a minimum delay The actual delay is permitted to be longer This can be helpful when using an RTOS Every RTOS has a delay API function but the accuracy is typically 1 tick which is 1 ms in most cases Therefore a delay of 1 tick is typically between 0 and 1 ms To compensate for this the eguivalent of 1 tick typically 1 should be added to the delay parameter before passsing it to an RTOS delay fun
46. void pData unsigned Off unsigned NumBytes Parameter Meaning Unit Unit number 0 N m Zero based index of page to be read Needs to be smaller than PageIndex R page size pData Pointer to a buffer for read data Off Byte offset within the page NumBytes Number of bytes to read Table 5 14 pfRead parameter list Return value 0 Data successfully transferred I 0 An error has occurred Additional information If the parameter off is smaller than the page size the data area is accessed An off set greater than the page size indicates that the spare area should be accessed User s amp reference manual for uC FS 2004 2007 Micrium 163 5 3 6 5 pfReadEx Description Reads from both the data and the spare area of a page Prototype int pfReadEx U8 Unit U32 PageIndex void pData unsigned Off unsigned NumBytes void pSpare unsigned OffSpare unsigned NumBytesSpare Parameter Meaning Unit Unit number 0 N PageIndex Number of page that should be read pData Pointer to a buffer for read data ae Byte offset within the page which needs to be smaller than the page size NumBytes Number of bytes to read pSpare Pointer to a buffer for spare data Offset from the start of the spare area to the point where spare data should be read First byte of the spare area has the same off set as the page size Example OffSpare Page size 512 OffSpare
47. 5 45 Table 5 46 Table 5 47 Table 5 48 Table 5 49 Table 5 50 Table 5 51 Table 5 52 Table 5 53 Table 5 54 Table 5 55 Table 5 56 Table 5 57 Table 5 58 Table 5 59 Table 5 60 Table 5 61 Table 5 62 Table 5 63 Table 5 64 Table 5 65 215 Table 5 66 Table 5 67 Table 5 68 Table 5 69 Table 5 70 Table 5 71 User s amp reference manual for uC FS FS NAND HW X Read x16 parameter list 174 FS NAND HW X Write x8 parameter list 175 FS NAND HW X Write x16 parameter list 176 FS NAND HW X Delayus parameter list 177 FS NAND HW X Init x8 parameter list 178 FS NAND HW X Init x16 parameter list 179 DataFlash device driver hardware functions 180 FS DF HW X EnableCS parameter list 181 FS DF HW X DisableCS parameter list 182 FS DF HW X Init parameter list 183 FS DF HW X Read parameter list 184 FS DF HW X Write parameter list 185 MMC SD card pin description ceceeeeseee esse eee eaee es 189 MMC SD card SPI mode pin description 190 SPI mode configuration functions 192 SPI mode hardware FUNCTIONS lt lt lt sccesccc c 195 FS MMC HW X EnableCS parameter list 196 FS MMC HW X DisableCS parameter list 197 FS MMC HW X SetMaxSpeed parameter list 198 FS MM
48. 5 Configuring the driver 5 6 5 1 Adding the driver to pC FS To add the driver use FS_AddDevice with the driver label FS_NOR_Driver This function has to be called from FS X AddDevices Refer to FS_X_AddDevices on page 262 for more information Example FS_AddDevice amp FS NOR Driver 5 6 5 2 FS NOR _Configure Description Configures the NOR flash drive This function has to be called from FS X AddDevices after adding the device driver to file system Refer to FS X AddDevices on page 262 for more information Prototype void FS NOR Configure U8 Unit U32 BaseAddr U32 StartAddr U32 NumBytes Parameter Description Unit Unit number 0 N BaseAddr Base address of the NOR flash chip StartAddr Start address of the NOR flash device NumBytes Specifies the size of the NOR flash device in bytes Table 5 85 FS NOR Configure parameter list Additional information If your consists of two identical CFI compliant NOR flash chips with 16 bit interface FS NOR Configure configures both flash chips Refer to FS NOR SetPhyType on page 254 for more information about the different physical type of your device Example Configure a single NOR flash chip void FS X AddDevices void Add driver FS AddDevice 8FS NOR Driver Set physical type single CFI compliant NOR flash chips with 16 bit interface FS NOR SetPhyType 0 amp FS_NOR_PHY
49. Additional Information Low level format Before using the NAND flash as storage device A low level format has to be per formed Refer to FS FormatLow on page 83 and FS FormatlLIfReguired on page 82 for detailed information about low level formatting 5 6 7 1 Further reading For more technical details about CFI compliant flash memory check the documents and specifications that are available free of charge e Common Flash Interface CFI and Command Sets Intel Application Note 646 April 2000 e Common Flash Memory Interface Specification AMD Revision 2 0 December 1 2001 5 6 8 Additional driver functions 5 6 8 1 FS_NOR_GetDiskinfo Description Returns information about the flash disk Prototype void FS_NOR_GetDiskInfo U8 Unit FS NOR DISK INFO pDiskInfo Parameter Description Unit Unit number 0 N pDiskInfo Pointer to a structure of type FS NOR DISK INFO Table 5 87 FS NOR GetDiskInfo parameter list Additional information Refer to Structure FS NOR DISK INFO on page 259 for more information about the structure elements User s amp reference manual for uC FS 2004 2007 Micrium 257 5 6 8 2 FS NOR GetSectorlnfo Description Returns info about a particular physical physical sector Prototype void FS NOR GetSectorInfo U8 Unit U32 PhysSectorIndex FS NOR SECTOR INFO pSectorInfo
50. Additional Information MultiMedia cards do not have mechanical write protection switches and should always return 0 If you are using SD cards be aware that the mechanical switch does not really protect the card physically from being overwritten it is the responsibility of the host to respect the status of that switch Example char FS MMC HW X IsWriteProtected U8 Unit return 0 If the card slot has no write switch detector return 0 User s amp reference manual for uC FS 2004 2007 Micrium 201 5 4 6 6 FS MMC HW X IsPresent Description Checks whether a card is present or not Prototype char FS MMC HW X IsPresent U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 47 FS MMC HW X IsPresent parameter list Return value Return value Description FS MEDIA STATE UNKNOWN FS MEDIA NOT PRESENT FS MEDIA IS PRESENT The card state is unknown A card is not present A card is present Table 5 48 FS MMC HW X IsPresent list of return values Additional Information Usually a card slot provides a hardware signal that can be used for card presence determination The sample code below is for a specific hardware that does not have such a signal Therefore the presence of a card is unknown and you have to return FS MEDIA STATE UNKNOWN Then uC FS tries reading the card to figure out if a valid card is inserted i
51. DIRENT pDirEnt pDir FS OpenDir Open the root directory of default device if pDir do char acDirName 20 pDirEnt FS_ReadDir pDir FS_DirEnt2Name pDirEnt acDirName Get name of the current DirEntry if void pDirEnt NULL break No more files or directories sprintf _acBuffer s n acName FS_X_Log _acBuffer while 1 FS CloseDir pDir else FS_X_ErrorOut Unable to open directory n User s amp reference manual for uC FS 2004 2007 Micrium 127 4 14 2 FS DirEnt2Attr Description Retrieves the attributes of the directory entry referred to by pDirEnt Prototype void FS_DirEnt2Attr FS_DIRENT pDirEnt U8 pAttr Parameter Description pDirEnt Pointer to a directory entry read by FS ReadDir pAttr Pointer to U8 variable in which the attributes should be stored Table 4 89 FS DirEnt2Attr parameter list Additional Information These attributes are available Parameter Description FS ATTR DIRECTORY pDirEnt is a directory FS ATTR ARCHIVE pDirEnt has the ARCHIVE attribute set FS ATTR READ ONLY pDirEnt has the READ ONLY attribute set FS ATTR HIDDEN pDirEnt has the HIDDEN attribute set SYSTEM pDirEnt has the SYSTEM attribute set Table 4 90 FS DirEnt2Attr list of possible attributes T
52. FS Even if you do not have the Microsoft compiler you should read this chapter in order to understand how an appli cation can use UC FS 2 2 1 Building the sample program Open the workspace FS Start dsw with MS Visual Studio for example double click ing it There is no further configuration necessary You should be able to build the application without any error or warning message 2 2 2 Stepping through the sample The sample project uses the RAM disk driver for demonstration The main function of the sample application Start c calls the function FSTask FSTask initialises the file system and executes some basic file system operations The sample application Start c step by step FSTask is called FSTask initialises and adds a device to uC FS outputs the volume name calls FS GetFreeVolumeSpace and outputs the return value the available free space of the RAM disk to console window creates and opens a file test with write access File txt on the device writes 4 bytes into the file and closes the file handle or outputs an error mes sage 7 calls FS GetFreeVolumeSpace and outputs the return value the available free space of the RAM disk again to console window 8 outputs an guit message and runs into an endless loop AUNE oul User s amp reference manual for uC FS 2004 2007 Micrium 16 CHAPTER 2 Getting Started The sample step by step 1 After starting the debugger by stepping into the
53. Hard drive 2431 12434 4167 ARM 7 50 MHz Compact Flash IDE mode 1882 1882 2000 ARM 7 50 MHz Compact Flash mem mapped 2782 2782 2560 ARM 7 50 MHz MMC SD using SPI with 12MHz 1280 1333 1488 XScale 208 MMC SD using SD4 card mode with MHz 20MHz 7262 7262 5389 ARM 7 50 MHz SMC 392 390 771 ARM 7 50 MHz NAND Flash 8MB 474 474 771 ARM 7 33 MHz NOR flash 172 91 1254 ARM 7 50 MHz RAM disk 4000 4000 4571 Table 9 2 Performance valus for sample configurations 9 2 1 1 Description of the performance tests The performance tests are executed as described and in the order below Performance test procedure 1 2 3 8 9 Format the drive wo Writing Open a file for writing Write data to the opened file in chunks of 64 kBytes using 80 of the volume capacity but no more than 4 MByte Writing a 64KByte chunk is measured Close the file W1 Writing Reopen the file for writing old created file will be deleted Write data to the opened file in chunks of 64kBytes using 80 of the capacity of the medium but no more than 4MByte Writing a 64KByte chunk is measured Close the file R Reading Open the file for reading Read 4 MBytes from file in 64KByte chunks Reading a 64KByte chunk is mea sured R1 10 Close the file 11 Show the performance results User s amp reference manual for uC FS 2004 2007 Micrium 294 CHAPTER 9 Performance and Resource usage
54. II I O cards CompactFlash cards are designed with flash technology a nonvolatile storage solution that does not reguire a battery to retain data indefinitely The CompactFlash card specification version 2 0 supports data rates up to 16MB sec and capacities up to 137GB CF cards consume only five percent of the power reguired by small disk drives a S iL 2 CompactFlash cards support both 3 3V and 5V operation and can be interchanged between 3 3V and 5V systems This means that any CF card can operate at either voltage Other small form factor flash cards may be available to operate at 3 3V or 5V but any single card can operate at only one of the voltages CF data storage cards are also available using magnetic disk IBM Microdrive User s amp reference manual for uC FS 2004 2007 Micrium 232 CHAPTER 5 Device drivers Modes of operation interface modes Compact Flash cards can operate in three modes e Memory card mode e I O Card mode e True IDE mode Supported modes of operation interface modes Currently TRUE IDE and MEMORY CARD mode are supported User s amp reference manual for uC FS 2004 2007 Micrium Memory card mode pin functions SENTE Dir Pin Description name These address lines along with the REG signal are 8 10 11 1 used to select the following the 1 0 port address 2 14 15 1 registers within the CompactFlash Storage Card or A10 AO I 6 17
55. INFO refer to Structure FS FORMAT INFO on page 84 User s amp reference manual for uC FS 2004 2007 Micrium 84 CHAPTER 4 4 8 6 Structure FS FORMAT INFO Description API functions The FS_FORMAT_INFO structure represents the information used to format a volume Prototype typedef struct U16 SectorsPerCluster U16 NumRootDirEntries FS DEV INFO pDevInfo FS FORMAT INFO Members Description SectorsPerCluster NumRootDirEntries pDevInfo A cluster is the minimal unit size a file system can handle Sectors are combined together to form a cluster Represents the number of directory entries the root directory should have Typically it is only used for FAT12 and FAT16 drives FAT32 has a dynamically grow table Pointer to a FS DEV NFO structure Table 4 49 FS FORMAT INFO list of structure elements User s amp reference manual for uC FS 2004 2007 Micrium 85 4 8 7 Structure FS DEV INFO Description The FS DEV INFO structure contains the medium information Prototype typedef struct U16 NumHeads U16 SectorsPerTrack U32 NumSectors U16 BytesPerSector FS DEV INFO Members Description Number of heads on the drive This is relevant for mechanical NumHeads 3 drives only Number of sectors in each track This is relevant for mechani SectorsPerTrack i cal drives only
56. Mbytes x 8 or 4 Mbytes x 16 M58LW064 64 Mbytes 8 Mbytes x 8 4Mbytes x 16 MT28F128 128 Mbytes Micron MT28F256 256 Mbytes MT28F320 32 Mbytes MT28F640 64 Mbytes Table 5 84 List of supported serial NOR flashes Support for devices not available in this list Most other NOR flash devices are compatible with one of the supported devices Thus the driver can be used with these devices or may only need a little modification which can be easily done Get in touch with us if you have questions about support for devices not in this list 5 6 2 Theory of operation Differentiating between logical sectors or blocks and physical sectors is very essential to understand this section A logical sector block is the base unit of any file system its usual size is 512 bytes A physical sector is an array of bytes on the flash chip that are erased together typically between 2 Kbytes 128 Kbytes The flash chip driver is an abstraction layer between these two types of sectors Every time a logical sector is being updated it is marked as invalid and the new con tent of this sector is written into another area of the flash The physical address and the order of physical sectors can change with every write access Hence there can not exist a direct relation between the sector number and its physical location User s amp reference manual for uC FS 2004 2007 Micrium 250 CHAPTER 5 Device drivers The flash driver manages the logical secto
57. Porting uC FS 2 x to 3 x 10 4 6 MMC driver differences rsion 3 X S P tien FLE EURE FS USE MMC DRIVER FS AddDevice FS MMC CardMode Driver FS MMC USE SPI MODE FS AddDevice FS MMC SPI Driver FS MMC MAXUNIT FS USE CRC FS MMC ActivateCRC FS MMC DeactivateCRC FS MMC SUPPORT 4BIT MODE Table 10 11 Differences between uC FS v 2 x v 3 x removed MMC macros Refer to the section MultiMedia amp SD card driver on page 188 for detailed informa tion about the MMC driver in uC FS version 3 x 10 4 7 CF IDE driver differences In version 3 x removed macros FS USE IDE DRIVER FS_AddDevice amp FS_IDI FS_IDE_MAXUNIT gt Table 10 12 Differences between uC FS v 2 x v 3 x removed CF IDE macros Alternative zaj _Driver In version 3 x is the hardware inteface of the CF IDE driver simplified Only 6 hard ware functions have to implemented Hardware interface version 2 x Hardware interface version 3 x FS_IDE_HW_X_HWReset FS_IDE_HW_X_HWReset FS IDE HW X Delay400ns FS IDE HW X Delay400ns FS IDE HW X GetAltStatus FS IDE HW X GetCylHigh FS IDE HW X GetCylLow FS IDE HW X GetData FS IDE HW X ReadData FS IDE HW X GetError FS IDE HW X GetSectorCount FS_IDE_HW_X_GetSectorNo FS IDE HW
58. Q A PO CHAPTER 11 FAQs FAQs Is my data safe when an unexpected RESET occurs In general the data which is already on the medium is safe If a read operation is interrupted this is completely harmless If a write operation is interrupted the data written in this operation may or may not be stored on the medium depending on when the unexpected RESET occurred In any case the data which was on the media prior to the write operation is not affected directory entries are not messed up the file allocation table is kept in order This is true if your storage medium is not affected by the RESET meaning that it is able to complete a pending write operation Which is typically the case with Flash memory cards other than SMC I use FAT and I can only create a limited number of root directory entries Why With FAT12 and FAT16 the root directory is special because it has a fixed size During media format one can determine the size but once formatted this value is constant and determines the number of entries the root directory can hold FAT32 does not have this limitation and the root directory s size can be variable Microsoft s FAT32 File System Specification says on page 22 For FAT12 and FAT16 media the root directory is located in a fixed location on the disk immediately following the last FAT and is of a fixed size in sectors computed from the BPB_RootEntCnt value For FAT32 the root directory can be of variable size and i
59. Return value gt 0 Current position of the file pointer in the file 1 In case of any error Additional Information In this version of uC FS this function simply returns the file pointer element of the file s FS FILE structure Nevertheless you should not access the FS FILE structure yourself because that data structure may change in the future In conjunction with FS FSeek this function can also be used to examine the file size By setting the file pointer to the end of the file using FS SEEK END the length of the file can now be retrieved by calling FS FTell This function is identical to FS GetFilePos Refer to FS_GetFilePos on page 56 for more information Example const char acText hello world n void MainTask void FS FILE pFile I32 Pos pFile FS FOpen test txt w if pFile 0 FS FWrite acText 1 strlen acText pFile Pos FS FTell pFile FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 56 CHAPTER 4 API functions 4 5 3 FS GetFilePos Description Returns the current position of a file pointer Prototype 132 FS GetFilePos FS FILE pFile Parameter Description pFile Pointer to a data structure of type FS FILE Table 4 18 FS GetFilePos parameter list Return value gt 0 Current position of the file pointer in the file 1 In case of any error Ad
60. User s amp reference manual for uC FS 2004 2007 Micrium Chapter 10 Porting LC FS 2 x to 3 x User s amp reference manual for uC FS 2004 2007 Micrium 296 CHAPTER 10 Porting uC FS 2 x to 3 x 10 1 Differences from version 2 x to 3 x Most of the differences from uC FS version 2 x to version 3 x are internal The API of UC FS version 2 x is a subset of the API of version 3 x Only few functions are com pletely removed Refer to section API differences on page 297 for a complete over view of the removed and obsolete functions uC FS version 3 has a new driver handling You can include drivers and allocate the required memory for the accordant driver without the need to recompile the whole file system Refer to uC FS Configuration on page 267 for detailed information about the integration of a driver into uC FS For detailed information to the uC FS device drivers refer to the chapter Device drivers on page 141 Because of these differences we recommend to start with a new file system project and include your application code if the start project runs without any problem Refer to the chapter Running uC FS on target hardware on page 21 for detailed information about the best way to start the work with uC FS version 3 x The following sections gives an overview about the changes from uC FS version 2 x to uC FS version 3 in table form User s amp reference manual for uC FS 2004 2007 Micrium 10 2 AP
61. Your full name and the name of your supervisor Your company name Your job title Your email address and telephone number Company name and address Your company s main phone number Your company s web site address Name and version of the product Please send this information to licensing micrium com Contact address Micrium 949 Crestview Circle Weston FL 33327 1848 U S A Phone 1 954 217 2036 FAX 1 954 217 2037 WEB www micrium com Email support micrium com User s amp reference manual for uC FS 2004 2007 Micrium Manual versions If you find any errors in this document please inform us and we will make the appro priate corrections for future releases For further information on topics or routines not yet specified please contact us Print date October 4 2007 Manual version Date By Explanation Chapter API functions Storage layer functions added Chapter Running uC FS on target hardware Structure Directory names updated Chapter Device drivers Structure changed Subsection Resource usage added to every driver section Section NAND flash driver updated and enhanced Section NOR flash driver updated and enhanced Section Multimedia amp SD card driver enhanced Graphics updated Subsection Troubleshooting added Section DataFlash driver removed The DataFlash driver is now integrated in the NAND driver Chapter Performance and resource usage Sect
62. about the FS FileTime structure refer to Structure FS FILETIME on page 99 User s amp reference manual for uC FS 2004 2007 Micrium 68 CHAPTER 4 API functions 4 6 11 FS_SetEndOfFile Description Sets the end of file for the specified file Prototype int FS SetEndofFile FS FILE pFile Parameter Description pFile Pointer to a data structure of type FS FILE Table 4 35 FS SetEndoOfFile parameter list Return value 0 End of File was set 1 Operation failed Additional Information pFile should point to a file that has been opened with write permission Refer to FS FOpen on page 48 This function can be used to truncate or extend a file If the file is extended the contents of the file between the old EOF position and the new position are not defined Example void MainTask void FS FILE pFile pFile FS FOpen test bin r FS SetFilePos pFile 2000 FS SetEndofFile pFile FS Fclose pFile User s amp reference manual for uC FS 2004 2007 Micrium 69 4 6 12 FS Truncate Description Truncates a file opened with FS FOpen to the specified size Prototype int FS Truncate FS FILE pFile U32 NewSize Parameter Description pFile Pointer to a data structure of type FS FILE NewSize New size of the file Table 4 36 FS Truncate parameter list Return value 0 Truncation was successful 1 Truncation fail
63. application your screen should look as the screenshot below The main function calls FSTask Globals All global members main if pFile FS Write pFile Test 4 i Workspace FS_Start 1 project s FS_FClose pFile EEA FS Start files Vans E23 Application Rome mets Gen ICE VE io choc O0 i TER v FS GetVoluneFreeSpace sVolNane E23 Config printf Free space d bytes n v ConfigR MDisk c printf Finished n FS_Conth while 1 FS X Panic c FS BG Core i B Driver 3636363 DE DE JEJE IE DE JEJE JE JE JE DE JE JE JE JE DE DE JE JEJE IE DE JEJE JE JE JE JE JE IE JE JEJE DE JE JE JE JE JE JE JE JE JE JE JE E JE JE JE JE DE JE JE JE IE JE JE JE IE JE JE JEE JEJE EHE IE HE JE IE JE JE JE JE JE JE DE DE JE JE JE JE JE JE JE JE DE JE JE JE DE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE EJE E bis H ROS H E External Dependencies 2 void main void void main void FSTask Call simple Start file system application SRR EOF HHH HHH HHH HHH JE JE KA KRKA KA NAKA JE JE JE DE DE DE DE DE HEHEHE DE DE DE JE JE JE DE JE DE DE IE EDEN IN Figure 2 1 FS Start project main User s amp reference manual for uC FS 2004 2007 Micrium 2 The first things called from FSTask tion initialises the file system and calls FS AddDevices 17 is the uC FS function FS Init This func The funct
64. as strcmp etc of your compiler Table 6 7 Miscellaneous configuration macros User s amp reference manual for uC FS 2004 2007 Micrium 276 CHAPTER 6 HCIFS Configuration 6 2 7 Sample configuration The uC FS configuration file FS Conf h is located in Micrium Software uC FS Config uC FS compiles and runs without any problem with the default settings If you want to change the default configuration insert the corresponding macros in the delivered FS_Conf h KEKE KKK KEK KKK KEK KKK KEKE KKK KEK KEK KEKE X A X KKK KEKE KKK KEK KKK KKK KKK A KKK KKK KKK KKK k k kk k Micrium Inc hi 949 Crestview Circle i Weston FL 33327 1848 ki uC FS a c Copyright 2001 2006 Micrium Inc All rights reserved KKK KKK KKK KKK KEKE KKK KK KKK k k A AX X XK X A AX AK KZ A X AX XZ A AX XK X A AZ AX XK X A XK XK ZK A AZ AX X A AX X k k kk k kk k kh WC FS file system for embedded applications uC FS is protected by international copyright laws Knowledge of the source code may not be used to write a similar product This file may only be used in accordance with a license and should not be re distributed in any way We appreciate your understanding and fairness File FS Conf h Purpose uC FS compile time configuration settings END OF HEADER 7 ifndef _FS_CONF_H_ define _FS_CONF_H_ define FS DEBUG LEVEL 1 define FS
65. be more precise any NOR flash which fulfills the following reguirements e Minimum of 2 physical sectors At least 2 sectors need to be identical in size e Physical sectors need to be at least 2048 bytes each e Physical sectors do not need to be uniform for example 8 8 Kbytes 3 64 Kbytes is permitted e Flash needs to be re writeable without erase The same location can be written to multiple times without erase as long as only 1 bits are converted to 0 bits e Erase clears all bits in a physical sector to 1 Physical layer The driver requires a physical layer for the flash device The following physical layers are available e FS NOR PHY CFI 1x16 CFI compliant parallel NOR flash with 1x16 bit inter face e FS NOR PHY CFI 2x16 CFI compliant parallel NOR flash with 2x16 bit inter face e FS NOR PHY SERIALFLASH M25P Serial flash ST M25Pxx family e Physical layer template Common flash interface CFI The NOR flash driver can be used with any CFI compliant 16 bit chip The Common Flash Memory Interface CFI is an open specification which may be implemented freely by flash memory vendors in their devices It was developed jointly by Intel AMD Sharp and Fujitsu The idea behind CFI was the interchangeability of current and future flash memory devices offered by different vendors If you use only CFI compliant flash memory chips you are able to use one driver for different flash products by reading id
66. called when a command is sent or parameters are set in the IDE CF drive The integrated logic may need a delay of 400ns When using slow IDE CF drives with fast processors this function should guarantee that a delay of 400ns is kept However this function may be empty if you intend to use fast drives Modern CF Cards and IDE drives are faster than 400ns when executing commands Example void FS IDE HW X Delay400ns U8 Unit FS USE PARA Unit User s amp reference manual for uC FS 2004 2007 Micrium 242 CHAPTER 5 5 5 6 3 FS_IDE_HW_IsPresent Description Checks if the device is connected Prototype U8 FS IDE HW IsPresent U8 Unit Device drivers Parameter Meaning Upit Unit number 0 N Table 5 78 FS IDE HW IsPresent parameter list Return value 1 Device is connected 0 Device is not connected Example int FS IDE HW IsPresent U8 Unit FS USE PARA Unit return 1 User s amp reference manual for uC FS 2004 2007 Micrium 5 5 6 4 FS IDE HW_ReadReg 243 Description Reads an IDE register Data from the IDE register are read 16 bit wide Prototype U16 FS IDE HW ReadReg U8 Unit unsigned AddrOff Parameter Meaning Unit Unit number 0 N AddrOff Address offset that specifies which IDE register should be read Table 5 79 FS IDE HW ReadReg parameter list Return value Da
67. flash driver supports both options User s amp reference manual for uC FS 2004 2007 Micrium 252 CHAPTER 5 Device drivers 5 6 2 1 Software structure The NOR flash driver is divided into different layers which are shown in the illustra tion below Serial NOR flashes Parallel NOR flashes 1x8 bit 1x16 bit or 2x16 bit interfaces It is possible to use the NOR flash driver also with serial NOR flashes Only the hard ware layer needs to be ported Normally no changes to the physical layer are required If the physical layer needs to be adapted a template is available 5 6 3 Fail safe operation The uC FS NOR driver is fail safe That means that the driver makes only atomic actions and takes the responsibility that the data managed by the file system is always valid In case of power loss or power reset during a write operation it is always assured that only valid data is stored in the flash If the power loss interrupts the write operation the old data will be kept and not corrupted 5 6 4 Wear leveling Wear leveling is supported by the driver Wear leveling makes sure that the number of erase cycles remains approximately equal for each sector Maximum erase count difference is set to 5 This value specifies a maximum difference of erase counts for different physical sectors before the wear leveling uses the sector with the lowest erase count User s amp reference manual for uC FS 2004 2007 Micrium 253 5 6
68. is required e ISO IEC ANSI 9899 1990 C90 with support for C style comments e ISO IEC 9899 1999 C99 e ISO IEC 14882 1998 C If your compiler has some limitations let us know and we will inform you if these will be a problem when compiling the software Any compiler for 16 32 64 bit CPUs or DSPs that we know of can be used most 8 bit compilers can be used as well A C compiler is not required but can be used The application program can there fore also be programmed in C if desired User s amp reference manual for uC FS 2004 2007 Micrium Chapter 2 Getting Started This chapter provides a step by step introduction to using uC FS User s amp reference manual for uC FS 2004 2007 Micrium 14 CHAPTER 2 Getting Started 2 1 Installation uC FS is shipped as a CD ROM or as a zip file in electronic form In order to install it proceed as follows e If you received a CD copy the entire contents to your hard drive into any folder of your choice When copying keep all files in their respective sub directories Make sure the files are not read only after copying e If you received a zip file extract it to any folder of your choice preserving the directory structure of the zip file User s amp reference manual for uC FS 2004 2007 Micrium 2 2 Using the Windows sample If you have MS Visual C 6 00 or any later version available you will be able to work with a Windows sample project using uC
69. list Return value 0 If the file pointer has been positioned according to the parameters 1 In case of any error Additional Information The FS SetFilePos function moves the file pointer to a new location that is an off set in bytes from MoveMethod You can use FS SetFilePos to reposition the pointer anywhere in a file The pointer can also be positioned beyond the end of the file Valid values for parameter MoveMethod are Permitted values for parameter MoveMethod FS FILE BEGIN starting point is zero or the beginning of the The starting point is the current value of the file FS FILE CURRENT pointer l The starting point is the current end of file posi FS_FILE_END tion This function is identical to FS FSeek Refer to FS_FSeek on page 54 for more information Example const char acText some text will be overwritten n void MainTask void FS_FILE pFile pFile FS_FOpen test txt w if pFile 0 FS FWrite acText 1 strlen acText pFile FS FSeek pFile 4 FS SEEK CUR FS FWrite acText 1 strlen acText pFile FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 58 CHAPTER 4 API functions 4 6 Operations on files 4 6 1 FS_CopyFile Description Copies an existing file to a new file Prototype int FS CopyFile const char sSource const ch
70. may just try reading and writing a raw sector Here is an example function that tries writing a single sector to your device After reading back and verifying the sector data you know if sectored access to the device is possible and if your device is working int WriteSector void U8 acBufferOut FS MAX SECTOR SIZE U8 acBufferIn FS MAX SECTOR SIZE U32 SecNum int KL SecNum 80 Do not write on the first sectors They contain information about partitioning and media geometry for i 0 i lt FS MAX SECTOR SIZE i we fill the buffer with data acBufferOut i i 256 x FS IoCtl FS CMD WRITE SECTOR SecNum acBufferOut Write one sector if x 0 FS_X_Log Cannot write to sector n return 1 x FS IoCtl FS CMD READ SECTOR SecNum acBufferIn read the sector LE x 150 FS X Log Cannot read from sector n return 1 for i 0 i lt FS MAX SECTOR SIZE i if acBufferIn i acBufferOut i FS X Log Sector not correctly written n User s amp reference manual for uC FS 2004 2007 Micrium 288 CHAPTER 8 Debugging return 1 return 0 If you still receive no valid file pointer although the sectors of the device is accessible and other operating systems report the device to be valid you may have to take a look into the running system by stepping through the function FS FOpen User s amp reference manual
71. mmc If not specified the first device in the device table will be used UnitNum is the number for the unit of the device If not specified unit O will be used Note that it is not allowed to specify UnitNum if DevName has not been spec ified e DirPathList is a complete path to an existing subdirectory The path must start and end with a character Directory names in the path are separated by If DirPathList is not specified the root directory on the device will be used e DirectoryName and all other directory names have to follow the standard FAT naming conventions for example 8 3 notation if support for long file names is not enabled To open the root directory simply use an empty string for pDirName Example FS DIR pDir void FSTaskl void Open directory test default driver on default device pDir FS OpenDir test void FSTask2 void Open root directory RAM device driver on default device pDir FS_OpenDir ram User s amp reference manual for uC FS 2004 2007 Micrium 4 14 8 2 FS ReadDir Description Reads next directory entry in directory specified by p1 Prototype FS DIRENT FS ReadDir FS DIR pDir Parameter Description p Dir Pointer to an opened directory Table 4 98 FS_ReadDir parameter list Return value Returns a pointer to a directory entry If there are no more entries in
72. one mano a ann pede eet 287 10 Performance and Resource usage cece cece eee e eee e eee a aa aaeeeeeeeeeeeeeeeeeeeeeeeeeeenentee 289 10 1 Memory footprint kit aah ner alee as cl mena ee Baa ere 290 10 2 Performance cae Seats a ed viens Sag p re te dae aid ble aa aed daa dale ath Pas rente 293 11 Porting PCIE S SION Xo nn ne ee be Se tie tetas ete tte Siderits 295 11 1 Differences from version 2 x to 3 x 296 11 2 API diff rences saunas ats a Valo KO BA K pod eek alt ae K d A ld 297 11 3 Configuration differences sun VEE hae tie VE de PRE KA PEN es 298 11 4 DEVICE driVe T seda seda esku tears ca degen es gst aunds KR VA Aka kA RAM antenne diese 299 11 5 OS Integration sis Poste gia Sia dis nee cay veld dopln BES nate pale Cant polsk u n ee teat ee 304 12 RS s adnu to laka s ata tr dons dresse rer tite S dubu nelle Tee Venere 305 12 1 FAQS z nooo o ua Bee n Aa o od zb re Aa u nec u v ago al u 306 WS ANG B K zu eres a A KA C k l P AKO a 307 User s amp reference manual for uC FS 2004 2006 Micrium List of Figures Figure title Figure 2 1 Figure 2 2 Figure 2 3 Figure 2 4 Figure 3 1 Figure 3 2 Figure 3 3 Figure 3 4 Figure 3 5 Figure 5 1 BS Stati project MAN uns nn FS Start project FSTask s oo 40oe oseeoen0o FS Start project FSTask c scsssssesssstcesccssneceees FS Start project console output 4 Start PTOJ ES cente
73. pflnitGetDevicelnfo Description Initializes hardware layer resets NAND flash and tries to identify the NAND flash If the NAND flash can be handled FS NAND DEVICE INFO is filled Prototype int pfInitGetDeviceInfo U8 Unit FS NAND DEVICE INFO pDevInfo Parameter Meaning Unit Unit number 0 N pDevInfo Pointer to a structure of type FS NAND DEVICE INFO Table 5 12 pfInitGetDeviceInfo parameter list Return value 0 On success 1 In case of an error User s amp reference manual for uC FS 2004 2007 Micrium 161 5 3 6 3 pflsWP Description Checks if the device is write protected This is done by reading bit 7 of the status register Typical reason for write protection is that either the supply voltage is too low or the WP pin is active low Prototype int pfIsWP U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 13 pfIsWP parameter list Return value 0 Device is not write protected 1 Device is write protected User s amp reference manual for uC FS 2004 2007 Micrium 162 CHAPTER 5 Device drivers 5 3 6 4 pfRead Description This function can be used to read from the data or spare area of the device The spare area is assumed to be located right after the main area Prototype int pfRead U8 Unit U32 PageIndex
74. printf function U16 FS X ErrorOut const char s printf s s User s amp reference manual for uC FS 2004 2007 Micrium 287 8 4 Troubleshooting If you are used to C like file operations you already know the fopen function In uC FS there is an equivalent function called FS FOpen You specify a name an access mode and if this kind of file access is allowed and no error occurs you get a pointer to a file handle in return For more information about the parameters refer to FS FOpen on page 48 Open a file FS FILE pfile pfile FS FOpen test txt r if pFile 0 return 1 report error else return 0 file system is up and running If this pointer is zero after calling FS FOpen there was a problem opening the file There are basically some common reasons why this could happen e The file or path does not exist e The drive could not be read or written e The drive contains an invalid BIOS parameter block or partition table These faults can be caused by corrupted media To verify the validity of your medium either check if the medium is physically okay or check the medium with another operation system for example Windows But there are also faults that are relatively seldom but also possible A compiler linker error has occurred Stack overflow Memory failure Electro magnetic influence EMC EMV ESD To find out what the real reason for the error is you
75. project con figuration settings The start application should print out the storage space of the device twice once before a file has been written to the device and once afterwards User s A reference manual for uC FS 2004 2007 Micrium 26 CHAPTER 3 Running yC FS on target hardware 3 3 Step 3 Adding the device driver To configure uC FS with a device driver 2 things need to be done at the same time e Adding device driver source to project e Adding hardware routines to project Every recommended step is explained in the following sections For example the implementation of the MMC SD driver is shown but all steps should be easy to adapt on every other device driver implementation 3 3 1 Adding the device driver source to project Add the driver sources to the project and add the directory to the include path Example IAR Embedded Workbench IDE E ConfigRAMDisk c m FS X Panic c m MMC Drv c mmc x Hw h Figure 3 4 Add driver sources to project Most drivers reguire additional hardware routines to work with the specific hardware If your driver requires low level 1 0 routines to access the hardware you will have to provide them Drivers which reguire hardware routines are e NAND e MMC SD cards e Compact flash IDE Drivers which not require hardware routines are e NOR flash e RAM User s amp refer
76. the directory or in case of any error 0 is returned Example Refer to FS_CloseDir on page 126 User s amp reference manual for uC FS 2004 2007 Micrium 136 CHAPTER 4 API functions 4 14 9 FS_ReadSector Description Reads a sector from a device Prototype int FS_ReadSector const char sVolume const void pData U32 SectorIndex Parameter Description sVolume Volume name pData Pointer to a data buffer where the read data should be stored SectorIndex Index of the sector from which data should be read Table 4 99 FS ReadSector parameter list Return value 0 On success I 0 On error Additional information This function is obsolete Use instead FS STORAGE ReadSector on page 104 User s amp reference manual for uC FS 2004 2007 Micrium 4 14 9 1 FS RewindDir Description 137 Sets the current pointer for reading a directory entry to the first entry in the direc tory Prototype void FS RewindDir FS DIR pDir Parameter Description pDir Pointer to directory structure Table 4 100 FS_RewindDir parameter list Example void MainTask void FS_DIR pDir FS_DIRENT pDirEnt char acDirName 20 pDir FS_OpenDir Open the root directory of default device if pDir do char acDirName 20 pDirEnt FS_ReadDir pDir FS_DirEnt2Name pDirEnt acDirName Get name of if vo
77. uC FS 2004 2007 Micrium 192 CHAPTER 5 Device drivers 5 4 3 Fail safe operation Unexpected Reset The data will be preserved Power failure Power failure can be critical If the card does not have sufficient time to complete a write operation data may be lost Countermeasures make sure the power supply for the card drops slowly 5 4 4 Wear leveling MMC SD cards are controlled by an internal controller This controller also handles wear leveling Therefore the driver does not need to handle wear leveling 5 4 5 Configuration 5 4 5 1 Adding the driver to pC FS To add the driver use FS_AddDevice with either the driver label FS MMC SPI Driver Or FS MMC CardMode Driver This function has to be called from within FS X AddDevices Refer to FS X AddDevices on page 262 for more information Example SPI mode FS AddDevice 4FS MMC SPI Driver Card mode FS AddDevice amp FS MMC CardMode Driver 5 4 5 2 Cyclic redundancy check CRC The cyclic redundancy check CRC is a method to produce a checksum The check sum is a small fixed number of bits against a block of data The checksum is used to detect errors after transmission or storage A CRC is computed and appended before transmission or storage and verified afterwards by the recipient to confirm that no changes occurred on transit CRC is a good solution for error detection but reduces the transmission speed because a CRC checksum has to be comput
78. v 2 x v 3 x list of renamed de 299 Differences between uC FS v 2 x v 3 x adding a driver 2004 2006 Micrium Table 10 6 Differences between uC FS v 2 x v 3 x removed RAMDISK macros 300 Table 10 7 Differences between uC FS v 2 x v 3 x removed NAND driver macros 300 Table 10 8 Differences between uC FS v 2 x v 3 x IDE driver hard ware interface differences 300 Table 10 9 Differences between uC FS v 2 x v 3 x adding a driver 301 Table 10 10 Differences between uC FS v 2 x v 3 x IDE driver hard ware interface differences 301 Table 10 11 Differences between uC FS v 2 x v 3 x removed MMC macros 302 Table 10 12 Differences between uC FS v 2 x v 3 x removed CF IDE macros 302 Table 10 13 Differences between uC FS v 2 x v 3 x CF IDE driver hard ware interface differences 302 Table 10 14 Differences between uC FS v 2 x v 3 x removed Flash NOR flash macros 303 Table 10 15 Differences between uC FS v 2 x v 3 x removed Serial Flash DataFlash macros 303 Table 10 16 Differences between uC FS v 2 x v 3 x removed Windrive macros 304 Table 10 17 Differences between uC FS v 2 x v 3 x removed replaced configuration macros 304 Table 10 18 Differences between uC FS v 2 x v 3 x Changes in the OS interface 304 User s amp reference manual for uC FS 2004 2006 Micrium Chapter 1 Introduction to uC FS 1 1 What is pC FS uC FS is a file system that can be u
79. void MainTask void FS FILE pFile pFile FS FOpen test txt r if pFile 0 146 Err Err FS FError pFile FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 4 13 4 FS_ErrorNo2Text Description Retrieves text for a given error code Prototype const char FS_ErrorNo2Text int ErrCode 125 Parameter Description ErrCode The returned error code Table 4 87 FS_ErrorNo2Text parameter list Return value Returns the string according to the ErrCode Example void MainTask void FS_FILE pFile pFile FS_FOpen test txt r if pFile 0 int Err Err FS_FError pFile FS_X_Log Open file error FS X Log FS ErrorNo2Text Err FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 126 CHAPTER 4 API functions 4 14 Obsolete functions This section contains reference information for obsolete functions 4 14 1 FS_CloseDir Description Closes a directory referred to by the parameter pDir Prototype int FS CloseDir FS DIR pDir Parameter Description pDir Pointer to a data structure of type FS DIR Table 4 88 FS CloseDir parameter list Return Value 0 If the directory was successfully closed 1 In case of any error Example void MainTask void FS DIR pDir FS
80. 12 Step 12 Get the size of a file FS GetFileSize NULL endif es x Ne User s amp reference manual for uC FS 2004 2007 Micrium 292 CHAPTER 9 Performance and Resource usage 9 1 4 Memory requirements The following table shows the memory requirement of the used functions Description PON Kbytes Step 1 Minimum file system without any driver 7 0 Step 2 Write a file 1 1 Step 3 Remove a file 0 1 Step 4 Open directory 0 5 Step 5 Create directory 0 5 Step 6 Long file name support 2 0 Step 7 Low level format a medium 0 2 Step 8 High level format a medium 1 8 Step 9 Assign a cache FS CACHE ALL 0 4 Assign a cache FS CACHE MAN 0 7 Assign a cache FS CACHE RW 0 7 Assign a cache FS CACHE RW OUOTA 1 0 Step 10 Checkdisk 33 Step 11 Get device info 0 1 Step 12 Get the size of a file 0 1 The static RAM reguirement of the file system without any driver is around 2 5 Kbytes User s amp reference manual for uC FS 2004 2007 Micrium 9 2 Performance A benchmark is used to measure the speed of the software on available targets This benchmark is in no way complete but it gives an approximation of the length of time reguired for common operations on various targets 9 2 1 Configuration and performance table All values are in Kbytes sec System Medium wo W1 R ARM 7 50 MHz
81. 15 81 CHDIS RESET IOCS16 WP WAIT IORDY STSCHG PDIAG SPKR DASP 353 CFGND INPK 26 VS2 CD2 VS1 CSEL A CE1 CSO VCC 13 CE2 CS1 VCC OE ATASEL IORD 1 10u 6 3V IOWR GND WE GND INTRO IREO REG CFGND User s amp reference manual for uC FS Device drivers 2004 2007 Micrium 231 5 5 2 Theory of operation 5 5 2 1 CompactFlash CompactFlash is a mechanically small removable mass storage device The Com pactFlash Storage Card contains a single chip controller and flash memory module s in a matchbox sized package with a 50 pin connector consisting of two rows of 25 female contacts each on 50 mil 1 27 mm centers The controller interfaces with a host system allowing data to be written to and read from the flash memory mod ule s Host Interface Controller L Compact Flash Card Figure 5 1 CompactFlash schematic There are two different Compact Flash Types namely CF Type I and CF Type II The only difference between CF Type I and CF Type II cards is the card thickness CF Type I is 3 3 mm thick and CF Type II cards are 5mm thick A CF Type I card will operate in a CF Type I or CF Type II slot A CF Type II card will only fit in a CF Type II slot The electrical interfaces are identical CompactFlash is available in both CF Type I and CF Type II cards though predominantly in CF Type I cards The Micro drive is a CF Type II card Most CF I O cards are CF Type I but there are some CF Type
82. 18 1 CF Card the memory mapped port address regis 9 20 7 ters within the CompactFlash Storage Card or CF Card a byte in the card s information structure and its configuration control and status registers This signal is asserted high as BVD1 is not sup BVD1 I O 46 ported BVD2 1 0 45 This signal is asserted high as BVD2 is not sup ported These Card Detect pins are connected to ground on da the CompactFlash Storage Card or CF Card They CD1 CD2 O 26 25 are used by the host to determine that the Com pactFlash Storage Card or CF Card is fully inserted into its socket These input signals are used both to select the card pe and to indicate to the card whether a byte or a word CE1 CE2 I 7 32 operation is being performed CE2 always accesses the odd byte of the word We recommend connect ing these pins together This signal is not used for this mode but should be Caci oe grounded by the host 27 31 These lines carry the Data Commands and Status D15 D00 I O 47 49 information between the host and the controller 2 6 D00 is the LSB of the Even Byte of the Word D08 is 21 23 the LSB of the Odd Byte of the Word GND 15 Ground INPACK O 43 This signal is not used in this mode IORD I 34 This signal is not used in this mode IOWR I 35 This signal is not used in this mode This is an Output Enable strobe generated by the OE ATA host interface It is used to read data from the SEL I 9 CompactFlash Storag
83. 2 DD12 DD1 15 16 DD14 DD2 13 14 DD13 DDO 17 18 DD15 ope te BPO G d 20 k DDO 17 18 DD15 roun 19 ey no pin Ground 19 20 key no pin DMARQ 21 22 Ground DMARQ 21 22 Ground DIOWD 23 24 Ground DIOW 23 24 Ground DIORD 25 26 Ground BOF LES 20 Ground IORDY 27 28 SPSYNC CSEL us DMACK 29 30 Ground DMACKED 29 30 Ground INTRO 31 32 10CS16 INTRQ 31 32 IOCS16D DA1 33 34 PDIAG DA1 33 34 PDIAGD DAO 35 36 DA2 DAO 35 36 DA2 CS1FX 37 38 CS3FX DASP 39 40 Ground CS1FXD 37 38 CS3FXD 5V logic 41 42 5V motor DASPD 39 40 Ground Ground 43 44 Type 5 5 3 Fail safe operation Unexpected Reset The data will be preserved Power failure Power failure can be critical If the card does not have sufficient time to complete a write operation data may be lost Countermeasures make sure the power supply for the card drops slowly 5 5 4 Wear leveling CompactFlash card are controlled by an internal controller this controller also han dles wear leveling Therefore the driver does not need to handle wear leveling 5 5 5 Configuring the driver 5 5 5 1 Adding the driver to pC FS To add the driver use FS AddDevice with the driver label FS IDE Driver This function has to be called from within FS X AddDevices Refer to FS X AddDevices on page 262 for more information User s amp reference manual for uC FS 2004 2007 Mi
84. 225 2004 2006 Micrium Table 5 72 Table 5 73 Table 5 74 Table 5 75 Table 5 76 Table 5 77 Table 5 78 Table 5 79 Table 5 80 Table 5 81 Table 5 82 Table 5 83 Table 5 84 Table 5 85 Table 5 86 Table 5 87 Table 5 88 Table 5 89 Table 5 90 Table 5 91 Table 5 92 Table 5 93 Table 6 1 Table 6 2 Table 6 3 Table 6 4 Table 6 5 Table 6 6 Table 6 7 Table 7 1 Table 7 2 Table 7 3 Table 8 1 Table 8 2 Table 8 3 Table 9 1 Table 9 2 Table 10 1 297 Table 10 2 Pin functions in memory card mode 228 Pin functions in memory card mode 233 FS IDE Configure parameter list 238 CompactFlash IDE device driver functions 239 FS IDE HW Reset parameter list 240 FS IDE HW Delay400ns parameter list 241 FS IDE HW IsPresent parameter list 242 FS IDE HW ReadReg parameter list 243 FS IDE HW WriteReg parameter list 244 FS IDE HW ReadData parameter list 245 FS IDE HW WriteData parameter list 246 List of supported serial NOR flashes 249 List of supported serial NOR flashes 249 FS NOR Configure parameter list 253 FS NOR SetPhyType parameter list 254 FS NOR GetDiskInfo parameter list
85. 3V TER an I CFWRL 36 50 WE GND CFRDY 37 32 INTRO_IREQ C CND CFVCCH REG User s amp reference manual for uC FS 2004 2007 Micrium 236 CHAPTER 5 Device drivers 5 5 2 2 IDE ATA Drives Just like Compact Flash cards ATA drives have a built in controller to drive and con trol the mechanical hardware in a drive Actually there are two types of connecting ATA drives 5 25 and 3 5 inch drives are using a 40 pin male interface to connect to an IDE controller 2 5 and 1 8 inch drives mostly used in Notebooks and embedded systems have a 50 pin male interface Modes of operation interface modes ATA drives can operate in a variety of different modes e PIO Programmed I O e Multiword DMA e Ultra DMA Supported modes of operation interface modes Currently only PIO mode through TRUE IDE is supported ATA drives True IDE mode pin functions Refer to True IDE mode pin functions on page 225 for information User s amp reference manual for uC FS 2004 2007 Micrium ATA drives Hardware interfaces 237 Signal Pin Pin Signal Signal use Pin Pin Signal use RESETD 1 2 Ground master slave jumper A B master slave jumper master slave jumper C D master slave jumper DD7 3 4 DD8 TODI npin DD6 5 6 DD9 RESET 1 2 Ground DD5 7 8 DD10 DD7 3 4 DD8 DD4 9 10 DD11 opal Le DD9 DD3 12 DD12 zed bi ea 11 DD4 9 10 DD11 DD2 13 14 DD13 DD3 11 1
86. 512 gt First byte of spare area OffSpare 513 gt Second byte of spare area Page size 2048 OffSpare 2048 gt First byte of spare area OffSpare 2049 gt Second byte of spare area NumBytesSpare Number of spare bytes to read Table 5 15 pfReadEx parameter list Return value 0 Data successfully transferred I 0 An error ha User s amp reference manual for s occurred uC FS 2004 2007 Micrium 164 CHAPTER 5 Device drivers 5 3 6 6 pfWrite Description Writes data into a complete or a part of a page This code is identical for main mem ory and spare area the spare area is located rigth after the main area Prototype int pfWrite U8 Unit U32 PageIndex const void pData unsigned Off unsigned NumBytes Parameter Meaning Unit Unit number 0 N PageIndex Zero based index of page to be written pData Pointer to a buffer of data which should be written OEE Byte offset within the page which needs to be smaller than the page size NumBytes Number of bytes which should be written Table 5 16 pfWrite parameter list Return value 0 Data successfully transferred I 0 An error has occurred User s amp reference manual for uC FS 2004 2007 Micrium 165 5 3 6 7 pfWriteEx Description Writes data to 2 parts of a page Typically used to write both the data and spare area of a page in one step
87. 54 Table 4 17 FS Tell parameter list cccceccceeseeeeeseeeeenaees 55 Table 4 18 FS_GetFilePos parameter list 56 Table 4 19 FS_SetFilePos parameter list 57 Table 4 20 FS CopyFile parameter list 0 58 Table 4 21 FS_GetFileAttributes parameter list 59 Table 4 22 FS GetFileAttributes list of possible attributes 59 Table 4 23 FS_GetFileTime parameter list 60 Table 4 24 FS_GetFileTime timestamp format description 60 Table 4 25 FS_GetFileTimeEx parameter list 61 Table 4 26 FS_GetFileTime timestamp format description 61 Table 4 27 FS Move parameter list 2 62 Table 4 28 FS_Remove parameter list 63 Table 4 29 FS_Rename parameter list 64 Table 4 30 FS_SetFileAttributes parameter list 65 Table 4 31 FS_SetFileTime parameter list 66 Table 4 32 FS_SetFileTime timestamp format description 66 Table 4 33 FS_SetFileTimeEx parameter list 67 Table 4 34 FS_GetFileTime timestamp format description 67 Table 4 35 FS_SetEndOfFile parameter list 68 User s A reference manual for uC FS 2004 2006 Micrium Table 4 36 Table 4 37 Table 4 38 Table 4 39 Table 4 40 Tabl
88. AM disk ps FS Alloc RAMDISK NUM SECTORS RAMDISK BYTES PER SECTOR 1 Add driver A EE ene ee eee 7 Configure driver TEA pRamDisk RAMDISK BYTES PER SECTOR RAMDISK NUM SECTORS User s amp reference manual for uC FS 2004 2007 Micrium 146 CHAPTER 5 Device drivers 5 2 6 Hardware functions The RAM disk driver does not need any hardware function 5 2 7 Addition information 5 2 7 1 Formatting A RAM disk is unformatted after each startup Exceptions from this rule are RAM disks which are memory backed up with a battery You have to format every unformatted RAM disk with the FS Format function before you can store data on it If you use only one RAM disk in your application FS FORMAT can be called with an empty string as device name For example FS Format NULL If you use more then one RAM disk you have to specify the device name For exam ple FS FORMAT ram 0 NULL for the first device and FS FORMAT ram 1 NULL for the second Refer to FS_Format on page 84 for more detailed infor mation about the high level format function of uC FS User s amp reference manual for uC FS 2004 2007 Micrium 147 5 3 NAND flash driver uC FS supports the use of NAND flashes An optional driver for NAND flashes is avail able The NAND driver reguires very little RAM it can work with sector sizes of 512 bytes or 2 Kbytes small sectors even on large page NAND flashes and is extrem
89. Bytes unsigned NumItems volatile U16 plIdeReg U16 pDatal6 pideReg _Getp AddrOf NumItems NumBytes gt gt 1 pDatal6 U16 pData do pDatal6 pIdeReg while NumItems User s amp reference manual for uC FS 2004 2007 Micrium 246 CHAPTER 5 5 5 6 7 FS_IDE_HW_WriteData Description Writes data to the IDE data register Device drivers Prototype void FS IDE HW WriteData U8 Unit U16 Data unsigned NumBytes Parameter Meaning Unit Unit number 0 N pData Pointer to a buffer of data which should be written NumBytes Number of bytes that should be read Table 5 82 FS IDE HW WriteData parameter list Example void FS ID unsigned volatile U16 pIdeReg NumItems pDatal6 do pIdeR while User s amp reference m NumItems U16 pIdeReg pDatal6 _Getp AddrOff NumBytes gt gt 1 U16 pData eg pDatal6 NumItems anual for yC FS E HW WriteData U8 Unit const U8 pData unsigned NumBytes 2004 2007 Micrium 247 5 5 7 Additional information The uC FS s generic CompactFlash amp IDE device driver can be used to access most ATA HD drives or CompactFlash storage cards also known as CF using true IDE or Memory card mode For details on CompactFlash cards check the specification which is available at http www compactflash org Information about the AT Attach
90. C HW X SetVoltage parameter list 199 FS MMC HW X IsWriteProtected parameter list 200 FS MMC HW X IsPresent parameter list 201 FS MMC HW X IsPresent list of return values 201 FS MMC HW X Read parameter list 202 FS MMC HW X Write parameter list 203 Card mode hardware functions lt lt lt 205 FS MMC HW X SetMaxSpeed parameter list 206 FS MMC HW X Set ResponseTimeOut parameter list 207 FS MMC HW X SetReadDataTimeOut parameter list 208 FS MMC HW X SetHWBlockLen parameter list 209 FS MMC HW X SetHWNumBlocks parameter list 210 FS MMC HW X IsWriteProtected parameter list 211 FS MMC HW X IsPresent parameter list 212 FS MMC HW X IsPresent list of return values 212 FS MMC HW X GetResponse parameter list 213 FS MMC HW X GetResponsef list of return values 213 FS MMC HW X ReadData parameter list 214 FS MMC HW X ReadData list of return values 214 FS MMC HW X SendCmd parameter list 215 FS MMC HW X SendCmaf list of possible commands FS MMC HW X SendCmd list of possible responses 216 FS MMC HW X WriteData parameter list 217 FS MMC HW X WriteData list of return values 217 FS MMC HW X Delay parameter list 218 Screenshot descriptionS lt lt c lt c 220 True IDE pin functions zoadestizazodva naky lad zekka ka
91. Cache parameter list es 115 FS CACHE Clean parameter list 117 2004 2006 Micrium Table 4 81 Table 4 82 Table 4 83 Table 4 84 Table 4 85 Table 4 86 Table 4 87 Table 4 88 Table 4 89 Table 4 90 Table 4 91 Table 4 92 Table 4 93 Table 4 94 Table 4 95 Table 4 96 Table 4 97 Table 4 98 Table 4 99 Table 4 100 Table 4 101 Table 4 102 Table 5 1 Table 5 2 Table 5 3 Table 5 4 Table 5 5 Table 5 6 Table 5 7 Table 5 8 Table 5 9 Table 5 10 Table 5 11 Table 5 12 Table 5 13 Table 5 14 Table 5 15 Table 5 16 Table 5 17 Table 5 18 Table 5 19 Table 5 20 Table 5 21 Table 5 22 Table 5 23 Table 5 24 Table 5 25 User s amp reference manual for uC FS FS CACHE SetMode parameter list FS CACHE SetOuota parameter list FS ClearErr parameter list FS FEof parameter list ccccceceesceeeeeseeeseeees FS FError parameter list FS FError list of error code values FS ErrorNo2Text parameter list FS CloseDir parameter list FS DirEnt2Attr parameter list FS DirEnt2Attr list of possible attributes FS DirEnt2Name parameter list FS DirEnt2Size parameter list FS DirEnt2Time parameter list FS DirEnt2Time timestamp format description FS GetDevicelnfo parameter list FS GetNumrFiles parameter list FS OpenDir parameter list FS ReadD
92. Compiler Assembler Custom Build Build Actions Linker Debugger Simulator PROJ_DIR Config Angel PROJ_DIR FS IAR ROM monitor J Link J Trace LMI FTDI Macraigor RDI Third Party Driver Figure 3 3 Configure the include path Select the start application For quick and easy testing of your uC FS integration start with the code found in the folder Application Exclude all files in the Application folder of your project except the supplied main c and Start c The application performs the following steps 1 main c calls MainTask 2 MainTask initializes and adds a device to uC FS 3 checks if volume is low level formatted and formats if required 4 checks if volume is high level formatted and formats if required 5 outputs the volume name 6 calls FS_GetFreeVolumeSpace and outputs the return value the available total space of the RAM disk to console window 7 creates and opens a file test with write access File txt on the device 8 writes 4 bytes into the file and closes the file handle or outputs an error mes sage 9 calls FS_GetFreeVolumeSpace and outputs the return value the available free space of the RAM disk again to console window 10 outputs an quit message and runs into an endless loop Build the project and test it Build the project It should compile without errors and warnings If you encounter any problem during the build process check your include path and your
93. D device added Example Refer to Adding the driver to uC FS on page 155 for an example FS NAND SetBlockRangef Description Sets a limit for which blocks of the NAND flash can be controlled by the driver Prototype void FS NAND SetBlockRange U8 Unit U16 FirstBlock U16 MaxNumBlocks Parameter Meaning Unit Unit number 0 N Zero based index of the first block to use FirstBlock Specifies the number of blocks at the beginning of the device to skip 0 means that no blocks are skipped Maximum number of blocks to use 0 means use all blocks after FirstBlock Table 5 9 FS NAND SetBlockRange parameter list MaxNumBlocks Additional information This function is optional By default the driver controls all blocks of the NAND flash making the entire NAND flash available If a part of the NAND flash should be used for another purpose for example to store the application program used by a boot loader and therefore is not controlled by the driver this function can be used Limit ing the number of blocks used by the driver also reduces the amount of memory used by the driver Example Refer to Adding the driver to uC FS on page 155 for an example User s amp reference manual for uC FS 2004 2007 Micrium 157 5 3 6 Hardware functions Physical layer functions There is normally no need to change the physical layer of the NAND driver only the hardware layer has to be
94. DE HW Delay400ns 241 FS IDE HW IsPresent 242 FS IDE HW Reset 240 Include files 25 Initializing the file system 10 Introduction to uC FS 7 12 L Layer API Layer 9 Device Driver 10 File System Layer 9 Hardware Layer 10 Storage Layer 10 M Microsoft compiler 15 Miscellaneous configurations 275 MMC 188 MMC card mode pin description 189 MMC CardMode HW FS MMC HW X Delay 218 FS MMC HW X GetResponse 213 FS MMC HW X IsPresent 212 FS MMC HW X IsWriteProtected 211 FS MMC HW X ReadData 214 FS MMC HW X SendCma 215 FS MMC HW X SetHWBlockLen 209 FS MMC HW X SetHWNumBlocks 210 FS MMC HW X SetMaxSpeed 206 FS MMC HW X SetReadDataTimeOut 208 FS MMC HW X SetResponseTimeOut 207 FS MMC HW X WriteData 217 MMC SPI HW FS MMC HW X DisableCS 197 FS MMC HW X EnableCS 193 194 196 FS MMC HW X IsPresent 201 FS MMC HW X IsWriteProtected 200 FS MMC HW X Read 202 FS MMC HW X SetMaxSpeed 198 FS MMC HW X SetVoltage 199 FS MMC HW X Write 203 MMC SPI mode pin description 190 Multimedia amp SD card device driver 188 MultiMedia Card 188 2004 2007 Micrium N NAND flash driver NAND flash device driver 147 Pin description 150 Supported hardware 148 NAND HW FS NAND HW X DisableCE 170 NOR flash driver 248 Configuration 253 Supported hardware 248 o Obsolete functions FS CloseDir 126 FS DirEnt2Attr 127 FS DirEnt2Namef 128 FS DirEnt2Size 129 FS DirEnt2Time 130 FS GetNumFiles 132 FS OpenDir 134 FS ReadDir 135 FS Re
95. Dir pBuffer Pointer to the buffer that will receive the text Table 4 91 FS_DirEnt2Name parameter list Additional Information If pDirEnt and pBuffer are valid the name of the directory is copied to the buffer that pBuffer points to Otherwise pBuffer S NULL pDirEnt should point to a valid FS_DIRENT structure FS_DirEnt2Name checks if the pointers are valid To get a valid pointer FS_ReadDir should be called before using FS_DirEnt2Name otherwise pBuffer iS NULL Refer to FS_ReadDir on page 135 for more information Example void MainTask void char acDirName 20 FS_DIR pDir FS_DIRENT pDirEnt pDir FS_OpenDir Open root directory of default device pDirEnt FS_ReadDir pDir Read the first directory entry FS_DirEnt2Name pDirEnt acDirName FS_X_Log acDirName User s amp reference manual for uC FS 2004 2007 Micrium 129 4 14 4 FS DirEnt2Size Description Returns the size in bytes of the directory entry referred to pDirEnt Prototype U32 FS DirEnt2Size FS DIRENT pDirEnt Parameter Description pDirEnt Pointer to a directory entry read by FS ReadDir Table 4 92 FS DirEnt2Size parameter list Return value File size in bytes O in case of any error Additional Information If pDirEnt is valid the size of the directory entry will be returned
96. DirPathList Filename e DevName is the name of a device If not specified the first device in the volume table will be used UnitNum is the number of the unit for this device If not specified unit O will be used Note that it is not allowed to specify UnitNum if DevName has not been spec ified e DirPathList means a complete path to an already existing subdirectory FS_FOpen does not create directories The path must start and end with a character Directory names in the path are separated by If DirPathList is not specified the root directory on the device will be used e FileName desired If FAT is used and long file name support is not enabled all file names and all directory names have to follow the standard FAT naming conventions for exam ple 8 3 notation EFS supports long file names The name length of a file or directory is limited to 235 valid characters The parameter pMode points to a string If the string is one of the following uC FS will open the file in the specified mode Permitted values for parameter pMode r Opens text file for reading w Truncates to zero length or creates text file for writing a Appends opens creates text file for writing at end of file rb Opens binary file for reading EA Truncates to zero length or creates binary file for writing User s amp reference manual for yC FS 2004 2007 Micrium 49 Permitted values for p
97. EES EEE ES 126 6 B ee ER R O O O O een Deven eda LEE As 141 6 1 General information lt lt lt srrr0 10000 KK KK K K K KKK KK KKK 142 6 RAM disk drivers s same saka sd em queen rade nat barak dina ste 143 6 3 NAND flash driver id l do Monnaies E A KR AKA vk 147 6 4 MultiMedia amp SD card driver sis K K K P K 188 6 5 CompactFlash card amp IDE driver 0000 o K n ennes 224 6 6 NOR PASM drive zz dt nann Peds data ta ada IA E ae AE uno KK EAE Koi UNIS r SR S atai 248 6 7 WinDriVe driVer sean a boa ote plno ove nana antenne die P ono l 261 User s amp reference manual for uCFSFS 2004 2006 Micrium 6 8 Writing YOUr OWN driver sais sursnresssasnmamenenmennesearentenmantap nasaneadenme i anne 263 7 SCIPS Configuration ans ie ne ne nn en tien nn Hib e niga niente 267 7 1 Runtime CONfIGUIAtION kr dpi den epi ene deg an a me an eed 268 7 2 Compile time configuration sisi 271 8 OS MOC AO EHESS nt cea lactate telah i enr ne ots 277 8 1 OS layer APT fUNCHONS 54s upe da abys ed ads Roka d dscns eae bere pada 278 8 2 Sample onfiguration zeste n k n ara VA Koa k as ntm BVK alk ae 279 9 1D bUGOINg tent mumetianmanunt tienne TEAS 283 9 1 FSX LOG 0 Si arean aan e son ov D weve erase ens 284 9 2 FS X Warn O A es iv ada nA E AV A VESA V AAA ds vE A 285 9 3 FSX Eroro uU zed noas kasta soba v na KPE O EOL nit ran Kak aso k aaa es ARTEA 286 9 4 Troubleshooting ze ieee ory Pud plo da da lud
98. ES NANDAK MAR NUM EEY FS NAND SetBlockRange Refer to BSP NS FS NAND SetBlockRange on page 156 for detailed information Table 10 7 Differences between uC FS v 2 x v 3 x removed NAND driver macros Hardware interface version 2 x Hardware interface version 3 x FS NAND2K HW X SetAddr FS NAND HW X SetAddrMode FS NAND2K HW X SetCmd FS NAND HW X SetCmdMode FS NAND2K HW X SetData FS NAND HW X SetDataMode FS NAND2K HW X SetStandby FS NAND HW X SetStandby FS NAND2K HW X WaitWhileBusy FS NAND HW X WaitWhileBusy FS NAND2K HW X IsWriteProtected FS NAND HW X IsWriteProtected FS NAND2K HW X Read FS NAND HW X Read FS NAND2K HW X Write FS NAND HW X Write FS NAND2k HW X Delayus FS NAND HW X Delayus FS NAND2K HW X Init FS NAND HW X Init gt FS NAND HW X DisableCE FS NAND HW X EnableCE Table 10 8 Differences between uC FS v 2 x v 3 x IDE driver hardware interface differences Refer to the section NAND flash driver on page 147 for detailed information about the NAND driver in uC FS version 3 x User s amp reference manual for uC FS 2004 2007 Micrium 301 10 4 5 NAND driver differences In version 3 x removed mac
99. Error Description Returns the current error status of a file Prototype 116 FS_FError FS_FILE pFile Parameter Description pFile Pointer to a data structure of type FS_FILE Table 4 85 FS_FError parameter list Return value FS_ERR_OK if no errors A value not equal to FS_ERR_OK if a file operation caused an error Additional Information The return value is not FS_ERR_OK only when a file operation caused an error and the error was not cleared by calling FS_ClearErr or any other operation that clears the previous error status The following error codes are available Code Description FS_ERR_OK No error FS_ERR_EOF End of file has been reached Unable to write data because there is no more space on the FS_ERR_DISKFULL media FS_ERR_INVALIDPAR An uC FS function has been called with an illegal parameter A read operation has been made on a file open for writing FS_ERR_WRITEONLY only i A write operation has been made on a file open for reading FS ERR READONLY only FS ERR READERROR An error occurred during a read operation FS ERR WRITEERROR An error occurred during a write operation FS ERR DISKCHANGED Media has been changed although the file was still open FS ERR CLOSE An error occurred during the close operation Table 4 86 FS FError list of error code values Example
100. FS In a target system they are typ ically not required in a release production build since a production build typically uses a lower debug level Fatal errors are output using FS x 1 Warnings are output using FS X Warn Messages are output using FS X Log 275 ErrorOut if FS DEBUG LEVEL gt 3 if FS DEBUG LEVEL gt 4 FS DEBUG LEVEL gt 5 The file system calls this function depending on the configuration macro FS DEBUG LEV EL The following table lists the permitted values for FS DEBUG LEVEL Value Symbolic name Explanation 0 FS DEBUG LEVEL NOCHECK No run time checks are performed m Parameter checks are performed to avoid 1 FS DEBUG LEVEL CHECK PARA crashes Default for target system Parameter checks an nsisten hecks 2 FS DEBUG LEVEL CHECK ALL Bra Mele hoc and Consistency ches are per formed 3 FS_DEBUG_LEVEL_LOG_ERRORS Errors are recorded Errors and warnings are 4 FS_DEBUG_LEVEL_LOG_WARNINGS Ed recorded Default for PC simulation Errors warnin nd m r 5 m ors wa gs and messages are recorded Table 6 6 Debug level macros 6 2 6 Miscellaneous configurations Type Macro Default Description Setting this macro to 1 uC FS B Se NO CETE does not use the standard C library functions such
101. FS USE PARA Unit _Timer2Config _NANDFlashInit User s amp reference manual for uC FS 2004 2007 Micrium 179 5 3 7 13 FS NAND HW X Init x16 Description Initializes a NAND flash device with a 16 bit interface Prototype void FS NAND HW X Init x16 U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 31 FS NAND HW X Init x16 parameter list Additional Information This function is called before any access to the NAND flash device is made Use this function to initialize the hardware User s amp reference manual for uC FS 2004 2007 Micrium 180 CHAPTER 5 Device drivers 5 3 8 Hardware functions ATMEL DataFlash Routine Explanation Control line functions FS DP UW xX mnablecS Activates chip select signal CS of the DataFlash chip FS DF HW X Disablecs Deactivates chip select signal CS of the DataFlash chip FS DF HW X Init Initializes the SPI hardware Data transfer functions PS DF HW X Read Receives a number of bytes from the DataFlash FS DF HW X Write Sends a number of bytes to the card Table 5 32 DataFlash device driver hardware functions User s amp reference manual for uC FS 2004 2007 Micrium 181 5 3 8 1 FS DF HW X EnableCS Description Activates chip select signal CS of the specified DataFlash Prototype void FS DF HW X EnableCS U8 Unit Para
102. FS_FormatLow parameter list Return value 0 Low level format successful 0 In case of any error Additional Information Low level format is only reguired for devices which have their own management level These are the drivers for NOR flashes NAND flashes and SMC cards MMC SD and all other cards do not reguire a low level format User s amp reference manual for uC FS 2004 2007 Micrium 83 4 8 5 FS Format Description Performs a high level format of a device This means putting the management infor mation required by the File system on the medium In case of FAT this means prima rily initialization of FAT and the root directory as well as the BIOS parameter block Prototype int FS Format const char pDeviceName FS FORMAT INFO pFormatInfo Parameter Description pVolumeName Name of the device to format pFormatInfo Optional info for formatting Table 4 48 FS Format parameter list Return value 0 High level format successful 0 In case of any error Additional Information There are many different ways to format a medium even with one file system If the second parameter is not specified reasonable default values are used auto format However FS Format also allows fine tuning of the parameters used For details refer to the sample file Format c which is shipped with uC FS For more information about the structure FS FORMAT
103. FreeSpace parameter list 88 FS GetTotalSpace parameter list 90 FS GetVolumeFreeSpace parameter list 91 FS GetVolumelInfo parameter list 92 FS GetVolumeLabel parameter list 93 FS GetVolumeNamef parameter list 94 FS GetVolumeSize parameter list 95 FS GetVolumeStatus parameter list 96 FS GetVolumeStatus list of return values 96 FS IsVolumeMounted parameter list 97 FS TimeStampToFileTime parameter list 98 FS TimeStampToFileTime timestamp format description FS FILETIME list of structure member variables 99 FS SetBusyLEDCallback parameter list 100 FS GetVolumelInfo parameter list 101 FS STORAGE GetDeviceInfo parameter list 102 FS STORAGE ReadSector parameter list 104 FS STORAGE ReadSectors parameter list 105 FS STORAGE Sync parameter list 106 FS STORAGE Unmount parameter list 107 FS STORAGE WriteSector parameter list 108 FS STORAGE WriteSectors parameter list 109 FS FAT CheckDisk parameter list 110 FS FAT CheckDisk ErrCode2Text parameter list 112 FS FAT CheckDisk ErrCode2Text list of error code values FS FormatSD parameter list 113 FS Assign
104. I differences 297 Function Description Changed functions FS GetFreeSpace Number of parameters reduced Parameter DevIndex removed FS GetTotalSpace Number of parameters reduced Parameter DevIndex removed Remo ved functions FS Exit Should be removed from your application FS CheckMediumPresent source code Obsolete directory handling functions FS CloseDir FS DirEnt2Attr FS DirEnt2Name The directory handling has been changed in FS uC FS version 3 x The functions should be FS _DirEnt2Time replaced Refer to FS_FindClose on _DirEnt2Size FS_GetNumFiles page 73 for an example of the new way of FS OpenDir directory handling FS ReadDir FS RewindDir Obsolete file sys tem extended functions FS IoCtl version 3 x Use FS IsLLFormatted to check if a low level format is reguired and FS GetDeviceInfo to get the device FS IoCt1 should not be used in uC FS information Table 10 1 Differences between uC FS v 2 x v 3 x API differences In uC FS version 3 is the header file FS Api h renamed to FS h therefore change the name of the file system header file in your application User s amp reference manual for uC FS 2004 2007 Micrium 298 CHAPTER 10 Porting uC FS 2 x to 3 x 10 3 Configuration diff
105. L i pointer FS ErrorNo2Text Retrieves text for a given error code Obsol ete functions WS Closebir Closes a directory stream FS DirEnt2Attr Gets the directory entry attributes FS DirEnt2Name Gets the directory entry name FS DirEnt2Size Gets the directory entry file size FS DirEnt2Time Gets the directory entry timestamp WS GetDeviceints Returns the device info FS GetNumFiles Gets the number of files in a directory o FS InitStorage Initializes the driver and OS if necessary FS OpenDir Opens a directory stream FS ReadDir Reads next directory entry FS ReadSector Reads a sector from a device FS RewindDir Resets position of directory stream FS WriteSector Writes a sector to a device FS UnmountLL Low level unmount Unmounts a volume on driver layer Table 4 1 pC FS API function overview Continued User s amp reference manual for uC FS 2004 2007 Micrium 37 4 2 File system control functions 42 1 FS Init Description Starts the file system Prototype void FS Init void Additional Information FS Init initializes the file system and creates resources reguired for an OS inte gration of uC FS This function must be called before any other uC FS function Example include FS h void main void FS_Init Access file syst
106. M disk instance This function has to be called from within FS X AddDevices after adding an instance of the RAMDisk driver Refer to FS_X_AddDevices on page 262 for more information Prototype void FS RAMDISK Configure U8 Unit void pData U16 BytesPerSector U32 NumSectors Parameter Description Unit Unit number 0 N pData Pointer to a data buffer BytesPerSector Number of bytes per sector NumSectors Number of sectors Table 5 2 FS RAMDISK Configure parameter list Additional information The size of the disk is defined as the number of sectors reserved for the drive Each sector consists of 512 bytes The minimum value for NumSectors is 7 BytesPerSec tor defines the size of each sector on the RAM disk A FAT file system needs a mini mum sector size of 512 bytes User s amp reference manual for uC FS 2004 2007 Micrium 145 Example A kkkkkk kkk kkk kkk khkk kk kkk kkk kkk kk kk khkk kkk kk kkk kk kkk kk kkk k k k k kk kk kk k je FS X AddDevices Ae Function description This function is called by the FS during FS Init It is supposed to add all devices using primarily FS AddDevice Note 1 Other API functions Other API functions may NOT be called since this function is called during initialisation The devices are not yet ready at this point EJ void FS_X_AddDevices void void pRamDisk n Allocate memory for the R
107. MAX SECTOR SIZE 512 endif Avoid multiple inclusion User s amp reference manual for uC FS 2004 2007 Micrium 277 Chapter 7 OS Integration uC FS is suitable for any multithreaded environment To ensure that different tasks can access the file system concurrently you need to implement a few operating sys tem dependent functions For uC OS II and MS Windows you will find implementations of these functions in the file system s source code This chapter provides descriptions of the functions required to fully support uC FS in multithreaded environments If you do not use an OS or if you do not make file access from different tasks you can implement these functions as empty routines You may also add date and time support functions for use by the FAT file system The sample implementations provided with uC FS use ANSI C standard functions to obtain the correct date and time User s amp reference manual for uC FS 2004 2007 Micrium 278 CHAPTER 7 OS Integration 7 4 OS layer API functions To use uC FS with an operating system set the define FS os to 1 in FS Conf h and implement the following functions Samples for the implementation of an operating system can be found in the directory Sample os Example User s amp reference manual for uC FS 2004 2007 Micrium 279 7 2 Sample configuration KKK KKK KK KKK KEK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KEK KK KKK KKK k kk k
108. MC HW X SetResponseTimeOut Sets the card host controller timeout nt ae value for receiving response from card D r em Sets the card host controller timeout oes value for receiving data from card a E E naka Sets the card host controller block size e value for a block Tells the card host controller how many FS_MMC_HW_X_SetHWNumBlocks block will be transferred to or received from card Medium status functions eee Checks the status of the mechanical write ee protection of a SD card FS_MMC_HW_X_IsPresent Checks whether a card is present or not Data transfer functions FS MMC HW X GetResponse Retrieves the response after sending a nee command to the card f Receives a number of bytes from the FS MMC HW X ReadData card Be d ee nc Sends and setups the controller to send a Soe specific command to card FS MMC HW X WriteData Writes a number of block to the card Time functions FS MMC HW X Delay Waits for a specific time in ms Table 5 51 Card mode hardware functions User s amp reference manual for uC FS 2004 2007 Micrium 206 CHAPTER 5 Device drivers 5 4 7 1 FS MMC HW X SetMaxSpeed Description Sets the maximum SD MMC clock speed If the hardware is unable to use this speed a lower fregency can always be selected The value is given in kHz Prototype U16 FS MMC HW X SetMaxSpeed U8 Unit U16 MaxFreg Parameter Meaning Unit Unit number 0 N MaxFreq Clock speed kHz betwee
109. MediaCard bus mas ter card host controller to the card and responses are sent from the cards to the host 3 Vss al SUP Supply voltage ground 4 Vpp ae SUP Supply voltage Clock signal With each cycle of this signal an one bit transfer on the 5 CLK Input command and data lines is done The frequency may vary between zero and the maximum clock frequency 6 Vss2 ual SUP Supply voltage ground Data line Bit 0 Input Out DAT is a bidirectional data channel The DAT signal 4 DATO put operates in push pull mode Only one card or the host using push lis driving this signal at a time pull drivers Relevant only for SD cards For data transfers this line is the Data line Bit O Data line Bit 1 Input Out On MMC card this line does not exist put Relevant only for SD cards For data transfer this line 8 DATI using push is the Data line Bit 1 Connect an external pull up pull drivers resistor to this data line even if only DATO is to be used Otherwise non expected high current consump tion may occur due to the floating inputs of DAT1 Data line Bit 2 Input Out On MMC card this line does not exist ut Relevant only for SD cards For data transfer this line 9 DAT2 ae push is the Data line Bit 2 Connect an external pull up pull drivers resistor to this data line even if only DATO is to be used Otherwise non expected high current consump tion may occur due to the floating inputs of DAT2 Table 5 38
110. Micrium Empowering Embedded Systems uC FS CPU independent File System for embedded applications Software version 3 10 User s Manual Rev 0 www micrium com Disclaimer Specifications written in this manual are believed to be accurate but are not guaran teed to be entirely free of error Specifications in this manual may be changed for functional or performance improvements without notice Please make sure your man ual is the latest edition While the information herein is assumed to be accurate Micrium assumes no responsibility for any errors or omissions and makes no warran ties Micrium specifically disclaims any implied warranty of fitness for a particular purpose Copyright notice You may not extract portions of this manual or modify the PDF file in any way without the prior written permission of Micrium The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license 2004 2007 Micrium Weston Florida 33327 1848 U S A Trademarks Names mentioned in this manual may be trademarks of their respective companies Brand and product names are trademarks or registered trademarks of their respec tive holders Registration Please register the software via email This way we can make sure you will receive updates or notifications of updates as soon as they become available For registration please provide the following information
111. S 2004 2007 Micrium 34 4 1 API function overview CHAPTER 4 API functions The table below lists the available API functions within their respective categories Function Description File system control functions FS Init Starts the file system Fo Mount Mounts a volume FS_SetAutoMount Sets the mount behavior of the specified volume FS_Unmount Closes all file directory handles and unmounts the volume FS UnmountForced Invalidates all file directory handles and unmounts the volume File system configuration functions FS AddDevice Adds and makes a device driver accessable to uC FS FS AddPhysDevice Adds a device driver physical to uC FS FS LOGVOL Create Creates a logical volume FS LOGVOL AddDevice Adds a device to a logical volume File access functions FS FClose Closes a file FS FOpen Opens a file FS FRead Reads data from a file FS Read Reads data from a file FS FWrite Writes data to a file FS Write Writes data to a file File positioning functions FS FSeek Sets position of a file pointer FS FTell Returns position of a file pointer FS GetFilePos Returns position of a file pointer FS SetFilePos Sets position of a file pointer Operations on files FS CopyFile Copies a file FS GetFileAttributes Retrieves the attrib
112. S NAND HW X DisableCE U8 Unit Device drivers Parameter Description Unit Unit number 0 N Table 5 22 FS_NAND_HW_X_DisableCE parameter list User s amp reference manual for yC FS 2004 2007 Micrium 171 5 3 7 5 FS NAND HW X EnableCE Description Enables NAND CE Prototype void FS NAND HW X EnableCE U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 23 FS NAND HW X EnableCE parameter list Example EER k kkk kk k k RR EEE ER k k k k k k k k ERE RK KEK k k k k ER k k k KERR KR k k k k k k k k k k k k k k KE k k FS NAND HW X EnableCE void FS NAND HW X EnableCE U8 Unit PIOB CODR 1 lt lt 18 Enable NAND CE User s amp reference manual for uC FS 2004 2007 Micrium 172 CHAPTER 5 Device drivers 5 3 7 6 FS NAND HW X WaitWhileBusy Description Checks whether the device is busy Prototype int FS NAND HW X WaitWhileBusy U8 Unit unsigned us Parameter Meaning Unit Unit number 0 N us Time in us to Wait Table 5 24 FS NAND HW X WaitWhileBusy parameter list Return value 0 if the device is not busy Any other value means that an operation is pending Additional Information If your hardware allows you to monitor the nR B line you can use the status of that line and return when the device is not busy Otherwise the function should return 1 In t
113. S signal is used to address a specific card slot connected to the SPI Enabling is egual to setting the CS line onto low level Example void FS MMC HW X EnableCS U8 Unit SPI CLR CS User s amp reference manual for uC FS 2004 2007 Micrium 197 5 4 6 2 FS MMC HW X DisableCS Description Deactivates chip select signal CS of the specified card slot Prototype void FS MMC HW X DisableCS U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 43 FS MMC HW X DisableCS parameter list Additional Information The CS signal is used to address a specific card slot connected to the SPI Disabling is equal to setting the CS line to high Example void FS MMC HW X DisableCS U8 Unit SPI SET CS User s amp reference manual for uC FS 2004 2007 Micrium 198 CHAPTER 5 Device drivers 5 4 6 3 FS MMC HW X SetMaxSpeed Description Sets the maximum SPI speed If the hardware is unable to use this speed a lower fregency can always be selected The value is given in kHz Prototype U16 FS MMC HW X SetMaxSpeed U8 Unit U16 MaxFreg Parameter Meaning Unit Unit number 0 N MaxFreq Clock speed kHz between host and card Table 5 44 FS MMC HW X SetMaxSpeed parameter list Return value Actual freguency in thousand cycles per second kHz 0 if the freguency could not be set Additional Information Make sure yo
114. STORAGE Init Description This function only intializes the driver and OS if necessary Prototype void FS STORAGE Init void Return value The return value is the number of drivers can be used at the same time These num ber of drivers is relevant for the high level initialzation function FS Init FS Init uses these information to allocate the sector buffers which are neccessary for a file system operation Additional information FS STORAGE Init initializes the storage layer of a driver If you use FS STORAGE Init instead of FS Init only the storage layer functions like FS STORAGE ReadSector Or FS STORAGE WriteSector are available This means that the file system can be used as a pure sector read write software This can be useful when using the file system as a USB mass storage client driver User s amp reference manual for uC FS 2004 2007 Micrium 104 CHAPTER 4 API functions 4 10 3 FS_STORAGE_ReadSector Description Reads a sector from a device Prototype int FS STORAGE ReadSector const char sVolume const void pData U32 SectorIndex Parameter Description Volume name If not specified the first device in the volume sVolume A table will be used pData Pointer to a buffer where the read data will be stored SectorIndex Index of the sector from which data should be read Table 4 69 FS STORAGE ReadSector parameter list Retu
115. T 512 16 32Mx8 TC582562AXB 512 16 32Mx8 TC58512FTXx 512 16 64Mx8 TH58100FT 512 16 256Mx8 Table 5 3 List of supported NAND flashes User s amp reference manual for UC FS 2004 2007 Micrium 149 Manufacturer Device Page size Bytes Size Bits HY27UF082G2M 2048 64 256Mx8 Hvni HY27UF084G2M 2048 64 512Mx8 a HY27UG084G2M 2048 64 512Mx8 HY27UG084GDM 2048 64 512Mx8 MT29F2G08A 2048 64 256Mx8 MT29F2G08B 2048 64 256Mx8 Micron MT29F4G08A 2048 64 512Mx8 MT29F4G08B 2048 64 512Mx8 MT29F2G16A 2048 64 128Mx16 K9F1G08x0A 2048 64 256Mx8 K9F2G08U0M 2048 64 256Mx8 Samsung K9K2G08R0A 2048 64 256Mx8 K9K2G08U0M 2048 64 256Mx8 K9F4G08U0M 2048 64 512Mx8 K9F8G08U0M 2048 64 1024Mx8 NAND01GR3B 2048 64 128Mx8 NAND01GW3B 2048 64 128Mx8 ST Microelectronics NAND02GR3B 2048 64 256Mx8 NANDO2GW3B 2048 64 256Mx8 NANDO4GW3 2048 64 512Mx8 Table 5 3 List of supported NAND flashes Support for devices not in this list Most other NAND flash devices are compatible with one of the supported devices Thus the driver can be used with these devices or may only need a little modifica tion which can be easily done Get in touch with us if you have guestions about sup port for devices not in this list 5 3 1 2 Tested and compatible DataFlash chips The NAND flash driver fully supports the ATMEL DataFlash DataFlash Cards series up to 32 MBit Currently the following devices are supported Manufacturer Device
116. T structure DirEnt2Name checks if should be called before FS I Dir Ent2Size Refer to FS_ReadDir on page 135 for more information A timestamp is a packed value with the following format Bits Description 0 4 Second divided by 2 5 10 Minute 0 59 11 15 Hour 0 23 16 20 Day of month 1 31 21 24 Month January gt 1 February gt 2 etc 25 31 Year offset from 1980 Add 1980 to get current year Table 4 94 FS_DirEnt2Time timestamp format description To convert a timestamp to a FS_FILETIME structure use the function FS_TimeStampToFileTime Example void MainTask void U32 TimeStamp FS_DIR pDir FS_DIRENT pDirEnt char acLog 100 char acFileName 40 FS_FILETIME FileTime pDir FS_OpenDir Open root directory of default device pDirEnt FS_ReadDir pDir Read the first directory entry FS_DirEnt2Name pDirEnt amp acFileName 0 TimeStamp FS_DirEnt2Time pDirEnt FS_TimeStampToFileTime amp TimeStamp amp FileTime sprintf ac File time of s d 2d 2d 2d 2d 2d acFileName FileTime Year FileTime Month FileTime Day FileTime Hour FileTime Minute FileTime Second FS X Log ac User s amp reference manual for uC FS 2004 2007 Micrium 4 14 6 FS GetDevicelnfo 131 Description Returns the device status Prototype int FS GetDev
117. TER 4 API functions 4 3 2 FS_AddPhysDevice Description Adds a device physical to uC FS This initialises the driver allowing the driver to identify the storage device as far as reguired and allocate memory reguired for driver level man agement of the device This makes sector operations possible Prototype int FS AddPhysDevice const FS DEVICE TYPE pDevType Parameter Description Pointer to device driver table See Device driver function table on page 258 for additional information Table 4 7 FS AddDevice parameter list pDevType Return value gt 0 Unit number of the device lt 0 An error has occured Additional Information Devices that are only physically added to uC FS can be combined to a logical volume Refer to FS LOGVOL Create on page 45 and FS_LOGVOL_AddDevice on page 46 for information about logical volumes User s amp reference manual for uC FS 2004 2007 Micrium 45 4 3 3 FS LOGVOL Create Description Creates a logical volume A logical volume is the representation of one or more phys ical devices as a single device It allows treating multiple physical devices as one larger device the file system takes care of selecting the correct location on the cor rect physical device when reading or writing to the logical volume Logical volumes are typically used if multiple flash devices NOR or NAND are present but should be presented to t
118. This file system reduces frag mentation of the data by utilizing drive space more efficiently while still offering faster access to embedded storage devices Another benefit of EFS is that there are no issues concerning long file name LFN support The FAT file system was not designed for long file name support limiting names to twelve characters 8 3 LFN support may be added to any of the FAT file systems but there are legal issues that must be settled with Microsoft before end applications make use of this feature Long file names are inherent to this proprietary file system relieving it of any legal issues 1 3 3 Initializing the file system The first thing that needs to be done after the system start up and before any file system function can be used is to call the function FS Init This routine initializes the internals of the filesystem However it does not perform any low level or device driver specific initialization User s amp reference manual for uC FS 2004 2007 Micrium 1 3 4 Add your device After initializing the file system you have to add your target device to the file sys tem The function FS AddDevice adds and initializes the device User s amp reference manual for uC FS 2004 2007 Micrium 12 CHAPTER 1 Introduction to yC FS 1 4 Development environment compiler The CPU used is of no importance only an ANSI compliant C compiler complying with at least one of the following international standard
119. Volume does not require a low level format or in case of any error Additional Information Low level format is only reguired for devices which have their own management level These are the drivers for NOR flashes NAND flashes MMC SD and all other cards do not reguire a low level format User s amp reference manual for uC FS 2004 2007 Micrium 81 4 8 3 FS_FormatLLifRequired Description Checks if the volume is low level formatted and formats the volume if reguired Prototype int FS FormatLLIfReguired const char pVolumeName Parameter Description pVolumeName Name of the device to low level format Table 4 46 FS FormatLLIfReguired parameter list Return value 0 Ok low level format successful 1 Low level format not required 1 Volume does not require a low level format or in case of any error Additional Information Low level format is only required for devices which have their own management level These are the drivers for NOR flashes NAND flashes MMC SD and all other cards do not require a low level format User s amp reference manual for uC FS 2004 2007 Micrium 82 CHAPTER 4 API functions 4 8 4 FS FormatLow Description Low level formats a device Required by NAND NOR flashes prior to format Prototype int FS FormatLow const char pDeviceName Parameter Description pVolumeName Name of the device to low level format Table 4 47
120. X GetStatus FS IDE HW X SetCommand FS IDE HW X SetCylHigh FS IDE HW X SetCylLow FS IDE HW X SetData FS IDE HW X WriteData FS IDE HW X SetDevControl FS IDE HW X SetDevice FS IDE HW X SetFeatures FS IDE HW X SetSectorCount FS IDE HW X SetSectorNo Table 10 13 Differences between uC FS v 2 x v 3 x CF IDE driver hardware interface differences User s amp reference manual for uC FS 2004 2007 Micrium 303 Hardware interface version 2 x Hardware interface version 3 x FS IDE HW X DetectStatus FS IDE HW X ReadReg FS IDE HW X WriteReg Table 10 13 Differences between uC FS v 2 x v 3 x CF IDE driver hardware interface differences Refer to the section CompactFlash card 8 IDE driver on page 223 for detailed infor mation about the CF IDE driver in uC FS version 3 x 10 4 8 Flash NOR flash differences In version 3 x Alternative removed macros FS USE FLASH DRIVER FS AddDevice s FS NOR Driver FS FLASH MAX ERASE CNT DIFF FS FLASH NUM FREE SECTORCACHE FS FLASH CHECK INFO SECTOR FS NOR Configure Refer to FLASH BASEADR FS NOR Configure on page 248 for FLASH USER START detailed i
121. YPE is defined as follows typedef int FS_QUERY_F_TYPE int ErrCode The callback is used to notify the user about the error that occurred and to ask whether the error should be fixed To get a detailed information string of the error that occurred the parameter ErrCode can be passed to FS FAT CheckDisk ErrCode2Text User s amp reference manual for uC FS 2004 2007 Micrium Example include lt stdarg h gt include FS h static U32 _aBuffer 5000 E Ekk kk kk kk kkk kk kkk kkk kk k kkk kk k kk _OnError x int _OnError int ErrCode da E va list ParamList const char sFormat char c char ac 1000 sFormat FS FAT CheckDisk ErrC if sFormat va start ParamList ErrCode vsprintf ac sFormat ParamLi printf Ss n ac if ErrCode FS ERRCODE CLUST printf Do you want to repa else printf Convert lost clus Delete cluster ch Do not repair Abort printf Xn c getchar printf n if c y c return 1 else if c a c return 2 else if c d c return 3 return 0 Do not fix RE RRRRKRER EERE ER kkk kkk kkk kkk kkk kk x MainTask KP void MainTask void FS Init while FS FAT CheckDisk User s amp reference manual for uC FS amp _aBuffer 0 111 kkkkxkkxkxkxkxkxkxkxkxkxkkkkkxkkkkxkxkkxkkkxkkxkkkkkxk ode2Text ErrCode
122. _CFI_1x16 Configure a single NOR flash interface 256 Mbytes FS NOR Configure 0 0x1000000 0x1000000 0x200000 User s A reference manual for uC FS 2004 2007 Micrium 254 CHAPTER 5 Device drivers Configure two NOR flash chips void FS X AddDevices void Add driver FS_AddDevice amp FS NOR Driver Set physical type 2 identical CFI compliant NOR flash chips with 16 bit interface if FS_NOR_SetPhyType 0 amp FS_NOR_PHY_CFI_2x16 Configure two NOR flash interfaces 256 Mbytes each Lif FS_NOR_Configure 0 0x1000000 0x1000000 0x400000 5 6 5 3 FS NOR SetPhyType Description Sets the physical type of the device The NOR flash driver comes with 2 different physical interfaces The most common is a CFI compliant NOR flash chip with a 16 bit interface A device can consist of a single or two identical CFI compliant flash inter faces with a 16 bit interface Set pPhyType to FS NOR PHY CFI 1x16 if you use a single NOR flash chip If your device consists of two identical NOR flash chips set pPhyType to FS NOR PHY CFI 2x16 This function has to be called from within FS X AddDevices after adding the device driver to file system Refer to FS X AddDevices on page 262 for more information Prototype void FS NOR SetPhyType U8 Unit const FS NAND PHY TYPE pPhyType Parameter Meaning Unit Unit number 0 N pPhyType Pointer to
123. _acCache sizeof acCache FS CACHE RW OUOTA Set the FS CACHE RW module to cache all sectors Sectors are cached for read and write Write back operation to volume are delayed y FS_CACHE_SetMode FS_SECTOR_TYPE_MASK_ALL FS_CACHE_MODE_FULL Set the quotas for directory and data sector types in the CACHE_RW_QUOTA module to 10 sectors each FS_CACHE_SetQuota FS_SECTOR_TYPE_MASK_DATA FS SECTOR TYPE MASK DIR 10 Do some work DoWork FS CACHE Clean DoOtherWork Disable cache FS AssignCache NULL 0 User s amp reference manual for uC FS 2004 2007 Micrium 122 CHAPTER 4 API functions 4 13 Error handling functions 4 13 1 FS _ClearErr Description Clears the error status of a file Prototype void FS ClearErr FS FILE pFile Parameter Description pFile Pointer to a data structure of type FS FILE Table 4 83 FS ClearErr parameter list Additional Information This routine should be called after you have detected an error so that you can check for success of the next file operations Example void MainTask void FS FILE pFile int Err pFile FS FOpen test txt r if pFile 0 Err FS FError pFile if Err FS ERR OK FS ClearErr pFile FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 123 413 2 FS FEof De
124. adapted In some special cases when the low level hardware routines provided by the driver are not compatible with the target hardware e g special FPGA implementations of a memory controller the physical layer has to be adapted Port pin any hardware simple memory controller Memory controller e g special FPGA implementations If there is a reason to change the physical layer anyhow the functions which have to be changed are organized in a function table The function table is implemented in a structure of type FS NANI typedef struct FS NAN Int int int int int int pfEraseBlock pfinitGetDevicel pfIsWP pfRead pfReadEx pfWrite User s amp reference manual for uC FS Info D PHY TYPE D PHY TYPE U8 U32 U8 FS NAND DEV CE U8 U8 U32 void unsigned unsigned U8 U32 void unsigned unsigned void unsigned unsigned U8 U32 const void unsigned NFO Unit Block Unit pDevInfo Unit Unit PageNo pData Off NumBytes Unit PageNo pData Off NumBytes pSpare OffSpare NumBytesSpare Unit PageNo pData Off 2004 2007 Micrium 158 int pfWriteEx FS NAND PHY TYPE CHAPTER 5 Device drivers unsigned NumBytes Unit PageNo const void pData unsigned Off unsigned NumBytes const void pSpare unsigned OffSp
125. ame int TypeMask int ModeMask Parameter Description DevName P the volume table will be use TypeMask Specifies the cache mode th ModeMask lowing parameters as cache pDevName is the name of a device If not specified the first device in Specifies the sector types that should be cached This parameter can be an OR combination of the following sector type mask d at should be used Use one of the fol mode mask Table 4 81 FS_CACHE_SetMode parameter list Permitted values for parameter TypeMask OR combinable FS_SECTOR_TYPE_MASK_DATA Caches all data sectors FS_SECTOR_TYPE_MASK_DIR Caches all directory sectors FS_SECTOR_TYPE_MASK_MAN Caches all management sectors FS_SECTOR_TYPE_MASK_ALL Caches all sectors by an OR combina tion of FS_SECTOR_TYPE_MASK_DATA FS_SECTOR_TYPE_MASK_DIR FS_SECTOR_TYPE_MASK_MAN Permitted values for parameter ModeMask OR combinable Sectors of types defined in TypeMask FS_CACHE MODE_R are copied to cache when read from volume Sectors of types defined in TypeMask FS_CACHE_MODE_WT are copied to cache and also written to the volume Writethrough cache FS CACHE MODE WB Sector types defined in TypeMask are lazily written back to the device Writeback cache Return value 0 Setting the mode of the cache module was successful
126. an SPI is used you should verify that it is set up as follows 8 bits per transfer Most significant bit first Data changes on falling edge Data is ledged on rising edge Verify signals during initialization of the card The oscilloscope has been set up as follows Color Description RED MOSI Master Out Slave In Pin 2 PURPLE MISO Master In Slave Out Pin 7 GREEN CLK Clock Pin 5 YELLOW CS Chip Select Pin 1 Table 5 70 Screenshot descriptions Trigger Single falling edge of CS To check if your implementation of the hardware layer works correct compare your output of the relevant lines SCLK CS MISO MOSI with the correct output which is shown in the following screenshots The output of your card should be similar In the example MISO has a pull up and a pull down of equal value This means that the MISO signal level is at 50 1 65V when the output of the card is inactive On other target hardware the inactive level can be low in case a pull down is used or high if a pull up is used User s amp reference manual for uC FS 2004 2007 Micrium 221 Initial communication sequence The initial communication sequence consists of the following three parts 1 Outputs 10 dummy bytes with CS disabled MOSI 1 2 Sets CS low and send a 6 byte command GO IDLE STATE command 3 Receives two byte set CS high and output 1 dummy byte with CS disabled MOSI 1 Ove
127. anual for uC FS 2004 2007 Micrium 214 CHAPTER 5 Device drivers 5 4 7 9 FS_MMC_HW_X_ReadData Description Receives a number of bytes from the card Prototype int FS_MMC_HW_X_ReadData U8 Unit void pBuffer unsigned NumBytes unsigned NumBlocks Parameter Meaning Unit Unit number 0 N pBuffer Pointer to a buffer for data to receive the response NumBytes Number of bytes to receive NumBlocks Number of blocks to receive Table 5 62 FS MMC HW X ReadData parameter list Return value Return value Meaning FS MMC CARD NO ERROR All data have been read successfully FS MMC CARD READ TIMEOUT Card did not send the data in appropriate time The received response failed the CRC check of card host controller Table 5 63 FS MMC HW X ReadData list of return values Additional Information FS MMC CARD READ CRC ERROR This function is used to read the data is coming from MMC SD card to the host con troller through the DAT line or DAT 0 3 lines Example int FS MMC HW X ReadData U8 Unit void pBuffer unsigned NumBytes unsigned NumBlocks U16 pBuf U16 pBuffer int i do 1 0 Wait until transfer is complete while __SDMMC_STATUS amp MMC STATUS FIFO FULL 0 if __SDMMC_STATUS amp MMC STATUS READ CRC ERROR return FS MMC CARD READ CRC ERROR if
128. ar pDirName Parameter Description pDirName Fully gualified directory name Table 4 41 FS MkDir parameter list Return value 0 The directory was successfully created 1 In case of any error Additional Information Refer to FS_FindFirstFile on page 73 for examples of valid fully qualified directory names Note that FS MkDir will not create the whole pDirName it will only create a directory in an already existing path Example void FSTaskl void int Err Create mydir in directory test default driver on default device Err FS_MkDir test mydir void FSTask2 void int Err Create directory mydir RAM device driver on default device Err FS_MkDir ram mydir User s amp reference manual for uC FS 2004 2007 Micrium 76 CHAPTER 4 API functions 4 7 5 FS RmDir Description Deletes a directory Prototype int FS RmDir const char pDirname Parameter Description pDirname Fully gualified directory name Table 4 42 FS RmDir parameter list Return value 0 If the directory has been successfully removed 1 In case of any error Additional Information Refer to FS FindFirstFile on page 73 for examples of valid and fully qualified directory names FS RmDir will only delete a directory if it is empty Example void FSTaskl void int Err Remove mydir in direc
129. ar sDest Parameter Description sSource Pointer to a string that specifies the name of an existing file sDest Pointer to a string that specifies the name of the new file Table 4 20 FS CopyFile parameter list Return value 0 If the file has been copied 1 In case of any error Additional Information Valid values for sSource are the same as for FS FOpen Refer to FS FOpen on page 48 for examples of valid names Example void MainTask void FS CopyFile test txt ram info txt User s amp reference manual for uC FS 2004 2007 Micrium 59 4 6 2 FS GetFileAttributes Description The FS GetFileAttributes function retrieves attributes for a specified file or direc tory Prototype U8 FS GetFileAttributes const char pName Parameter Description pName Pointer to a string that specifies the name of a file or directory Table 4 21 FS GetFileAttributes parameter list Return value gt 0x00 Attributes of the given file or directory OxFF In case of any error The attributes can be one or more of the following values Attribute Description The file or directory is an archive file or directory Applications can use this attribute to mark files for backup or removal FS ATTR DIRECTORY The given pName is a directory The file or directory is hidden It is not included in an ordinary directory listing The file or directory is r
130. arameter pMode Appends opens creates binary file for writing at aa end of file r Opens text file for update reading and writing Truncates to zero length or creates text file for update T Appends opens creates text file for update writ ing at end of file r b or rb Opens binary file for update reading and writing Truncates to zero length or creates binary file for w b or wb update Appends opens creates binary file for update ATD OT taD writing at end of file For more details on the FS FOpen function also refer to the ANSI C documentation regarding the fopen function Note that uC FS does not distinguish between binary and text mode files are always accessed in binary mode Example FS FILE pFile void fool void Open file for reading default driver on default device pFile FS FOpen test txt r void foo2 void Create new file for writing default driver on default device pFile FS_FOpen test txt w void foo3 void Open file for reading in folder mysub default driver on default device pFile FS_FOpen mysub test txt r void foo4 void Open file for reading RAM device driver on default device pFile FS_FOpen ram test txt r void foo5 void Open file for reading RAM device driver on device number 2 pFile FS FOpen ram 1 test txt r User s amp referenc
131. are unsigned NumBytesSpare If the physical layer should be modified the following members of the structure FS_NAND_PHY_TYPE have to be adapted Routine Explanation pfEraseBlock Erases a chosen block of the device Meow teen o Initializes the devices and retrieves the Pr es ee device information pfIsWP Checks if the device is write protected pfRead Reads data from the device k Reads data from the device and the spare pfReadEx area pfWrite Writes data to the device F Writes data to the device and the spare pfwriteEx area Table 5 10 NAND device driver physical layer functions User s amp reference manual for uC FS 2004 2007 Micrium 159 5 3 6 1 pfEraseBlock Description Erases one block of the device A block is the smallest eraseable unit Prototype int pfEraseBlock U8 Unit U32 PageIndex Parameter Meaning Unit Unit number 0 N Zero based index of the first page in the block to be erased If the device has 64 pages per block then the following values are permitted PageIndex PageIndex 0 gt block 0 PageIndex 64 gt block 1 PageIndex 128 gt block 2 etc Table 5 11 pfEraseBlock parameter list Return value 0 On success block erased 1 In case of an error User s amp reference manual for uC FS 2004 2007 Micrium 160 CHAPTER 5 Device drivers 5 3 6 2
132. ck function for the error handling that is used by FS FAT CheckDisk See FS FAT CheckDisk on page 110 for an exam ple User s amp reference manual for uC FS 2004 2007 Micrium 113 4 11 3 FS FormatSD Description Performs a high level format of a device according to the SD Specification File sys tem specification Prototype int FS FormatSD const char pVolumeName Parameter Description pVolumeName Name of the device to format Table 4 78 FS FormatSD parameter list Return value 0 File system has been started I 0 An error has occurred Additional Information For further information refer to SD Specification Part 2 File System Specification May 9 2006 www sdcard org User s amp reference manual for uC FS 2004 2007 Micrium 114 CHAPTER 4 API functions 4 11 4 FS FAT SupportLFN Note The LFN package is needed to support long file names Description Adds long file name support to the file system Prototype void FS SupportLFN void Additional Information The FAT file system was not designed for long file name LFN support limiting names to twelve characters 8 3 LFN support may be added to any of the FAT file systems but there are legal issues that must be settled with Microsoft before end applications make use of this feature Long file names are inherent to this proprietary file system relieving it of any legal issues User s amp
133. crium 238 CHAPTER 5 Device drivers Example FS_AddDevice amp FS_ IDE Driver 5 5 5 2 FS_IDE_Configure Description Configures the IDE CF drive This function has to be called from FS X AddDevices FS IDE Configure can be called before or after adding the device driver to the file system Refer to FS X AddDevices on page 262 for more information Prototype void FS IDE Configure U8 Unit U8 IsSlave Parameter Description Unit Unit number 0 N ISSlave Specifies whether the unit is connected Table 5 74 FS IDE Configure parameter list Additional information This function only needs to be called when the device does not use the default IDE master slave configuration By default all even units 0 2 4 are master all odd units are slave 1 3 5 Example Configure 2 different IDE CF devices void FS X AddDevices void Add 2 instances of the IDE driver FS_AddDevice amp FS_IDE Driver FS_AddDevice amp FS_ IDE Driver Set the first unit as MASTER FS IDE Configure 0 0 Set the second unit as MASTER FS IDE Configure 1 0 User s amp reference manual for uC FS 2004 2007 Micrium 5 5 6 Hardware functions Routine Explanation Control line function FS IDE HW Reset Resets the bus interface FS IDE HW Delay400ns Waits 400ns FS IDE
134. crium 78 CHAPTER 4 API functions 4 8 Formatting a medium In general before a medium can be used to read or write to a file it needs to be for matted Flash cards are usually already preformatted and do not need to be format ted Flashes used as storage devices have normally to be reformatted These devices require a low level format first then a high level format The low level format is device specific the high level format depends on the file system only FAT format typically User s amp reference manual for uC FS 2004 2007 Micrium 79 4 8 1 FS_IsHLFormatted Description Checks if the volume is high level formatted Prototype int FS IsHLFormatted const char sVolume Parameter Description pVolume Name of the device to check Table 4 44 FS IsHLFormatted parameter list Return value 1 Volume is high level formatted 0 Volume is not high level formatted 1 Device is not ready or a general error has occured User s amp reference manual for uC FS 2004 2007 Micrium 80 CHAPTER 4 API functions 4 8 2 FS_IsLLFormatted Description Checks if the volume is low level formatted Prototype int FS IsHLFormatted const char sVolume Parameter Description sVolume Name of the device to check Table 4 45 FS IsLLFormatted parameter list Return value 1 Volume is low level formatted 0 Volume is not low level formatted 1
135. ction Example void FS MMC HW X Delay int ms OS Delay ms 1 Make sure we delay at least lt ms gt milliseconds User s amp reference manual for uC FS 2004 2007 Micrium 5 4 8 Additional information For more technical details about MultiMedia amp SD cards check the documents and specifications available on the following internet web pages http www mmca org http www sdcard org 5 4 9 Resource usage 5 4 9 1 ROM usage 219 The ROM usage depends on the compiler options the compiler version and the used CPU The memory reguirements of the MMC SD driver have been measured on a sys tem as follows ARM7 IAR Embedded workbench V4 41A Thumb mode Size optimi zation ROM Module Kbytes uC FS SD card SPI mode driver 2 8 uC FS SD card card mode driver 2 6 5 4 9 2 Static RAM usage Static RAM usage is the amount of RAM reguired by the driver for variables inside of the driver The number of bytes can be seen in a list file Static RAM usage of the SD card driver in SPI mode 12 bytes Static RAM usage of the SD card driver in card mode 24 bytes 5 4 10 FAQs None User s amp reference manual for uC FS 2004 2007 Micrium 220 CHAPTER 5 Device drivers 5 4 11 Troubleshooting If the driver test fails or if the card cannot be accessed at all please follow the trou ble shooting guidelines below 5 4 11 1 SPI mode troubleshooting guide Verify SPI configuration If
136. d is reset only at power up if this pin is left high or open from power up 5 V 3 3 V power Voltage Sense Signals VS1 is grounded so that the CompactFlash Storage Card or CF Card CIS can be read at 3 3 volts and VS2 is reserved by PCMCIA for a secondary voltage The WAIT signal is driven low by the CompactFlash Storage Card or CF Card to signal the host to delay completion of a memory or I O cycle that is in progress This is a signal driven by the host and used for strobing memory write data to the registers of the CompactFlash Storage Card or CF Card when the card is configured in the memory interface mode The CompactFlash Storage Card or CF Card does not have a write protect switch This signal is held low after the completion of the reset initialization seguence Table 5 73 Pin functions in memory card mode Continued User s amp reference manual for uC FS 2004 2007 Micrium 235 Sample block schematic 20 21 CFDO CFEN 9 fei 22 CFDI CFA2 18 o 23 CID CFA3 17 2 CFD3 4 A3 D3 A4 pa 8 ae 4 CFD5 AS DS 5 CFD6 CFGND A6 D6 HD A7 D7 CFVCC pg 47 CFD8 er D10 42 CFDI0 p11 ZZ CDN 100n p12 28 CFDD D13 29 CB p14 SO CED 14 100n p15 SL CFDIS RESET 100n IOCS16 WP WAIT IORDY A STSCHG PDIAG n es SPKR_DASP 43 CFGND E 26 ja CD1 75 VS2 CD2 39 ver CFVCC CFGND cs CSEL gt 1 1 9 CE1 CSO VCC 13 o 5 CE2 CS1__VCC OE ATASEL CFVCC IORD 10u 6
137. d pretends that it is a hard drive that you can format mount save files to etc Remember that every bit of RAM is important for the well being of your system and the bigger your RAM disk is the less memory there is available for your system 5 2 3 Fail safe operation When power is lost the data of the RAM drive is typically lost as well except for sys tems with Battery backup for the RAM used as storage device For this reason fail safety is relevant only for systems which provide such battery backup Unexpected Reset In case of an unexpected reset the data will be preserved However if the Power fail ure unexpected Reset interrupts a write operation the data of the sector may con tain partially invalid data Power failure Power failure causes an unexpected reset and has the same effects 5 2 4 Wear leveling The RAM disk driver does not reguire wear leveling User s amp reference manual for uC FS 2004 2007 Micrium 144 CHAPTER 5 Device drivers 5 2 5 Configuring the driver 5 2 5 1 Adding the driver to pC FS To add the driver use FS AddDevice with the driver label FS RAMDISK Driver This function has to be called from within FS X AddDevices Refer to FS X AddDevices on page 262 for more information Refer to FS_X_AddDevices on page 262 for more information Example FS AddDevice FS RAMDISK Driver 5 2 5 2 FS RAMDISK Configure Description Configures a single RA
138. ddrMode U8 Unit FS USE PARA Unit CLE low ALE high NAND CLR CLE NAND SET ALE User s amp reference manual for uC FS 2004 2007 Micrium 168 CHAPTER 5 Device drivers 5 3 7 2 FS NAND HW X SetCmdModef Description Sets CLE high and ALE low for the specified device Prototype void FS NAND HW X SetCmdMode U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 20 FS NAND HW X SetCmdMode parameter list Additional Information This function is called to start the command transfer Example void FS NAND HW X SetCmdMode U8 Unit FS USE PARA Unit CLE high ALE low NAND SET CLE NAND CLR ALE User s amp reference manual for uC FS 2004 2007 Micrium 169 5 3 7 3 FS NAND HW X SetDataModef Description Sets CLE low and ALE low for the specified device Prototype void FS NAND HW X SetDataMode U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 21 FS NAND HW X SetDataMode parameter list Additional Information This function is called to the start data transfer Example void FS NAND HW X SetData U8 Unit FS USE PARA Unit CLE low ALE low NAND CLR CLE NAND CLR ALE User s amp reference manual for uC FS 2004 2007 Micrium 170 CHAPTER 5 5 3 7 4 FS NAND HW X _ DisableCE Description Disables NAND CE Prototype void F
139. ditional Information In this version of uC FS this function simply returns the file pointer element of the file s FS FILE structure Nevertheless you should not access the FS FILE structure yourself because that data structure may change in the future versions of uC FS In conjunction with FS SetFilePos FS GetFilePos this function can also be used to examine the file size By setting the file pointer to the end of the file using FS SEEK END the length of the file can now be retrieved by calling FS GetFilePos This function is identical to FS FTell Refer to FS FTell on page 55 for more information Example const char acText hello world n void MainTask void FS FILE pFile I32 Pos pFile FS FOpen test txt w if pFile 0 FS FWrite acText 1 strlen acText pFile Pos FS GetFilePos pFile FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 57 4 5 4 FS_SetFilePos Description Sets the current position of a file pointer Prototype int FS SetFilePos FS FILE pFile 132 DistanceToMove int MoveMethod Parameter Description pFile Pointer to a data structure of type FS FILE A 32 bit signed value where a positive value moves the file DistanceToMove pointer forward in the file and a negative value moves the file pointer backward MoveMethod The starting point for the file pointer move Table 4 19 FS SetFilePos parameter
140. e 4 41 Table 4 42 Table 4 43 Table 4 44 Table 4 45 Table 4 46 Table 4 47 Table 4 48 Table 4 49 Table 4 50 Table 4 51 Table 4 52 Table 4 53 Table 4 54 Table 4 55 Table 4 56 Table 4 57 Table 4 58 Table 4 59 Table 4 60 Table 4 61 Table 4 62 Table 4 63 Table 4 64 98 Table 4 65 Table 4 66 Table 4 67 Table 4 68 Table 4 69 Table 4 70 Table 4 71 Table 4 72 Table 4 73 Table 4 74 Table 4 75 Table 4 76 Table 4 77 112 Table 4 78 Table 4 79 Table 4 80 User s amp reference manual for uC FS FS Truncate parameter list ccccceceeeeeeeeeeee ees 69 FS Verify parameter liSt 70 FS FindClose parameter list n 72 FS FindFirstFile parameter list 73 FS FindNextFile parameter list 74 FS MkDir parameter list 75 FS_RmDir parameter list ccccesscceee ee eeaeaeee ees 76 FS_FIND_DATA list of structure elements 77 FS_IsHLFormatted parameter list 79 FS_IsLLFormatted parameter list 80 FS FormatLLIfReguired parameter list 81 FS_FormatLow parameter list 82 FS Format parameter list ccccccccceeeeesseeeee ees 83 FS FORMAT INFO list of structure elements 84 FS DEV INFO list of structure elements 85 FS FileTimeToTimeStamp parameter list 86 FS GetFileSize parameter list 87 FS Get
141. e Card or CF Card in Memory Mode and to read the CIS and configuration regis ters Table 5 73 Pin functions in memory card mode User s amp reference manual for uC FS 2004 2007 Micrium 234 CHAPTER 5 Device drivers Signal name Dir Pin Description READY REG RESET WAIT WE WP O 37 44 41 13 38 33 4 42 36 24 In Memory Mode this signal is set high when the CompactFlash Storage Card or CF Card is ready to accept a new data transfer operation and is held low when the card is busy At power up and at Reset the READY signal is held low busy until the Com pactFlash Storage Card or CF Card has completed its power up or reset function No access of any type should be made to the CompactFlash Storage Card or CF Card during this time Note however that when a card is powered up and used with RESET continuously disconnected or asserted the reset function of this pin is disabled and conse quently the continuous assertion of RESET will not cause the READY signal to remain continuously in the busy state This signal is used during Memory Cycles to distin guish between Common Memory and Register Attribute Memory accesses High for Common Memory Low for Attribute Memory To use it with uC FS this signal should be high When the pin is high this signal Resets the Com pactFlash Storage Card or CF Card The Compact Flash Storage Card or CF Car
142. e accessed though two different modes e SPI MODE e MMC SD card mode Drivers are available for both modes Device drivers MultiMediaCard To use one of these drivers you need to configure the selected MultiMedia amp SD card driver and provide basic I O functions for accessing your card reader hardware This section describes how to enable one of these drivers and all hardware access functions required by uC FS s for either the MultiMedia SD and SDHC card in SPI mode or MultiMedia amp SD card mode driver 5 4 1 Supported hardware MultiMedia Cards MMC SecureDigital Cards SD card and SecureDigital High Capacity SDHC Cards are small size factor mass storage devices The main design goal of these devices are to provide a very low cost mass storage product implemented as a card with a simple controlling unit and a compact easy to implement interface These requirements lead to a reduction of the functionality of each card to an absolute minimum In order to have a flexible design MMC SD and SDHC cards are designed to be used in different I O modes e MMC SD card mode e SPI mode e Emulated SPI mode using port pins The difference between MMC and SD cards are that SD cards can operate with a higher clock frequency The clock range can be between 0 25MHz whereas MMCs can only operate up to 20MHz Additionally the initialization of these cards differs They need to be initialized differently but after init
143. e information User s amp reference manual for uC FS 2004 2007 Micrium 262 CHAPTER 5 Device drivers Prototype void WINDRIVE Configure U8 Unit const char sDriveName Parameter Description Unit Unit number 0 n Pointer to string which contains the windows drive name For example a Table 5 91 FS Windrive Configure parameter list sDriveName 5 7 6 Hardware functions The WinDrive driver does not need any hardware functions 5 7 7 Additional information None User s amp reference manual for uC FS 2004 2007 Micrium 263 5 8 Writing your own driver If you are going to use uC FS with your own hardware you may have to write your own device driver This section describes which functions are reguired and how to integrate your own device driver into pC FS Call function in table 5 8 1 Device driver functions This section provides descriptions of the device driver functions required by HC FS Note that the names used for these functions are not really relevant for uC FS because the file system accesses them through a function table Routine Explanation AddDevice Adds a device to file system GetName Returns the name of the device GetNumUnits Returns the number of units GetStatus Returns the Status of the device InitMedium Initializes the device To eli Executes a special command on a device
144. e manual for uC FS 2004 2007 Micrium 50 CHAPTER 4 API functions 4 4 3 FS_FRead Description Reads data from an open file Prototype U32 FS FRead void pData U32 Size U32 N U32 pFile Parameter Description pData Pointer to a data buffer for storing data transferred from a file Size Size of an element to be transferred from a file to a data buffer N Number of elements to be transferred from the file pFile Pointer to a data structure of type FS FILE Table 4 12 FS FRead parameter list Return value Number of elements read Additional Information If there is less data transferred than specified you should check for possible errors by calling the FS FError function Example char acBuffer 100 void MainTask void FS FILE pFile int i pFile FS_FOpen test txt r if pFile 0 do i FS_FRead acBuffer 1 sizeof acBuffer 1 pFile acBuffer i 0 if i printf s acBuffer while i FS_FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 51 4 4 4 FS Read Description Reads data from an open file Prototype U32 FS FRead FS FILE pFile void pData U32 NumBytes Parameter Description pFile Pointer to a data structure of type FS FILE pData Pointer to a data buffer for storing data transferred from a file NumBytes Number of bytes to be transferred fro
145. eOut parameter list Additional Information This function sets the card host controller timeout value in MMC clock cycles before the card host controller sets a timeout condition when receiving data from card Example void FS MMC HW X SetReadDataTimeOut U8 Unit int Value SDMMC READ TO Value Set the read timeout User s amp reference manual for uC FS 2004 2007 Micrium 209 5 4 7 4 FS_MMC_HW_X_SetHWBlockLen Description Sets the card host controller block size value for a block Prototype void FS MMC HW X SetHWBlockLen U8 Unit U16 BlockSize Parameter Meaning Unit Unit number 0 N BlockSize Block size given in number of bytes Table 5 55 FS MMC HW X SetHWBlockLen parameter list Additional Information Card host controller sends data to or receives data from the card in block chunks This function typically sets the card host controller s block length register Example void FS MMC HW X SetHWBlockLen U8 Unit U16 BlockSize __SDMMC_BLK LEN BlockSize User s amp reference manual for uC FS 2004 2007 Micrium 210 CHAPTER 5 Device drivers 5 4 7 5 FS_MMC_HW_X_SetHWNumBlocks Description Tells the card host controller how many block will be transferred to or received from card Prototype void FS MMC HW X SetHWNumBlocks U8 Unit U16 NumBlocks Parameter Meaning Unit Unit number 0 N NumBlocks N
146. ead only Applications can read the file FS ATTR READ ONLY but cannot write to it or delete it In case of a directory appli cations cannot delete it The file or directory is part of or is used exclusively by the operating system Table 4 22 FS GetFileAttributes list of possible attributes Additional Information FS ATTR ARCHIVE FS ATTR HIDDEN FS ATTR SYSTEM Valid values for pName are the same as for FS FOpen Refer to FS FOpen on page 48 for examples of valid names Example void MainTask void U8 Attributes char ac 100 Attributes FS GetFileAttributes test txt sprintf ac File attribute of test txt d Attributes FS X Log ac User s amp reference manual for uC FS 2004 2007 Micrium 60 CHAPTER 4 API functions 4 6 3 FS GetFileTime Description Retrieves a timestamp for a specified file or directory Prototype int FS GetFileTime const char pName U32 pTimeStamp Parameter Description pName Pointer to a string that specifies the name of a file or directory pTimeStamp Pointer to a U32 variable that receives the timestamp Table 4 23 FS GetFileTime parameter list Return value 0 The timestamp of the given file was successfully read and stored in pTimeS tamp 1 In case of any error Additional Information Values for pName are the same as for FS FOpen Refer to FS_FOpen on page 48 for e
147. eadSectors Reads multiple sectors from a device FS STORAGE Sync Writes cached data to the storage medium Table 4 1 pC FS API function overview Continued User s amp reference manual for uC FS 2004 2007 Micrium 36 CHAP TER 4 API functions Function Description FS STORAGE Unmount Low level unmount Unmounts a volume on driver layer FS STORAGE WriteSector Writes a sector from a device FS STORAGE WriteSectors Writes multiple sectors from a device FAT rel ated functions FS FAT CheckDisk Checks and repairs a FAT volume FS FAT CheckDisk ErrCode2Text Returns an error string to a specific Check disk error code FS FAT SupportLFN Add long file name support to the file sys tem FS FormatSD High level formats a device according to the SD card file system specification File system cache functions FS AssignCache Adds a cache to a specific device Cleans the caches and writes dirty sectors FS CACHE Clean to the volume FS CACHE SetMode Sets the mode for the cache Sets the quotas for the different sector FS CACHE SetQuota types in the FS Cache RW Ouota cache module Error handling functions Clears the error status of a given file PS Cleerkrr pointer FS FEof Tests for end of file on a given file pointer Returns the error code of a given file FS PREEO
148. ecInfo gt NumFreeSectors pSecInfo gt NumEraseableSectors FS X Log acBuffer ERREK kk k k k k ERR KEE RK RRR k k k k ERK KE KE k k k k k k k k k k k k k k k k k k k k KR k k k EEE k k k k k User s amp reference manual for uC FS 2004 2007 Micrium 258 CHAPTER 5 MainTask 7 void MainTask void U32 dip di char ac 0x400 FS_NOR_DISK_INFO DiskInfo FS NOR SECTOR INFO SecInfo FS FILE pFile FS Init FS_FormatLLIfRequired for i 0 i lt strlen ac i ac i A Check if volume needs to be high level formatted if FS_IsHLFormatted 0 printf High level formatting n FS_Format NULL ShowDiskInfo amp DiskInfo for i 0 i lt 1000 i pFile FS_FOpen Test txt w if pFile 0 FS_Write pFile amp ac strlen ac FS_FClose pFile printf Loop cycle d n i for j 0 j lt DiskInfo NumPhysSectors ShowSectoriInfo amp SecInfo j while 1 User s amp reference manual for uC FS Device drivers 2004 2007 Micrium 259 5 6 8 3 Structure FS NOR DISK INFO Description The FS NOR SECTOR INFO structure contains physical and logical sector information Prototype typedef struct U32 NumPhysSectors U32 NumLogSectors U32 NumUsedSectors FS_NOR_DISK_INFO Number of used logical sectors Members Description NumPhysSectors Number physical sectors of the chi
149. ed Additional Information This function truncates an open file Be sure that pFile points to a file that has been opened with write permission For more information about setting write permission for pFile have a look at the description of FS_FOpen on page 48 Example void MainTask void FS FILE pFile U32 FileSize Int Success pFile FS FOpen test bin r FileSize FS GetFileSize pFile Success FS Truncate pFile FileSize 200 if Success 0 FS X Log Truncation was successful else FS_X_Log Truncation was not successful FS Fclose pFile User s amp reference manual for uC FS 2004 2007 Micrium 70 CHAPTER 4 API functions 4 6 13 FS Verify Description Validates a file by comparing its contents with a data buffer Prototype int FS Verify FS FILE pFile const void pData U32 NumBytes Parameter Description pFile Pointer to a string that specifies the name of a file or directory pData Pointer to a buffer that holds the data to be verified with the file NumBytes Number of bytes to be verified Table 4 37 FS Verify parameter list Return value 0 If verification was successful I 0 Verification failed Additional Information If the file contains less bytes than to be verified only the available bytes are verified Note The position of the file pointer has to set to the beginning of the data that should be v
150. ed for every data block which will be transmitted The following functions can be used for controlling CRC calculation in uC FS Function Description CRC configuration Activates the CRC functionality in SPI mode Deactivates the CRC functionality in SPI mode By default CRC is deactivated FS MMC ActivateCRC FS MMC DeactivateCRC Table 5 40 SPI mode configuration functions User s amp reference manual for uC FS 2004 2007 Micrium 5 4 5 3 FS_MMC_ActivateCRC Description Activates the cyclic redundancy check Prototype void FS MMC ActivateCRC void Additional information By default the cyclic redundancy check is deactivated for speed reasons The driver supports cyclic redundancy check both for all transmissions and just for critical trans missions You can activate and deactivate the cyclic redundancy check as it fits to the reguirements of your application User s amp reference manual for uC FS 2004 2007 Micrium 194 CHAPTER 5 Device drivers 5 4 5 4 FS MMC DeactivateCRC Description Deactivates the cyclic redundancy check Prototype void FS MMC DeactivateCRC void Additional information By default the cyclic redundancy check is deactivated for speed reasons The driver supports cyclic redundancy check both for all transmissions and just for critical trans missions You can activate and deactivate the cyclic redundancy check as it fits to the reguir
151. ed into its socket a LE CSO is the chip select for the task file registers while cso CS1 I 7 32 CS1 is used to select the Alternate Status Register and the Device Control Register This internally pulled up signal is used to configure this device as a Master or a Slave when configured in True CSEL I 39 IDE Mode When this pin is grounded the device is configured as a Master When the pin is open the device is configured as a Slave re All Task File operations occur in byte mode on the low D15 D00 O 5 6 order bus D00 D07 while all data transfers are 16 bit 21 23 Using DOO D15 GND 1 5 Ground This is an I O Read strobe generated by the host This IORD I 34 signal gates I O data onto the bus from the Compact Flash Storage Card or CF Card when the card is con figured to use the I O interface 1 0 Write strobe pulse is used to clock I O data on the Card Data bus into the CompactFlash Storage Card or IOWR I 35 CF Card controller registers when the CompactFlash Storage Card or CF Card is configured to use the I O interface The clocking will occur on negative to posi tive edge of the signal trailing edge OE ATA I 9 To enable True IDE Mode this input should be grounded SEL by the host INTRQ O 37 Signal is the active high interrupt request to the host This input signal is not used and should be connected REG le hae to VCC by the host This input pin is the active low hardware reset from RESET I 41 header VCC
152. em Af User s amp reference manual for uC FS 2004 2007 Micrium 38 CHAPTER 4 API functions 4 2 2 FS Mount Description Mounts a volume Prototype void FS Mount const char sVolume Parameter Description sVolume is the name of a volume If not specified the first device in the volume table will be used Table 4 2 FS Mount parameter list sVolume Additional Information This function can be useful if the default auto mount behavior has been changed with FS AutoMount Normally it is not required to mount a device with FS Mount since the file system auto mounts all accessible volumes in read write mode Refer to FS_SetAutoMount on page 39 for an overview about the different auto mount types User s amp reference manual for uC FS 2004 2007 Micrium 39 4 2 3 FS SetAutoMount Description Sets the mount behavior of the specified volume Prototype void FS SetAutomount const char sVolume U8 MountType Parameter Description sVolume is the name of a volume If not specified the first device in the volume table will be used MountType Specifies the auto mount behavior Table 4 3 FS SetAutoMount parameter list sVolume Permitted values for parameter MountType FS MOUNT R The volume will be read only auto mounted FS MOUNT RW The volume will be read write auto mounted 0 Disables auto mount for the volume Additional I
153. ements of your application User s amp reference manual for uC FS 2004 2007 Micrium 5 4 6 Hardware functions SPI mode Routine Explanation Control line functions Activates chip select signal CS of the PE MMC M Prase specified card slot Ce PS ETT Deactivates chip select signal CS of the specified card slot Operation condition d etection and adjusting FS MMC HW X SetMaxSpeed Sets the SPI clock speed The value is represented in thousand cycles per sec ond kHz FS MMC HW X SetVoltage Sets the operating voltage range for the MultiMedia amp SD card slot Medium status functions Checks the status of the mechanical write FS MMC HW X IsWriteProtected protection of a SD card FS MMC HW X IsPresent Checks whether a card is present or not Data transfer functions Receives a number of bytes from the FS MMC HW X Read card FS MMC HW X Write Sends a number of bytes to the card Table 5 41 SPI mode hardware functions User s amp reference manual for uC FS 2004 2007 Micrium 196 CHAPTER 5 5 4 6 1 FS MMC HW X EnableCS Device drivers Description Activates chip select signal CS of the specified card slot Prototype void FS MMC HW X EnableCS U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 42 FS MMC HW X EnableCS parameter list Additional Information The C
154. ence manual for uC FS 2004 2007 Micrium 27 Nearly all drivers have to be configured before they can be used The runtime config uration functions which specify for example the memory addresses and the size of memory are located in the configuration file of the respective driver All required configurations are explained in configuration section of the respective driver If you use one of the drivers which do not require hardware routines skip the next section and refer to Step 4 Activating the driver on page 29 User s amp reference manual for uC FS 2004 2007 Micrium 28 CHAPTER 3 Running yC FS on target hardware 3 3 2 Adding hardware routines to project A template with empty function bodies and in most cases one ore more sample implementations are supplied for every driver which reguires hardware routines The easiest way to start is to use one of the ready to use samples The ready to use samples can be found in the subfolders of Sample Driver lt DRIVER_DIR gt You should check the Readme txt file located in the driver directory to see which samples are included If there is one which is a good or close match for your hardware it should be used Otherwise use the template to implement the hardware routines The template is a skeleton driver which contains empty implementations of the reguired functions and is the ideal base to start the implementation of hardware spe cific I O routines What to do
155. entify ing information out of the flash chip itself The identifying information for the device such as memory size byte word configu ration block configuration necessary voltages and timing information is stored directly on the chip User s amp reference manual for uC FS 2004 2007 Micrium 249 5 6 1 1 Tested and compatible NOR flashes In general the driver supports almost all serial and parallel NOR flashes which fulfill the listed requirements This includes NOR flashes with 1x8 bit 1x16 bit and 2x16 bit interfaces The table below shows the serial NOR flashes that have been tested or are compati ble with a tested device Manufacturer Device Size M25P40 4 Mbytes 512 Kbytes x 8 M25P80 8 Mbytes 1Mbytes x 8 ST Microelectronics M25P16 16 Mbytes 2Mbytes x 8 M25P32 32 Mbytes 4Mbytes x 8 M25P128 128 Mbytes 16Mbytes x 8 Table 5 83 List of supported serial NOR flashes The table below shows the parallel NOR flashes that have been tested or are compat ible with a tested device Manufacturer Device Size Bits Intel Intel 28FxxxP30 64 Mbytes 1 Gbytes Intel 28FxxxP33 64 Mbytes 512 Mbytes M28W160 16 Mbytes 1 Mbytes x 16 M28W320 32 Mbytes 2 Mbytes x 16 M28 W640 64 Mbytes 4 Mbytes x 16 ST Microelectronics M29F080 8 Mbytes 1 Mbytes x 8 M29W160 16 Mbytes 2 Mbytes x 8 or 1 Mbytes x 16 M29W320 32 Mbytes 4 Mbytes x 8 or 2 Mbytes x 16 M29W640 64 Mbytes 8
156. er vec SDCard SDC ard Socket J O U1 ON CON9 FPS 009 2405 0 SPI User s amp reference manual for uC FS 2004 2007 Micrium 224 CHAPTER 5 Device drivers 5 5 CompactFlash card amp IDE driver uC FS supports the use of CompactFlash amp IDE devices An optional generic drivers for CompactFlash amp IDE devices is available To use the driver with your specific hardware you will have to provide basic 1 0 functions for accessing the ATA 1 0 registers This section describes all these rou tines 5 5 1 Supported Hardware uC FS s CompactFlash amp IDE device driver can be used to access most ATA HD drives or CompactFlash storage cards also known as CF using true IDE or Memory card mode User s amp reference manual for uC FS 2004 2007 Micrium 225 True IDE mode pin functions Signal T sta Dir Pin Description 18 19 Only A 2 0 are used to select one of eight registers in A2 A0 I 20 d the Task File the remaining address lines should be grounded by the host This input output is the Pass Diagnostic signal in the P LNG ek Master Slave handshake protocol This input output is the Disk Active Slave Present sig DASE 170745 nal in the Master Slave handshake protocol These Card Detect pins are connected to ground on v the CompactFlash Storage Card or CF Card They are CD1 CD2 O 26 25 used by the host to determine that the CompactFlash Storage Card or CF Card is fully insert
157. er These layer contains the low level routines to access your hardware These routines simply read and store fixed length sectors The structure of the device driver is sim ple in order to allow easy integration of your own hardware 1 3 2 Choice of file system type FAT vs EFS Within uC FS there is a choice among two different file systems The first the FAT file system is divided into three different sub types FAT12 FAT16 and FAT32 While the other EFS is a proprietary file system developed by Micrium Choosing a suit able file system will depend on the environment in which the end application is to operate The FAT file system was developed by Microsoft to manage file segments locate available clusters and reassemble file for use Released in 1976 the first version of the FAT file system was FAT12 which is no longer widely used It was created for extremely small storage devices The early version of FAT12 did not support manag ing directories FAT16 is good for use on multiple operating systems because it is supported by all versions of Microsoft Windows including DOS OS 2 and Linux The newest version FAT32 improves upon the FAT16 file system by utilizing a partition disk much more efficiently It is supported by Microsoft Windows 98 ME 2000 XP and 2003 and as well on Linux based systems The EFS file system has been added to uC FS as an alternative to the FAT file sys tem EFS has been designed for embedded devices
158. er in uC FS version 3 x 10 5 OS Integration In version 3 x removed macros In version 3 x used macros OS configuration macros FS_OS_LOCKING_PER_FILE Removed If you want to use uC FS version FS_OS_EMBOS 3 x with an RTOS define FS_OS_LOCKING in FS_OS_UCOS_ your FS Conf h Refer to OS integration FS OS WI NDOWS on page 271 for information about he func tions which has to be implemented to use FS OS uC FS with an RTOS Table 10 17 Differences between 1C FS v 2 x v 3 x removed replaced configuration macros Function Description Changed functions In uC FS version 3 x gets FS_xX_OS_TInit FS X OS Init an additional parameter Refer to FS X OS Init Removed functions FS X OS Exit Time and date functions FS X OS GetDate In uC FS version 3 x is only one version FS X OS GetDateTime used to handle the time and date function ality Refer to FS X GetTimeDate on page 264 for more information Table 10 18 Differences between uC FS v 2 x v 3 x Changes in the OS interface User s amp reference manual for uC FS 2004 2007 Micrium 305 Chapter 11 FAQs You can find in this chapter a collection of frequently asked questions FAQs together with answers User s amp reference manual for uC FS 2004 2007 Micrium 306 11 1
159. er speed Smaller code When deleting a large contiguous file on a FAT system it may take some time to delete the FAT B s md o DELITE 1 entries for the file This macro set to 1 enables a seguence to accel erate this operation ON Higher speed Bigger code OFF Lower speed Smaller code When using the LFN package the file directory name is stored as Unicode string This macros enables the support for accessing such files and directories where characters in the file directory name are others than the standard Latin characters such as Greek or Cyrillic To open such a file the string should be UTF 8 encoded B FS FAT SUPPORT UTF8 0 Table 6 3 FAT configuration macros User s amp reference manual for uC FS 2004 2007 Micrium 274 CHAPTER 6 HCIFS Configuration 6 2 3 EFS configuration Type Macro Default Description Setting this macro to 1 writing to a file always updates the directory entry of the file always after writ ing to the file guarding the new data against unexpected RESET ON Directory entry is updated with every write operation This is B FS EFS FWRITE UPDATE DIR 0 slower but has the advantage that data written without close in case of unexpected RESET is not lost OFF Directory entry is updated when file is closed This is faster but has the disadvantage that any data written between open and unexpected RESET is lost If EFS file directory o
160. erences The configuration of uC FS version 3 x has been simplified compared to uC FS v2 x UC FS v3 x can be used out of the box You can use it without the need for chang ing any of the compile time flags All compile time configuration flags are preconfig ured with valid values which matchs the requirements of the most applications A lot of the compile time flags of uC FS v 2 x are removed and replaced with runtime configuration function Removed replaced configuration macros In version 3 x In version 3 x removed macros used macros File system configuration FS_MAXOPEN FS NUM FILE HANDLES FS POSIX DIR SUPPORT FS DIR MAXOPEN FS NUM DIR HANDLES FS DIRNAME MAX FS SUPPORT BURST FS DRIVER ALIGNMENT FAT configuration macros Replaced by FS FAT SupportLFN Refer FS FAT SUPPORT LFN to FS FAT SupportLFN on page 115 for more information Table 10 2 Differences between 1C FS v 2 x v 3 x removed replaced configuration macros Changed default values of configuration macros Changed macros Default value in FS FAT OPTIMIZE SEO CLUSTERS Default value changed from 0 to 1 FS EFS FWRITE UPDATE DIR Default value changed from 1 to 0 Table 10 3 Differences between uC FS v 2 x v 3 x changed default values User s amp reference manual for uC FS 2004 2007 M
161. erified User s amp reference manual for uC FS 2004 2007 Micrium 71 Example const U8 acVerifyData 4 1 2 3 4 void MainTask void FS FILE pFile 132 n FS Init Open file and write data into pFile FS_FOpen test txt w FS Write pFile acVerifyData sizeof acVerifyData Determine current position of file pointer n FS_FTell pFile Set file pointer to the start of the data that should be verified hele FS_FSeek pFile 0 FS_SEEK_SET Verify data if FS_Verify pFile acVerifyData sizeof acVerifyData 0 FS_X_Log Verification was successful else FS_X_Log Verification failed Set file pointer to end of data that was written and verified FS_FSeek pFile n FS_SEEK_SET FS_FClose pFile while 1 User s amp reference manual for uC FS 2004 2007 Micrium 72 CHAPTER 4 API functions 4 7 Directory functions 4 7 1 FS FindClose Description Closes a directory Prototype void FS FindClose FS FIND DATA pfd Parameter Description pfd Pointer to a FS_FIND_DATA structure Table 4 38 FS_FindClose parameter list Example typedef struct Public elements to be used by application U8 Attributes U32 CreationTime U32 LastAccessTime U32 LastWriteTime U32 FileSize char sFileName Private elements Not be used by the a
162. estamp of the given file was successfully set I 0 In case of any error Additional Information Valid values for pName are the same as for FS FOpen Refer to FS FOpen on page 48 for examples of valid names On a FAT medium FS SetFileTime sets the creation time of a file or directory On a EFS medium FS SetFileTime sets the time stamp of a file or directory A timestamp is a packed value with the following format Bits Description 0 4 Second divided by 2 5 10 Minute 0 59 11 15 Hour 0 23 16 20 Day of month 1 31 21 24 Month January gt 1 February gt 2 etc 25 31 Year offset from 1980 Add 1980 to get current year Table 4 32 FS_SetFileTime timestamp format description To convert a FS FILETIME structure to a timestamp use the function FS_FileTimeToTimeStamp For more information about the conversion have a look at the description of FS_FileTimeToTimeStamp on page 86 Example void MainTask void U32 TimeStamp FS FILETIME FileTime FileTime Year 2005 FileTime Month 03 FileTime Day 26 FileTime Hour 10 FileTime Minute 56 FileTime Second 14 FS FileTimeToTimeStamp amp FileTime amp TimeStamp FS_SetFileTime test txt TimeStamp User s amp reference manual for uC FS 2004 2007 Micrium 67 4 6 10 FS SetFileTimeEx Description Sets the creation access or modify timestam
163. face routines for uC OS The following example shows an adaption for wC OS excerpt from file FS X uCoS II c located in the folder Sample os static OS EVENT _papSema void FS X OS Init unsigned NumLocks unsigned i OS EVENT pSema _papSema OS EVENT FS_AllocZeroed NumLocks sizeof OS EVENT pSema _papSema for i 0 i lt NumLocks i pSema OSSemCreate 1 pSema void FS X OS Unlock unsigned LockIndex OS EVENT pSema pSema _papSema LockIndex OSSemPost pSema void FS X OS Lock unsigned LockIndex INT8U err OS EVENT pSema pSema _papSema LockIndex OSSemPend pSema 0 amp err User s amp reference manual for uC FS 2004 2007 Micrium 283 Chapter 8 Debugging For debug purpose the following functions are helpful displaying information on dis play or through a serial communication port Furthermore additional hints are provided which may be helpful if you run into trou ble with uC FS integration User s amp reference manual for uC FS 2004 2007 Micrium 284 CHAPTER 8 Debugging 8 1 FS_X_Log Description Outputs debug information from uC FS This function has to integrated into your application if FS DEBUG LEVEL gt 5 Refer to section Debugging on page 275 of the Configuration chapter for further information about the different debug level Prototype void FS X Log const c
164. fies the sector types that should be cached This parameter can be an OR combination of the following sector type mask Specifies the number of sectors each sector type that is defined by TypeMask should reserve Table 4 82 FS CACHE SetOuota parameter list pDevName TypeMask NumSectors Permitted values for parameter TypeMask OR combinable FS SECTOR TYPE MASK DATA Caches all data sectors FS SECTOR TYPE MASK DIR Caches all directory sectors FS SECTOR TYPE MASK MAN Caches all management sectors All sectors are cached This is an OR combination of FS SECTOR TYPE MASK ALL FS_SECTOR_TYPE_MASK_DATA FS SECTOR TYPE MASK DIR FS SECTOR TYPE MASK MAN Return value 1 Setting the quota of the cache module was not successful 0 Setting the guota of the cache module was successful Additional Information This function is currently only usable with the FS CACHE RW OUOTA module After the FS CACHE RW OUOTA cache has been assigned to a volume and the cache mode has been set the guotas for the different sector types need to be configured with this function Otherwise neither read nor write operations are cached User s amp reference manual for uC FS 2004 2007 Micrium 121 Example include FS h static char _acCache 100 1024 Use a 100 Kbyte cache void Function void Assign a cache to the first available device FS AssignCache
165. file txt in the root directory of your RAM disk Stepping over this function should return the address of an FS FILE structure In case of any error it would return 0 indicating that the file could not be created Le FS Start Microsoft Visual C break Start c BEE 18 x Cu oc ions fers I OB tS HHH DE DE JE JE JE JE HEHEHE JE JE JE JE JE E JE JE JE JE JE DE JE JEJEJE JEJE A By Workspace FS Start 1 project s Ee FS Start files FSTask cation void FSTask void U32 v FS FILE pFile char ac 256 const char sVolName FS Init printf Running sample on s n sVolName v FS_GetVolumeFreeSpace sVolName printf Free space d bytes n v sprintf ac s File txt sVolNane printf Write test data to file s n ac pFile FS FOpen ac w if pFile FS Write pFile Test 4 FS_FClose pFile else printf Could not open file s to write n ac 3 Extemal Dependencies v FS GetYolumeFreeSpace sVolNane printf Free space d bytes n v printf Finished n while 1 HEHE HE IE JE JE JE E JE JE JE JE JE JE IE JE JE JE JE JE JE E JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE MEME Figure 2 3 FS_Start project FSTask 6 If FS FOpen returns a valid pointer to an FS FILE structure the sample appli cation will write a small ASCII st
166. for uC FS 2004 2007 Micrium 269 6 1 2 Memory allocation 6 1 2 1 FS_X_Alloc Description Provides memory to the file system Prototype void FS X Alloc U32 NumBytes Parameter Description NumBytes Number of bytes that should be allocated Table 6 1 FS X Alloc parameter list Additional information e Fragmentation The file system allocates memory only in the configuration phase not during nor mal operation so that fragmentation should not occur e Failure Since the memory is required for proper operation of the file system this func tion does not return on failure In case of a configuration problem where insuffi cient memory is available to the application this is normally detected by the programmer in the debug phase Example EA kkkkkkk kk kkk kkk kkk kkk kkk kk kk kkk k kk kk kk kk k kk k k kk kk k k kk k k k k k kk k k kkk RE FS X Alloc void FS X Alloc I32 NumBytes 132 NumItems void p NumItems NumBytes sizeof U32 1 sizeof U32 if FS_ALLOC_NumItemsFree NumItems lt 0 return NULL p _pNextBlock _pNextBlock NumItems FS ALLOC NumItemsFree NumItems return p User s amp reference manual for uC FS 2004 2007 Micrium CHAPTER 6 HCIFS Configuration 6 1 3 System configuration 6 1 3 1 FS X GetTimeDate Description Returns the current time and date Prototype U32 FS X OS GetTimeDate void Return value
167. for yC FS 2004 2007 Micrium Chapter 9 Performance and Resource usage User s amp reference manual for uC FS 2004 2007 Micrium 290 CHAPTER 9 Performance and Resource usage 9 1 Memory footprint The file system is designed to fit many kinds of embedded design requirements Sev eral features can be excluded from a build to get a minimal system that can effi ciently access any FAT media The operation area of uC FS is very different and the memory requirements RAM and ROM differs in depending on the used features The following section will show the memory reguirements of different modules which are used in typical applications Note that the values are valid for the given configuration Features can affect the size of others For example if FAT32 is deactivated the format function gets smaller because the 32 bit specific part of format is not added into the compilation 9 1 1 System The following table shows the hardware and the toolchain details of the project Detail Description CPU ARM7 Tool chain IAR Embedded Workbench for ARM V4 41A Model ARM7 Thumb instructions no interwork Compiler options Highest size optimization Empty dummy driver For information about the memory usage of a Device driver specific uC FS device driver refer to the Unit number section of the respective driver in the Device drivers on page 141 Table 9 1 Arm7 sample configuration 9 1 2 File system configu
168. guired Checks if a device is low level formatted and formats it if reguired FS FormatLow Low level formats a device FS Format High level formats a device File system extended functions FS GetFileSize Retrieves the current file size of a given file pointer FS GetNumVolumes Retrieves the available volumes FS GetFreeSpace Gets amount of free space on drive FS GetTotalSpace Gets total amount of drive space FS GetVolumeFreeSpace Gets the free space of a given volume Get volume information clusters sectors FS GetVolumeInfo etc FS GetVolumeLabel Retrieves the label of a given volume index Retrieves the name of a given volume FS GetVolumeName index FS GetVolumeSize Gets the size of a given volume FS GetVolumeStatus Returns the status of a volume ne anne Returns if the volume is mounted and has correct file system information FS FileTimeToTimeStamp Converts a file time to a timestamp FS SetBusyLEDCallback Sets a BusyLED callback for a specific vol ume FS SetVolumeLabel Sets a label to a specific volume FS TimeStampToFileTime Converts a timestamp to a file time Storage layer functions FS STORAGE GetDevicelnfo Returns the device info FS STORAGE Init Initializes the driver and OS if necessary FS STORAGE ReadSector Reads a sector from a device FS STORAGE R
169. har s Parameter Meaning s Pointer to the string to be sent Table 8 1 FS_X_Log parameter list Example sample using ANSI C printf function U16 FS_X_Log const char s printf s s User s amp reference manual for yC FS 2004 2007 Micrium 285 8 2 FS_X_Warn Description Outputs warnings from uC FS This function has to integrated into your application if FS DEBUG LEV tion chapter fo Prototype EL gt 4 Refer to section Debugging on page 275 of the Configura r further information about the different debug level void FS X Warn const char s Parameter Meaning S Pointer to the string to be sent Table 8 2 FS X Warn parameter list Example sample using ANSI C printf function U16 FS X Warn const char s printf s s User s amp reference manual for uC FS 2004 2007 Micrium 286 CHAPTER 8 Debugging 8 3 FS X ErrorOut Description Outputs errors from uC FS This function has to integrated into your application if FS DEBUG LEVEL gt 3 Refer to section Debugging on page 275 of the Configura tion chapter for further information about the different debug level Prototype void FS X ErrorOut const char s Parameter Meaning S Pointer to the string to be sent Table 8 3 FS X ErrorOut parameter list Example sample using ANSI C
170. he FAT file system or an optional file system called EFS are available for uC FS Right now they cannot be used simultaneously The Storage API declares the functions which are reguired to initialize and access a storage medium The Storage API allows sector read and write operations The API Layer transfers these calls to the Storage Layer The Storage API is optimized for applications which do not reguire file system functionality like file and directory handling A typical application which uses the Storage API could be a USB mass storage device where data has to be stored on a medium but all file system functionality is handled by the host PC File System Layer The file system layer translates file operations to logical block sector operations After such a translation the file system calls the logical block layer and specifies the corresponding device driver for a device User s amp reference manual for uC FS 2004 2007 Micrium CHAPTER 1 Introduction to uC FS Storage Layer The main purpose of the Storage Layer is to synchronize accesses to a device driver Furthermore it provides a simple interface for the File System API The Storage Layer calls a device driver to perform a block operation It also contains the cache mechanism Device Driver Device drivers are low level routines that are used to access sectors of the device and to check status It is hardware independent but depends on the storage medium Hardware Lay
171. he MultiMedia A SD card slot Prototype char FS MMC HW X SetVoltage U8 Unit U16 Vmin U16 Vmax Parameter Meaning Unit Unit number 0 N Vmin Minimum supply voltage in mV Vmax Maximum supply voltage in mV Table 5 45 FS MMC HW X SetVoltage parameter list Return value 1 Card slot works within the given range 0 Card slot cannot provide a voltage within given range Additional Information The values are in mill volts mV 1mV is 0 001V All cards work with the initial volt age of 3 3V If you want to save power you can adjust the card slot supply voltage within the given range of Vmin and Vmax Example define FS MMC DEFAULTSUPPLYVOLTAGE 3300 example means 3 3V char FS MMC HW X SetVoltage U8 Unit U16 Vmin U16 Vmax voltage range check char r if Vmin lt MMC DEFAULTSUPPLYVOLTAGE amp amp Vmax gt MMC DEFAULTSUPPLYVOLTAGE F M else F return r User s amp reference manual for uC FS 2004 2007 Micrium 200 CHAPTER 5 Device drivers 5 4 6 5 FS_MMC_HW_X_IsWriteProtected Description Checks the status of the mechanical write protection of a SD card Prototype char FS_MMC_HW_X_IsWriteProtected U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 46 FS MMC HW X IsWriteProtected parameter list Return value 0 If the card is not write protected 1 Means that the card is write protected
172. he NOR flash driver with a single device AK KXAZXXAZAZA AAA A AA AA A HZ A AZ KZ A K AZ AZ AZ AX A ZAZ A X AZ A KZ A ZAZ A KZ KZ AZ XZ AZ Z KZ A ZAZ A X AZ ZK A ZK A ZA AZ K K 7 define ALLOC_SIZE 0x10000 Size of memory dedicated to the file system This value should be fine tuned according for your system define FLASHO BASE ADDR 0x40000000 Base addr of the NOR flash device to be used as storage define FLASHO START ADDR 0x40000000 Start addr of the first sector be used as storage If the entire chip is used for file system it is identical to the base addr define FLASHO SIZE 0x200000 Number of bytes to be used for storage KERR RERERRR RRR E KERR ERE EEE REE ERE RRR EKER ERE EKER REE KE kkk kkk kk kkk kkk kkk kkk Public code This section does not require modifications in most systems KKEKKKKKKKKKKKKKKK KKK KKK KEKE KKK KKK KKK KKK KK KKK KKK KK Z KZ A KKK XZ AZ ZK A ZK A ZZ AZ K K RRR RREKREERR REE ERR ERE ERE ERE RE RRR KER EERE REE EKER REE KER EERE REE RRKEKREKEEKRE KE FS X AddDevices Function description This function is called by the FS during FS_Init It is supposed to add all devices using primarily FS_AddDevice void FS X AddDevices void Add driver FS AddDevice 4FS NOR Driver Confgure the NOR flash interface FS NOR SetPhyType 0 amp FS_NOR_PHY_CFI_1x16 FS NOR Configure 0 FLASHO BASE ADDR
173. he application the same way as single device with the combined capacity Prototype int FS LOGVOL Create const char sVolName Parameter Description sVolName Name for the logical volume Table 4 8 FS LOGVOL Create parameter list Additional Information Normally all devices are added indi vidually using FS AddDevice This function adds the devices physically NAND devices 4x1 Gbyte and logically to the file system this means that every 1 Gbyte NAND devices can be accessed individu ally Refer to FS AddDevice on page 42 for detailed information In contrast to adding all devices individually all devices can be com bined in a logical volume with a total size of all combined devices To create a logical volume the fol lowing steps have to be done NAND device 1x4 Gbytes 1 The available device has to be physi cally added to the file system with FS AddPhysDevice 2 A logical volume has to be cre ated with FS LOGVOL Create 3 The devices which are physically added to the file system has to be added to the logical volume with FS LOGVOL AddDevice User s amp reference manual for uC FS 2004 2007 Micrium 46 CHAPTER 4 4 3 4 FS LOGVOL AddDevice API functions Description Adds a device to a logical volume Prototype int FS LOGVOL AddDevice const char sLogVolName const FS DEVICE TYPE pDevice U8 Unit U32 Startoff U32 NumSect
174. he device If not specified unit O will be used Note that to specify UnitNum also DevName has to be specified User s amp reference manual for uC FS 2004 2007 Micrium 96 CHAPTER 4 API functions 4 9 10 FS_GetVolumeStatus Description Returns the status of a volume Prototype int FS GetVolumeStatus const char sVolume Parameter Description sVolume Volume name as a string Table 4 60 FS GetVolumeStatus parameter list Return Value Return value Description FS MEDIA STATE UNKNOWN The volume state is unknown FS MEDIA NOT PRESENT A volume is not present FS MEDIA IS PRESENT A volume is present Table 4 61 FS GetVolumeStatus list of return values User s amp reference manual for uC FS 2004 2007 Micrium 97 4 9 11 FS_IsVolumeMounted Description Returns if a volume was succesfully mounted and has correct file system information Prototype int FS IsVolumeMounted const char sVolumeName Parameter Description sVolumeName Volume name as a string Table 4 62 FS IsVolumeMounted parameter list Return Value 1 If volume information is mounted 0 In case of error for example if the volume could not be found is not detected or has incorrect file system information Example include FS h include lt stdio h gt void MainTask void if FS IsVolumeMounted ram printf Vol
175. high this signal Resets the Com pactFlash Storage Card or CF Card The Compact Flash Storage Card or CF Card is reset only at power up if this pin is left high or open from power up 5 V 3 3 V power Voltage Sense Signals VS1 is grounded so that the CompactFlash Storage Card or CF Card CIS can be read at 3 3 volts and VS2 is reserved by PCMCIA for a secondary voltage The WAIT signal is driven low by the CompactFlash Storage Card or CF Card to signal the host to delay completion of a memory or I O cycle that is in progress This is a signal driven by the host and used for strobing memory write data to the registers of the CompactFlash Storage Card or CF Card when the card is configured in the memory interface mode The CompactFlash Storage Card or CF Card does not have a write protect switch This signal is held low after the completion of the reset initialization seguence Table 5 72 Pin functions in memory card mode Continued User s amp reference manual for uC FS 2004 2007 Micrium 230 CHAPTER 5 Sample block schematic 20 OPENED CFAI 19 CFA2 18 CFA3 17 CFGND CFVCC 100n 100n 100n 32 CFRD 9 34 CFVCC CFWRL 36 CFRDY 37 OFVCC F AO po 21 CFDO A4 pq 22 CDI 23 CFD2 A2 D2 2 CFD3 A3 D3 3 CFD4 A4 D4 4 CFD5 A5 D5 5 CFD6 A6 D6 6 CFD7 A7 D7 47 CFD8 A8 D8 48 CFD9 A9 D9 A10 D10 44 CFDI0 D14 27 CFDU D12 28 CFDI2 p13 29 CFD D14 30 CFD14 D
176. his case the physical layer will perform a software status check of the device or wait for the time reguired by the current operation Example int FS NAND HW X WaitWhileBusy U8 Unit unsinged us int IsReady do IsReady NAND GET RDY 0 1 while IsReady 0 return IsReady User s amp reference manual for uC FS 2004 2007 Micrium 173 5 3 7 7 FS NAND HW X Read x8 Description Reads data from an 8 bit NAND flash device using the I O 0 7 lines Prototype void FS NAND HW X Read x8 U8 Unit U8 pBuffer unsigned NumBytes Parameter Meaning Unit Unit number 0 N pBuffer Pointer to a buffer to store the read data NumBytes Number of bytes that should be stored into the buffer Table 5 25 FS NAND HW X Read x8 parameter list Additional Information When reading from the device usually you will not have to take care of handling the RE line because that is done automatically by the hardware If you do have to control the RE line make sure that timing is according to your NAND flash device specification Example void FS NAND HW X Read x8 U8 Unit U8 pBuffer unsigned NumBytes SET_DATA2 INPUT do NAND CLR RE RE is active low NAND GET DATA pBuffer pBuffer NAND SET RE disable RE while NumBytes User s amp reference manual for uC FS 2004 2007 Micrium 174 CHAPTER 5 Device drivers
177. i 15 4 Running uC FS on target MAL WANC Luminaire die 21 4 1 Step 1 Creating a simple project without HC FS 23 4 2 Step 2 Adding UC FS to the start project c lt sstrrrrer 24 4 3 Step 3 Adding the device drivers Frkal cereals corer Prin annee derange 26 4 4 Step 4 Activating the driver 00000000 ea aa K K K tk 29 4 5 Step 5 Adjusting the RAM usage 32 5 APIUNONONS essene prep ebene aktu sedat hi rites Patient te ennemie insu 33 5 1 APL function OVERVIEW sis uk ubit ei een T O ie 34 5 2 File system control functions sisi ses n rr nn 37 5 3 File system configuration functions ss 42 5 4 File access TUnetior S35 dada dod LU a de et set nn ede 47 5 5 File POSITIONING FUNCTIONS katka koa tee te ane Lana ea eue A ee e da 54 5 6 Operations on fil S 32m ztex ida Ka deh etl teases REG nA A Ko C enr OR dee dazed tte leans 58 5 7 Directory sTunctions 334988438 a TO TR AR 0 AO V a ee ore ooo oa 72 5 8 Formatting a Med see zk dane See Stee Va Kaln drame hk K a ejka ana j 78 5 9 Extended functions eine aaa obsa ua d od ata u A o a 86 5 10 Storage layer FUNCTIONS 4 ties 452 din ran cepted ave s dana E eee ne anoda S Ae pe nas aan ad ena 102 5 11 FAT relat difUNCtIOns ses tosis Perio vont RSR GE M PA REA M TR 110 5 12 File system cache functions EEE EERE EEE EE Ee 115 5 13 Error handling functions sk kat ak dea da r la Lane Cedi aca des 122 5 14 Obsolete functions sisi DEEDS EES HDDS EEE ESSE SEES S
178. ialization they behave the same way MMC and SD cards also differ in the count of pins SD cards have more pins than MMCs Depending in which mode they are used the pins are used or not Additionally SD cards have a write protect switch which can be used to lock the data on the card In MMC SD card mode MultiMedia Cards use a seven pin interface in MultiMedia card mode Command Clock Data and 3x Power lines In contrast to the MultiMedia cards SD cards use a 9 pin interface Command Clock 1 or 4 Data and 3 Power lines In SPI mode Both card systems use the same pin interface ChipSelect CS Dataln DataOut Clock and 3 power lines User s amp reference manual for uC FS 2004 2007 Micrium 189 5 4 1 1 Pin description for MMC SD card in Card mode Pin a No Name Type Description Card Detect Data line Bit 3 Input Out After power up this line is input with 50 kOhm pull up CD put resistor This can be used for card detection relevant DAT 3 using push only for SD cards The pull up resistor is disabled after pull drivers the initialization procedure for using this line as DAT3 Data line Bit 3 for data transfer Command Response CMD is a bidirectional command channel used for card initialization and data transfer commands The CMD 5 CMD Push Pull signal has two operation modes open drain for initial ization mode and push pull for fast command transfer Commands are sent from the Multi
179. iceInfo const char sVolume FS DEV INFO pDevInfo Parameter Description sVolume Name of the device to check p DevicelInfo Pointer to a data structure of type FS D I V INFO Table 4 95 FS GetDeviceInfo parameter list Additional information This function is obsolete Use instead FS STORAGE GetDeviceInfo on page 102 Return Value 0 Ok User s amp reference manual for uC FS 1 Device is not ready or a general error has occured 2004 2007 Micrium 132 CHAPTER 4 API functions 4 14 7 FS GetNum Files Description Returns the number of files in a directory opened by FS OpenDir Prototype U32 FS GetNumFiles FS DIR pDir Parameter Description pDir Pointer to a FS_FILE data structure Table 4 96 FS GetNumrFiles parameter list Return value Number of files in a directory OxFFFFFFFF as return value indicates an error Additional Information If pDir is valid the number of files in the directory will be returned To get a valid pointer FS OpenDir should be called before using FS GetNumFiles Refer to FS_OpenDir on page 134 for more information Example void NumFilesInDirectory void U32 NumFilesInDir FS DIR pDir pDir FS OpenDir Open root directory of default device NumFilesInDir FS GetNumFiles pDir if NumFilesInDir char ac 50 sprintf ac NumFilesInDir
180. icrium 10 4 Device driver 10 4 1 Renamed drivers Old driver names Driver names in uC FS version 3 x In uC FS version 3 x the NAND driver could be used to NAND2K access small and large block NAND flashes similarly The driver is therefore renamed from NAND2K to NAND In uC FS version 3 the SMC small block NAND driver is integrated in the NAND driver The NAND driver could be ae used to access small and large block NAND flashes simi larly SFLASH The serial flash driver is renamed into DataFlash driver FLASH FLASH driver renamed to NOR flash driver Table 10 4 Differences between uC FS v 2 x v 3 x list of renamed device drivers 10 4 2 Integrating a device driver into uC FS In version 2 x you have to enable a device driver with a macro which has to be set has to be set in the uC FS configuration file FS_Conf h and recompile your file sys tem project uC FS version 3 x is run time configurable so that you can add all device drivers by calling the FS_AddDevice function with the proper parameter for the accordant driver In version 3 x removed macros FS USE FLASH DRIVER FS AddDevice FS USE IDE DRIVER FS AddDevice FS AddDevice FS AddDevice FS USE RAMDISK DRIVER FS AddDevice FS USE SFLASH DRIVER FS AddDevice FS USE SMC DRIVER FS AddDevice FS NAND Driver FS USE NAND2K DRIVER FS AddDevice FS NAND Driver FS USE WINDRIVE DRIVER FS AddDevice 8FS WINDRIVE Driver Table 10 5 D
181. id pDirEnt NULL break No more sprintf _acBuffer s n acName FS_X_Log _acBuffer while 1 rewind to 1st entry FS_RewindDir dirp display directory again do pDirEnt FS_ReadDir pDir the current DirEntry files or directories FS_DirEnt2Name pDirEnt acDirName Get name of the current DirEntry if void pDirEnt NULL break No more files or directories sprintf _acBuffer s n acName FS_X_Log _acBuffer while 1 Le FS CloseDir pDir else FS_X_ErrorOut Unable to open directory n User s amp reference manual for uC FS 2004 2007 Micrium 138 CHAPTER 4 API functions 4 14 10 FS_UnmountLL Description Unmounts a given volume at driver layer Sends an unmount command to the driver marks the volume as unmounted and uninitialized Prototype void FS_Unmount const char sVolume Parameter Description sVolume is the name of a volume If not specified the first device in the volume table will be used Table 4 101 FS_UnmountLL parameter list sVolume Additional information This function is obsolete Use instead FS_STORAGE_Init on page 103 User s amp reference manual for uC FS 2004 2007 Micrium 4 14 11 FS_WriteSector Description Writes a sector to a device Prototype int FS_WriteSector const char sVolume const void pData U32 SectorIndex
182. ifferences between uC FS v 2 x v 3 x adding a driver Alternative 4FS NOR Driver amp FS_ IDE Driver amp FS MMC SPI Driver FS MMC CardMode Driver FS RAMDISK Driver amp FS_DataFlash_ Driver FS USE MMC DRIVER alallala la alala User s amp reference manual for uC FS 2004 2007 Micrium 300 CHAPTER 10 Porting uC FS 2 x to 3 x 10 4 3 RAM disk driver differences In version 3 x Alternative removed macros FS_USE_RAMDISK_DRIVER FS_AddDevice amp FS RAMDISK Driver FS RAMDISK NUM SECTORS FS RAMDISK Configure Refer to FS RAMDISK MAXUNIT FS_RAMDISK_Configure on page 144 for detailed FS RAMDISK ADDR information FS RAMDISK SECTOR SIZE Table 10 6 Differences between uC FS v 2 x v 3 x removed RAMDISK macros Refer to the section RAM disk driver on page 143 for detailed information about the RAM disk driver in uC FS version 3 x 10 4 4 NAND driver differences In version 3 x Alternative removed macros FS USE NAND2K DRIVER FS AddDevice FS NAND Driver FS NAND2K MAXUNIT FS NAND SetPhyType Refer to FS NAND SetPhyType on page 155 for detailed infor mation
183. inter to a string that names an existing file or directory Pointer to a string that specifies the name of the new file or directory Table 4 27 FS Move parameter list sNewName Return value 0 If the file was successfully moved 1 In case of any error Additional Information Valid values for sExistingName and sNewName are the same as for FS FOpen Refer to FS_FOpen on page 48 for examples of valid names The FS Move function will move either a file or a directory including its children either in the same direc tory or across directories The file or directory you want to move has to be on the same volume Example void MainTask void FS Move subdirl subdir2 subdir3 User s amp reference manual for uC FS 2004 2007 Micrium 63 4 6 6 FS Removef Description Removes an existing file Prototype int FS Remove const char pName Parameter Description pName Pointer to a string that specifies the file to be deleted Table 4 28 FS Remove parameter list Return value 0 If the file was successfully removed 1 In case of any error Additional Information Valid values for pName are the same as for FS FOpen Refer to FS FOpen on page 48 for examples of valid names Example void MainTask void FS Remove test txt User s amp reference manual for uC FS 2004 2007 Micrium 64 CHAPTER 4 4 6 7 FS_Rename
184. ion FS AddDevices is used to add and configure the used device drivers to the file system In the example configuration only the RAM disk driver is added FS Init must be called before using any other uC FS function You should step over this function gt FS Start Microsoft Visual C break IC Application main c e Ja cS TS Ss Globals All global members e FSTask Workspace FS Stat 1 project s void ESTosk ae U32 FS Init if pFile FS Write pFile else A Extemal Dependencies while 1 FS_FILE p i le char ac 256 const char sVolName printf Running sample on s n v FS_GetVolumeFreeSpace sVolName printf Free space d bytes n sprintf ac s File txt printf Write test data to file s n pFile FS FOpen ac w hs printf Could not open file Xs to write n w FS GetYolumeFreeSpace sVolNane printf Free space d bytes n printf Finished n Figure 2 2 FS_Start project FSTask 3 If the initialisation was successfully the volume name is printed in the console window 4 The uC FS function FS_GetFreeSpace is called and the return value is written into the console window User s amp reference manual for uC FS 2004 2007 Micrium 18 CHAPTER 2 Getting Started 5 Afterwards you should get to the uC FS function call FS FOpen This function creates a file named
185. ion Memory footprint updated Chapter Device drivers NAND Pin description updated NAND Illustrations added NOR Illustrations added Chapter Introduction 3 08 R4 070716 SK uC FS structure picture changed Layer description updated Chapter API functions FS_InitStorage updated FS_ReadSector added 3 08 R3 070703 SK FS_WriteSector added FS_GetDevicelnfo added Chapter Index Index updated Chapter Device driver NAND flash driver section enhanced Chapter API functions FS UnmountLL added 3 08 R1 070618 SK FS GetVolumeStatus added FS InitStorage added Chapter Porting uC FS 2 x to 3 x chapter 3 10 RO 070927 SK 3 08 R5 070719 SK 3 08 R2 070703 SK User s A reference manual for uC FS 2004 2007 Micrium Manual version Date By Explanation Chapter Introduction Section Development environment added Chapter API functions updated FS_Mount added FS SetAutoMount added FS UnmountForced added Various improvements Chapter Running uC FS on target hardware updated Structural changes Section Adjusting the RAM usage added Chapter API functions updated 3 04 RO 070427 SK Samples updated Chapter Device driver updated Generic flash driver renamed to NOR flash driver FS FLASH replaced with FS NOR NOR additional driver functions added DataFlash driver added Chap
186. ir parameter list ee FS ReadSector parameter list FS RewindDir parameter list FS UnmountLL parameter list FS WriteSector parameter list List of default device driver labels FS RAMDISK Configure parameter list List of supported NAND flashes List of supported serial flash devices NAND flash pin description DataFlash chip pin function description NAND driver specific configuration functions FS NAND SetPhyType parameter list FS NAND SetBlockRange parameter list NAND device driver physical layer functions pfEraseBlock parameter list pfInitGetDeviceInfo parameter list pfIsWP parameter list pfRead parameter list pfReadEx parameter list pfWrite parameter list pfWriteEx parameter list NAND device driver hardware layer functions FS NAND HW X SetAddrMode parameter list FS NAND HW X SetCmdMode parameter list FS NAND HW X SetDataMode parameter list FS NAND HW X DisableCE parameter list FS NAND HW X EnableCE parameter list FS NAND HW X WaitWhileBusy parameter list FS NAND HW X Read x8 parameter list 2004 2006 Micrium Table 5 26 Table 5 27 Table 5 28 Table 5 29 Table 5 30 Table 5 31 Table 5 32 Table 5 33 Table 5 34 Table 5 35 Table 5 36 Table 5 37 Table 5 38 Table 5 39 Table 5 40 Table 5 41 Table 5 42 Table 5 43 Table 5 44 Table
187. iver side User s amp reference manual for uC FS 2004 2007 Micrium 154 CHAPTER 5 Device drivers 5 3 2 2 Software structure The NAND Flash driver is split up into different layers which are shown in the illus tration below Port pin Memory controller any hardware simple e g special FPGA memory controller implementations It is possible to use the NAND driver with custom hardware If port pins or a simple memory controller are used for accessing the flash memory only the hardware layer needs to be ported normally no changes to the physical layer are required If the NAND driver should be used with a special memory controller for example special FPGA implementations the physical layer needs to be adapted In this case the hardware layer is not required because the memory controller manages the hard ware access 5 3 3 Fail safe operation The uC FS NAND driver is fail safe That means that the driver makes only atomic actions and takes the responsibility that the data managed by the file system is always valid In case of a power loss or a power reset during a write operation it is always assured that only valid data is stored in the flash If the power loss interrupts the write operation the old data will be kept and the block not corrupted 5 3 4 Wear leveling Wear leveling is supported by the driver Wear leveling makes sure that the number of erase cycles remains approximately egual for each sector Maximu
188. kkk kkk kkk Public code RRKEKKREKKEKR ERE RE KER EKER KERR ER EEE KE RE KE RK EERE EKER ER ERE REE KRKEKREREEREKEREREE EE BERR RKK kkk kkk k kkk kkk kkk kkk kk RE ER kk kk kk kkk kkk kkk EKER KERR ERE kk k k k kkk k kk k main x void main void kif STEP gt 1 Step 1 Minimum file system FS FILI pFile FS Init pFile FS FOpen File txt w FS FClose pFile endif if STEP gt 2 Step 2 Write a file FS Write pFile Test 4 endif if STEP gt 3 Step 3 Remove a file FS Remove File txt endif if STEP gt 4 Step 4 Open a directory FS FIND DATA fd FS_FindFirstFile amp fd YourDir File txt 8 FS_FindClose amp fd endif if STEP gt 5 Step 5 Create a directory FS MkDir endif if STEP gt 6 Step 6 Add long file name support FS FAT SupportLFN endif kif STEP gt 7 Step 7 Low level format a medium FS FormatLow endif if STEP gt 8 Step 8 High level format a medium FS Format NULL endif if STEP gt 9 Step 9 Assign cache Cache module FS CACHE ALL FS AssignCache NULL 0 FS CACHE ALL FS AssignCache NULL 0 FS CACHE MAN FS AssignCache NULL 0 FS CACHE RW FS AssignCache NULL 0 FS CACHE RW OUOTA endif if STEP gt 10 Step 10 Checkdisk FS FAT CheckDisk NULL 0 0 NULL endif Kif STEP gt 11 Step 11 Get device info FS_GetDeviceInfo NULL endif kif STEP gt
189. llowed to specify UnitNum if DevName has not been spec ified e DirPathList is a complete path to an existing subdirectory The path must start and end with a character Directory names in the path are separated by If DirPathList is not specified the root directory on the device will be used e DirectoryName and all other directory names have to follow the standard FAT naming conventions for example 8 3 notation if support for long file names is not enabled To open the root directory simply use an empty string for sPath Refer to Structure FS_FIND_DATA on page 77 for more information about the structure pfd points to Example Refer to FS_FindClose on page 72 for an example User s A reference manual for uC FS 2004 2007 Micrium 74 4 7 3 FS FindNextFile CHAPTER 4 API functions Description Continues a file search from a previous call to the FindFirstFile function Prototype int FS FindNextFile FS FIND DATA pfd Parameter Description pfd Pointer to a FS_FIND_DATA structure Table 4 40 FS_FindNextFile parameter list Return value 1 File found in directory 0 In case of any error Example Refer to FS_FindClose on page 72 for an example User s amp reference manual for uC FS 2004 2007 Micrium 75 47 4 FS MkDir Description Creates a new directory Prototype int FS MkDir const ch
190. lu n NumFilesInDir FS X Log ac User s amp reference manual for uC FS 2004 2007 Micrium 133 4 14 8 FS InitStoragef Description This function only intializes the driver and OS if necessary Prototype void FS InitStorage void Return value The return value indicates the high level init how many drivers can be used at the same time The function will accordingly allocate the sector buffers that are necces sary for a file system operation Additional information If FS InitStorage is used to initialize a driver only the hardware layer functions FS ReadSector FS WriteSector and FS GetDeviceInfo are available This function is obsolete Use instead FS STORAGE Init on page 103 User s amp reference manual for uC FS 2004 2007 Micrium 134 CHAPTER 4 API functions 4 14 8 1 FS_OpenDir Description Opens an existing directory for reading Prototype FS DIR FS OpenDir const char pDirname Parameter Description pDirName Fully gualified directory name Table 4 97 FS OpenDir parameter list Return value Returns the address of an FS DIR data structure if the directory was opened In case of any error the return value is 0 Additional Information A fully gualified directory name looks like DevName UnitNum DirPathList DirectoryName where e DevName is the name of a device for example ram or
191. lume char pVolumeLabel unsigned VolumeLabelSize Parameter Description sVolume Volume name as a string pVolumeLabel Pointer to a buffer to receive the volume label pVolumeLabelSize Size of the buffer which can used to store pVolumeLabel Table 4 57 FS GetVolumeLabel parameter list Return Value gt 0 Number of total bytes available on this volume 1 Failed to get volume information User s amp reference manual for uC FS 2004 2007 Micrium 94 CHAPTER 4 4 9 8 FS GetVolumeNamef API functions Description Retrieves the name of the specified volume index Prototype int FS GetVolumeName int Index char pBuffer int BufferSize Parameter Description Index Index number of the volume RE Pointer to a buffer that receives the null terminated string for the Pao volume name Size of the buffer to receive the null terminated string for the vol BufferSize ume name Table 4 58 FS GetVolumeName parameter list Return Value If the function succeeds the return value is the length of the string copied to pBuffer excluding the terminating null character in bytes If the pBuffer buffer is too small to contain the volume name the return value is the size of the buffer reguired to hold the volume name plus the terminating null charac ter Therefore if the return value is greater than BufferSize make sure to call the function again with a b
192. ly efficient The driver is designed to support one or multiple SLC Single Level Cell NAND flashes The NAND flash driver can also be used to access ATMEL s DataFlash chips To use it in your system you will have to provide basic I O functions for accessing your flash device This section first describes which devices are supported and describes all hardware access functions reguired by the NAND flash driver NAND flash organization A NAND flash is a serial type memory device which utilizes the I O pins for both address and data input output as well as for command inputs The erase and pro gram operations are automatically executed To store data on the NAND flash device it has to be low level formatted NAND flashes consist of a number of blocks Every block contains a number of sec tors typically 64 The sectors can be written to individually one at a time When writing to a sector bits can only be written from 1 to 0 Only whole blocks all sec tors in the block can be erased Erasing means bringing all memory bits in all sec tors of the block to logical 1 Small NAND flashes up to 256 Mbytes have a page size of 528 bytes 512 for data 16 spare bytes for storing relevant information ECC etc to the page Large NAND devices 256 Mbytes or more have a page size of 2112 bytes 2048 bytes for data 64 bytes for storing relevant information to the page NAND flash organization lt Spare Area Block n User s amp
193. m erase count difference is set to 5 This value specifies a maximum difference of erase counts for different physical sectors before the wear leveling uses the sector with the lowest erase count User s amp reference manual for uC FS 2004 2007 Micrium 155 5 3 5 Configuring the driver 5 3 5 1 Adding the driver to pC FS To add the driver use FS AddDevice with the driver label FS NAND Driver This function has to be called from within FS X AddDevices Refer to FS_X_AddDevices on page 262 for more information Example void FS X AddDevices void FS AddDevice 4FS NAND Driver FS NAND SetPhyType 0 FS NAND PHY x8 Set the physical interface of the NAND flash FS NAND SetBlockRange Unit 2 128 Skip 2 blocks 256 Kbytes in case of 2K device Size is 128 blocks For 2k devices this means 2 Kbytes 64 128 16 Mbytes 5 3 5 2 Driver specific configuration functions Function Description FS NAND SetPhyType Sets the physical type of the device Set a limit on which blocks of the NAND flash can be controlled by the driver Table 5 7 NAND driver specific configuration functions FS NAND SetBlockRange FS NAND SetPhyType Description Sets the physical type of the device NAND flash is organized in pages of either 512 or 2048 bytes and has an 8 bit or 16 bit interface The driver needs to know the cor rect combination of page and interface width
194. m the file Table 4 13 FS Read parameter list Return value Number of bytes read Additional Information If there is less data transferred than specified you should check for possible errors by calling the FS FError function Example char acBuffer 100 void MainTask void FS FILE pFile pFile FS FOpen test txt r if pFile 0 do i FS_Read pFile acBuffer sizeof acBuffer 1 acBuffer i 0 i i 1 printf s acBuffer while i FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 52 CHAPTER 4 API functions 4 4 5 FS_FWrite Description Writes data to an open file Prototype U32 FS FWrite const void pData U32 Size U32 N FS File pFile Parameter Description pData Pointer to data to be written to the file Size Size of an element to be transferred from a data buffer to a file pFile N Number of elements to be transferred to the file Pointer to a data structure of type FS FILE ry Table 4 14 FS_FWrite parameter list Return value Number of elements written Additional Information If there is less data transferred than specified you should check for possible errors by calling the FS_FError function Example const char acText hello world n void MainTask void FS_FILE pFile pFile FS_FOpen test txt if pFile 0
195. ment interface can be found at the Technical Com mittee T13 who is responsible for the ATA standard http www t13 org 5 5 8 Resource usage 5 5 8 1 ROM usage The ROM usage depends on the compiler options the compiler version and the used CPU The memory reguirements of the IDE CF driver displayed in the table have been measured on a system as follows ARM7 IAR Embedded Workbench V4 41A Thumb mode Size optimization ROM Kbytes uC FS IDE CF driver 1 6 5 5 8 2 Static RAM usage Static RAM usage is the amount of RAM required by the driver for variables inside the driver The number of bytes can be seen in a list file Static RAM usage of the IDE CF driver 24 bytes 5 5 9 FAQs None Module User s amp reference manual for uC FS 2004 2007 Micrium 248 CHAPTER 5 Device drivers 5 6 NOR flash driver uC FS supports the use of NOR flashes An optional driver for NOR flashes is avail able The NOR flash driver can work with almost any NOR flash and is extremly effi cient This section first describes which devices are supported and will afterwards describe the configuration and the additional information functions of uC FS s NOR flash driver 5 6 1 Supported hardware The NOR flash driver can be used with almost any NOR flash This includes NOR flashes with 1x8 bit and 1x16 bit parallel interfaces as well as 2x16 bit interfaces in parallel as well as serial NOR flashes Reguirements To
196. meter Meaning Unit Unit number 0 N Table 5 33 FS DF HW X EnableCS parameter list Additional Information The CS signal is used to address a specific DataFlash chip connected to the SPI Enabling is egual to setting the CS line to low Example void FS DF HW X EnableCS U8 Unit SPI CLR CS User s amp reference manual for uC FS 2004 2007 Micrium 182 CHAPTER 5 Device drivers 5 3 8 2 FS DF HW X DisableCSf Description Deactivates chip select signal CS of the specified DataFlash Prototype void FS DF HW X DisableCS U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 34 FS DF HW X DisableCS parameter list Additional Information The CS signal is used to address a specific DataFlash connected to the SPI Disabling is egual to setting the CS line to high Example void FS DF HW X DisableCS U8 Unit SPI SET CS User s amp reference manual for uC FS 2004 2007 Micrium 5 3 8 3 FS DF HW X Init Description Initializes the SPI hardware Prototype int FS DF HW X Init U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 35 FS DF HW X TInit parameter list Return value 0 Initialization was successful 1 Initialization failed Additional Information The FS DF Hw X Init can be used to initialize the SPI hardware As described in the previous secti
197. moval The file or directory is hidden It is not included in an ordinary directory listing The file or directory is read only Applications can read the file but cannot write to it or delete it In case of a directory applications cannot delete it The file or directory is part of or is used exclu sively by the operating system FS ATTR HIDDI tri Z FS_ATTR_RI LE AD ONLY FS ATTR SYSTEM Return value 0 Attributes have been successfully set 0 In case of any error Additional Information Valid values for pName are the same as for FS FOpen Refer to FS FOpen on page 48 for examples of valid names Example void MainTask void U8 Attributes char ac 100 FS SetFileAttributes test txt FS ATTR HIDDEN Attributes FS GetFileAttributes test txt sprintf ac File attribute of test txt d Attributes FS X Log ac User s amp reference manual for uC FS 2004 2007 Micrium 66 CHAPTER 4 API functions 4 6 9 FS SetFileTimef Description The FS SetFileTime function sets the timestamp for a specified file or directory Prototype int FS SetFileTime const char pName U32 TimeStamp Parameter Description pName Pointer to a string that specifies the name of a file or directory TimeStamp Timestamp to be set to the file or directory Table 4 31 FS SetFileTime parameter list Return value 0 The tim
198. n host and card Table 5 52 FS_MMC_HW_X_SetMaxSpeed parameter list Return value Actual frequency in thousand cycles per second kHz 0 if the frequency could not be set Additional Information Make sure your SPI interface never generates a higher clock than MaxFreg specifies You can always run MultiMedia amp SD cards at lower or equal but never on higher fre quencies The initial frequency must be 400kHz or less If the precise frequency is unknown typical for implementation using port pins bit banging the return value should be less than the maximum freguency leading to longer timeout values which is in general unproblematic You have to return the actual clock speed of your SPI interface because uC FS needs the actual frequency to calculate timeout values If the precise freguency is unknown typical for implementation using port pins bit banging the return value should be less than the maximum freguency leading to longer timeout values which is in general unproblematic Example U16 FS MMC HW X SetMaxSpeed U8 Unit U16 MaxFreq U32 Prediv U32 Rate if Freq lt 400 Prediv 8 HCLK 8 where HCLK is 100MHz gt SDClock 12 5 MHz Rate 5 Card clock frequency SDClock 1 lt lt Rate 390kHz else Prediv 5 HCLK 5 where HCLK is 100MHz SDClock 20 MHz Rate 0 Card clock frequency SDClock 1 lt lt Rate 20 MHz ___SDMMC_PREDIV 1 lt lt 5 Use P
199. nOff if OnOff HW SetLED else HW CIrLED void MainTask void FS_FILE pFile FS_Init FS_SetBusyLEDCallback ram amp SetBusy pFile FS_FOpen ram file txt w FS FClose User s amp reference manual for uC FS 2004 2007 Micrium 101 4 9 15 FS_SetVolumeLabel Description Sets a label to a specific volume Prototype int FS SetVolumeLabel const char sVolume char pVolumeLabel Parameter Description sVolume Volume name as a string me Pointer to a buffer with the new volume label NULL indicates that the volume label should be deleted Table 4 67 FS GetVolumeInfo parameter list Return Value 0 On Success 1 In case of any error User s amp reference manual for uC FS 2004 2007 Micrium 102 CHAPTER 4 API functions 4 10 Storage layer functions 4 10 1 FS STORAGE GetDevicelnfo Description Returns the device status Prototype int FS STORAGE GetDeviceInfo const char sVolume FS DEV INFO pDevInfo Parameter Description sVolume Name of the device to check pDeviceInfo Pointer to a data structure of type FS DEV INFO Table 4 68 FS STORAGE GetDeviceInfo parameter list Return Value 0 Ok 1 Device is not ready or a general error has occured User s amp reference manual for uC FS 2004 2007 Micrium 103 410 2 FS
200. nal are 8 10 11 1 used to select the following the I O port address 2 14 15 1 registers within the CompactFlash Storage Card or A10 AO I 6 17 18 1 CF Card the memory mapped port address regis 9 20 ters within the CompactFlash Storage Card or CF Card a byte in the card s information structure and its configuration control and status registers This signal is asserted high as BVD1 is not sup BVD1 I O 46 ported BVD2 1 0 45 This signal is asserted high as BVD2 is not sup ported These Card Detect pins are connected to ground on stp the CompactFlash Storage Card or CF Card They CD1 CD2 O 26 25 are used by the host to determine that the Com pactFlash Storage Card or CF Card is fully inserted into its socket These input signals are used both to select the card 22 and to indicate to the card whether a byte or a word CE1 CE2 I 7 32 operation is being performed CE2 always accesses the odd byte of the word We recommend connect ing these pins together This signal is not used for this mode but should be SRE a grounded by the host 27 31 These lines carry the Data Commands and Status Di5 D00 1 0 47 49 information between the host and the controller 2 6 D00 is the LSB of the Even Byte of the Word D08 is 21 23 the LSB of the Odd Byte of the Word GND 5 Ground INPACK O 43 This signal is not used in this mode IORD I 34 This signal is not used in this mode IOWR I 35 This signal is not used in
201. narians rela ea ele utes ta ones uC FS project Structure st ue Configure the include path eee Add driver sources to project eee Adding template to your project CompactFlash schematic cssccsssccsssescssstssseesseees User s amp reference manual for uC FS 2004 2006 Micrium User s amp reference manual for uC FS 2004 2006 Micrium List of Tables Table title Page Table 1 1 Typographic conventions cx 5 Table 4 1 UC FS API function overview 00042 34 Table 4 2 FS Mount parameter list 38 Table 4 3 FS_SetAutoMount parameter list 39 Table 4 4 FS_Unmount parameter list 40 Table 4 5 FS UnmountForced parameter list 41 Table 4 6 FS AddDevice parameter list 42 Table 4 7 FS AddDevice parameter list 44 Table 4 8 FS LOGVOL Create parameter list 45 Table 4 9 FS LOGVOL AddDevice parameter list 46 Table 4 10 FS FClose parameter list 00 47 Table 4 11 FS_FOpen parameter list 0 48 Table 4 12 FS FRead parameter list 50 Table 4 13 FS Read parameter list ccccccccseeeeesseeeeeeeees 51 Table 4 14 FS FWrite parameter list 52 Table 4 15 FS_Write parameter list 2 53 Table 4 16 FS_FSeek parameter list 2
202. nfigu ration files are a good start to run uC FS out of the box User s amp reference manual for uC FS 2004 2007 Micrium 268 CHAPTER 6 HCIFS Configuration 6 1 Runtime configuration Every driver folder includes a configuration file e g ConfigRamDisk c with imple mentations of runtime configuration functions explained in this chapter These func tions can be customized 6 1 1 Driver handling FS_AddDevices is called by the initialization of the file system from FS Init This function should help to bundle the process of adding and configuring the driver 6 1 1 1 FS X AddDevices Description Helper function called by FS Init to add devices to the file system and configure them Prototype void FS AddDevices void Example KERR REE RE AA kA ERR EKER KERR ERE RE R KR EKR EERE RE EKER REE KE ERE RR ERERRRKEK kk kkk kk FS X AddDevices x void FS X AddDevices void void pRamDisk Allocate memory for the RAM disk pRamDisk FS_Alloc RAMDISK_NUM_SECTORS RAMDISK BYTES PER SECTOR Add driver FS_AddDevice amp FS RAMDISK Driver Configure driver FS RAMDISK Configure 0 pRamDisk RAMDISK BYTES PER SECTOR RAMDISK NUM SECTORS Check if volume is already high level formatted otherwise high level format the volume if FS_IsHLFormatted 0 FS_Format NULL User s amp reference manual
203. nformation FS NOR SetPhyType Refer to PLASH PYTEMODE FS_NOR_SetPhyType on page 249 for FLASH_RELOCATECODE detailed information FS_FLASH_CAN_REWRITE FS_FLASH_LINE_SIZE FS_FLASH_SECTOR_SIZE Table 10 14 Differences between uC FS v 2 x v 3 x removed Flash NOR flash macros Refer to the section NOR flash driver on page 244 for detailed information about the NOR flash driver in uC FS version 3 x 10 4 9 Serial Flash DataFlash differences In version 3 x Alternative removed macros FS USE SFLASH DRIVER FS AddDevice 8FS DataFlash Driver FS SFLASH MAXUNIT Table 10 15 Differences between uC FS v 2 x v 3 x removed Serial Flash DataFlash macros Note Since version 3 10 is the DataFlash support integrated in the NAND flash driver Refer to NAND flash driver on page 147 for detailed information User s amp reference manual for uC FS 2004 2007 Micrium 304 CHAPTER 10 Porting uC FS 2 x to 3 x 10 4 10 Windrive differences In version 3 x Alternative removed macros FS_WD_DEVONAME FS Windrive Configure Refer to FS_WD_DEV1NAME FS_Windrive_Configure on page 255 for detailed information Table 10 16 Differences between uC FS v 2 x v 3 x removed Windrive macros Refer to the section WinDrive driver on page 255 for detailed information about the Windrive driv
204. nformation The file system auto mounts all volumes default in read write mode User s amp reference manual for uC FS 2004 2007 Micrium 40 CHAPTER 4 API functions 4 2 4 FS Unmount Description Closes all file directory handles and unmounts the volume Prototype void FS Unmount const char sVolume Parameter Description sVolume is the name of a volume If not specified the first device in sVolume the volume table will be used Table 4 4 FS_Unmount parameter list Additional Information FS_Unmount should be called before a volume is removed It guarantees that all file handles to this volume are closed and the directory entries for the files are updated This function is also useful when shutting down the system Example include FS h void Shutdown void FS Unmount Close all file handles and unmount the default volume User s amp reference manual for uC FS 2004 2007 Micrium 41 4 2 5 FS UnmountForced Description Invalidates all file directory handles and unmounts the volume Prototype void FS UnmountForced const char sVolume Parameter Description sVolume is the name of a volume If not specified the first device in the volume table will be used Table 4 5 FS UnmountForced parameter list sVolume Additional Information FS UnmountForced should be called if a volume has been removed before it could be regular unmoun
205. nitialized Prototype void FS STORAGE Unmount const char sVolume Parameter Description sVolume is the name of a volume If not specified the first device in the volume table will be used Table 4 72 FS STORAGE Unmount parameter list sVolume User s amp reference manual for uC FS 2004 2007 Micrium 108 CHAPTER 4 API functions 4 10 7 FS STORAGE WriteSector Description Writes one sector to a device Prototype int FS STORAGE WriteSector const char sVolume const void pData U32 SectorIndex Parameter Description Volume name If not specified the first device in the volume sVolume table will be used pData Pointer to the data which should be written to the device SectorIndex Index of the sector to which data should be written Table 4 73 FS STORAGE WriteSector parameter list Return value 0 On success I 0 On error User s amp reference manual for uC FS 2004 2007 Micrium 109 4 10 8 FS STORAGE WriteSectors Description Writes multiple sectors to a device Prototype int FS STORAGE WriteSectors const char sVolume const void pData U32 FirstSector U32 NumSectors Parameter Description Volume name If not specified the first device in the volume sVolume table will be used pData Pointer to the data which should be written to the device FirstSector Start sector of the write operation
206. normal which means a logical 1 is represented with a high level on the data line and a logical 0 is represented with low level e MultiMedia amp SD cards support different voltage ranges Initial voltage should be 3 3V Power control should be considered when creating designs using the MultiMediaCard and or SD Card The ability to have software power control of the cards makes the design more flexible and robust The host will be able to turn power to the card on or off independent of whether the card is inserted or removed This can improve card initialization when there is a contact bounce during card insertion The host waits for a specified time after the card is inserted before powering up the card and starting the initialization process Also if the card goes into an unknown state the host can cycle the power and start the initialization process again When card access is unnec essary allowing the host to power down the bus can reduce the overall power con sumption User s amp reference manual for uC FS 2004 2007 Micrium 191 Sample schematic for MMC SD card in Card mode Sample schematic for MMC SD card in SPI mode 5 4 2 Theory of operation The Serial Peripheral Interface SPI bus is a very loose de facto standard for control ling almost any digital electronics that accepts a clocked serial stream of bits SPI operates in full duplex sending and receiving at the same time User s amp reference manual for
207. nto the slot Example char FS MMC HW X IsPresent U8 Unit return FS MEDIA STATE UNKNOWN User s amp reference manual for uC FS 2004 2007 Micrium 202 CHAPTER 5 Device drivers 5 4 6 7 FS MMC HW X Read Description Receives a number of bytes from the card Prototype void FS MMC HW X Read U8 Unit U8 pData int NumBytes Parameter Meaning Unit Unit number 0 N pData Pointer to a buffer for data to receive NumBytes Number of bytes to receive Table 5 49 FS MMC HW X Read parameter list Additional Information This function is used to read a number of bytes from the card to buffer memory Example void FS MMC HW X Read U8 Unit U8 pData int NumBytes do c 0 bpos 8 get 8 bits do SPI_CLR_CLK c lt lt 1 if SPI_DATAIN le 1 SPI SET CLK while bpos pData C while NumBytes Timing diagram for read access SPI_CS SPI CLK SPI DIN From SD MMC Data Output Data is read by the CPU on the rising edge of SPI_CLK Data is changed by the CPU on the falling edge of SPI_CLK User s amp reference manual for uC FS 2004 2007 Micrium 5 4 6 8 FS MMC HW X Write 203 Description Sends a number of bytes to the card Prototype void FS MMC HW X Write U8 Unit const U8 pData int NumBytes Parameter Meaning Unit Unit number 0 N pData Pointer to a buffe
208. o out put data during read operations 1 0 I O DATA INPUTS OUTPUTS 8 15 I Og I 015 16 bit flashes only Table 5 5 NAND flash pin description 5 3 1 4 Pin description DataFlashes DataFlash chips are commonly used when low pin count and easy data transfer are required DataFlash devices use the following pins User s amp reference manual for uC FS 2004 2007 Micrium 151 Pin Meaning CS SCLK SI SO ChipSelect This pin selects the DataFlash device The device is selected when CS pin is driven low Serial Clock The SCLK pin is an input only pin and is used to con trol the flow of data to and from the DataFlash Data is always clocked into the device on the rising edge of SCLK and clocked out of the device on the falling edge of SCLK Serial Data In The SI pin is an input only pin and is used to transfer data into the device The SI pin is used for all data input including opcodes and address sequences Serial Data Out This SO pin is an output pin and is used to transfer data serially out of the device Table 5 6 DataFlash chip pin function description Additionally the following requirements need to be fulfilled by your host system e Data transfer width is 8 bit e Chip Select CS sets the card active at low level and inactive at high level e Clock signal must be generated by the target system The serial flash chips are always in slave mode e Bit order require
209. ode ee ba and ALE low for the specified CLE low and ALE low for the specified FS NAND HW X SetDataMode device FS NAND HW X DisableCE Disables CE FS NAND HW X EnableCE Enables CE FS NAND HW X WaitwhileBusy Waits while the device is busy FS NAND HW X Read x8 For 8 bit NAND flashes Reads data from the NAND flash device FS NAND HW X Read x16 For 16 bit NAND flashes Reads data from the NAND flash device For 8 bit NAND flashes FS NAND HW X Write x8 Writing data to the NAND flash using the 1 0 0 7 lines of the NAND flash device For 16 bit NAND flashes FS NAND HW X Write 16 Writing data to the NAND flash using the 1 0 0 15 lines of the NAND flash device FS NAND HW X Delayus Delays for a specified period of time FS NAND HW X Init x8 For 8 bit NAND flashes Initializes the NAND flash device FS NAND HW X Init x16 Far o bit NAND flashes l Initializes the NAND flash device Table 5 18 NAND device driver hardware layer functions User s amp reference manual for yC FS 2004 2007 Micrium 167 5 3 7 1 FS NAND HW X SetAddrMode Description Sets CLE low and ALE high for the specified device Prototype void FS NAND HW X SetAddrMode U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 19 FS NAND HW X SetAddrMode parameter list Additional Information This function is called to start the address data transfer Example void FS NAND HW X SetA
210. oll mode instead of DMA 1 lt lt 4 Enable the Controller Prediv amp 0x0f Set the predivisor value ___SDMMC_RATE Rate Set rate value return Freg User s amp reference manual for uC FS 2004 2007 Micrium 207 5 4 7 2 FS MMC HW X SetResponseTimeOutf Description Sets the card host controller timeout value for receiving response from card Prototype void FS MMC HW X SetResponseTimeOut U8 Unit int Value Parameter Meaning Unit Unit number 0 N ae Number of MMC clock cycles to wait before a response timeout occurs Table 5 53 FS MMC HW X Set ResponseTimeOut parameter list Additional Information This function sets the card host controller timeout value in MMC clock cycles before the card host controller sets a timeout condition when receiving a response from card Example void FS MMC HW X SetResponseTimeOut U8 Unit int Value SDMMC RES TO Value Set the timeout for Card Response User s amp reference manual for uC FS 2004 2007 Micrium 208 CHAPTER 5 Device drivers 5 4 7 3 FS_MMC_HW_X_SetReadDataTimeOut Description Sets the card host controller timeout value for receiving data from card Prototype void FS MMC HW X SetReadDataTimeOut U8 Unit int Value Parameter Meaning Unit Unit number 0 N us Number of MMC clock cycles to wait before a Read Data timeout occurs Table 5 54 FS MMC HW X SetReadDataTim
211. on The SPI should be initialized as follows 8 bit data length MSB should be sent out first CS signal should be initially high The set clock frequency should not exceed the max clock frequency that are specified by the Serial Flash devices Usually 20MHz Example void FS_DF_HW_X_Init U8 Unit SPI_SETUP_PINS User s amp reference manual for uC FS 2004 2007 Micrium 184 CHAPTER 5 Device drivers 5 3 8 4 FS DF HW X Read Description Receives a number of bytes from the DataFlash Prototype void FS DF HW X Read U8 Unit U8 pData int NumBytes Parameter Meaning Unit Unit number 0 N pData Pointer to a buffer for data to be receive NumBytes Number of bytes to receive Table 5 36 FS DF HW X Read parameter list Additional Information This function is used to read a number of bytes from a card to buffer memory Example void FS DF HW X Read U8 Unit U8 pData int NumBytes do c 0 bpos 8 get 8 bits do SPI_CLR_CLK G lt lt dk if SPI DATAIN le 1 SPT SET CLK while bpos pData C while NumBytes User s amp reference manual for uC FS 2004 2007 Micrium 185 5 3 8 5 FS DF HW X Write Description Sends a number of bytes to the card Prototype void FS DF HW X Write U8 Unit const U8 pData int NumBytes Parameter Meaning Unit Unit number 0 N pDa
212. on a specific volume Prototype U32 FS GetVolumeFreeSpace const char sVolume Parameter Description sVolume Pointer to a string that specifies the volume name Table 4 55 FS GetVolumeFreeSpace parameter list Return Value gt 0 Amount of free space in bytes Free space larger than 4 GB is reported as OxFFFFFFFF the maximum value of a U32 0 If the volume cannot be found Additional Information Note that free space larger than four Gbytes is reported as OxFFFFFFFF because a U32 cannot represent bigger values The function FS GetVolumeInfo can be used for larger spaces If you do not need to know if there is more than 4 GB of free space available you can still reliably use FS GetVolumeFreeSpace Valid values for sVolume have the following structure DevName UnitNum where e DevName is the name of a device If not specified the first device in the volume table will be used UnitNum is the number of the unit of the device If not specified unit O will be used Note that to specify UnitNum also DevName has to be specified User s amp reference manual for uC FS 2004 2007 Micrium 92 CHAPTER 4 API functions 4 9 6 FS GetVolumelnfo Description Gets volume information that is the number of clusters total and free sectors per cluster and bytes per sector The function collects volume information and stores it into the given FS DISK INFO structure
213. ontains a single device a RAM disk This should always be the first step to check the proper function of uC FS with your target hard ware We assume that you are familiar with the tools you have selected for your project compiler project manager linker etc You should therefore be able to add files add directories to the include search path and so on It is also assumed that you are familiar with the OS that you will be using in your target system if you are using one In this document the IAR Embedded Workbench IDE is used for all examples and screenshots but every other ANSI C toolchain can also be used It is also possi ble to use make files in this case when we say add to the project this translates into add to the make file Procedure to follow Integration of uC FS is a relatively simple process which consists of the following steps Step 1 Creating a start project without pC FS Step 2 Adding uC FS to the start project Step 3 Adding the device driver Step 4 Activating the driver Step 5 Adjusting the RAM usage User s amp reference manual for uC FS 2004 2007 Micrium 23 3 1 Step 1 Creating a simple project without pC FS We recommend that you create a small hello world program for your system That project should already use your OS and there should be a way to display text on a screen or serial port IAR Embedded Workbench IDE main int Hell lann a Application
214. ors Parameter Description sVolName Name of the logical volume pDevice Pointer to device type that should be added Unit Number of unit that should be added Startoff Offset to define the start of sector range that should be used NumSector Number of sectors that should be used Table 4 9 FS LOGVOL AddDevice parameter list Additional information Only devices with an identical sector size can be combined to a logical volume All additional added devices need to have the same sector size device of the logical volume Example void FS X AddDevices void void pRAM U8 Unit1 Unit2 Add the RAM drives physical to FS Unitl FS_AddPhysDevice amp FS_RAMDISK_Driver Unit2 FS_AddPhysDevice amp FS_RAMDISK_Driver Allocate the required memory and configure the RAM drives TOR RAM TOR RAM PRAM FS Alloc RAMDISK NUM SECTORS RAMDISK BYTES PER SEC1 FS RAMDISK Configure Unitl pRAM RAMDISK BYTES PER SECTOR pRAM FS Alloc RAMDISK NUM SECTORS RAMDISK BYTES PER SEC1 FS RAMDISK Configure Unit2 pRAM RAMDISK BYTES PER SECTOR Create a logical volume to composite the RAM drives FS_LOGVOL_Create ramc Add the devices FS_LOGVOL_AddDevice ramc amp FS_RAMDISK_Driver Unitl 0 0 FS_LOGVOL_AddDevice ramc amp FS_RAMDISK_Driver Unit2 0 if FS_IsHLFormatted ramc
215. otype void FS NAND HW X Delayus unsigned us Parameter Meaning us Time to dwell in ps Table 5 29 FS NAND HW X Delayus parameter list Additional Information The dwell time is specified in us It is the user s responsibility to make sure that this function will at least wait the time specified by us The driver uses this function in situations where a minimum delay time is reguired by the specification of the NAND flash It is called only if the busy pin of the NAND flash cannot be read FS NAND HAS BUSY PIN 0 Example C void FS NAND HW X Delayus unsigned us volatile int i 1 5 us Factor depends on CPU speed while i Example ARM assembly FS NAND HW X Delayus mov R1 10 Factor depends on CPU speed mul RO RO R1 Loop subs RO RO 1 bne Loop BX LR return User s amp reference manual for uC FS 2004 2007 Micrium 178 CHAPTER 5 5 3 7 12 FS NAND HW X Init x8 Description Initializes a NAND flash device with an 8 bit interface Prototype void FS NAND HW X Init x8 U8 Unit Device drivers Parameter Meaning Upit Unit number 0 N Table 5 30 FS_NAND_HW_X_Init_x8 parameter list Additional Information This function is called before any access to the NAND flash device is made Use this function to initialize the hardware Example int FS NAND HW X Init x8 U8 Unit
216. p NumLogSectors Number of logical sectors of the chip NumUsedSectors Number of used sectors of the chip Table 5 89 FS NOR DISK INFO list of structure elements User s amp reference manual for uC FS 2004 2007 Micrium 260 CHAPTER 5 Device drivers 5 6 8 4 Structure FS NOR SECTOR INFO Description The FS NOR SECTOR INFO structure contains physical and logical sector information Prototype typedef struct U32 Off U32 Size U32 EraseCnt U16 NumUsedSectors U16 NumFreeSectors U16 NumEraseableSectors FS NOR SECTOR INFO Members Description Off Offset of the physical sector Size Size of the physical sector EraseCnt Erase count of sector NumUsedSectors Number of used logical sector inside the physical sector NumFreeSectors Number of free logical sector inside the physical sector NumEraseableSectors Number of erasable logical sector inside the physical sector Table 5 90 FS NOR SECTOR INFO list of structure elements User s amp reference manual for uC FS 2004 2007 Micrium 261 5 7 WinDrive driver The purpose of this driver is to run uC FS for test and simulation purposes on a PC running Windows Refer to the chapter Getting started on page 17 for a sample using the WinDrive driver 5 7 1 Supported hardware This driver is compatible with use any Windows logical driver on a Windows NT sys tem Be aware that Win9X is not supported beca
217. p for a specified file or directory Prototype int FS SetFileTimeEx const char pName U32 pTimeStamp int Index Parameter Description pName Pointer to a string that specifies the name of a file or directory pTimeStamp Pointer to a U32 variable that receives the timestamp Index Flag that indicates which timestamp should be set Table 4 33 FS SetFileTimeEx parameter list Permitted values for parameter Index Indicates that the creation timestamp should FS FILETIME CREATE be set MNE A cr Indicates that the access timestamp should be set ___ Indicates that the modify timestamp should FS FILETIME MODIFY e set Return value 0 The timestamp of the given file was successfully set 0 In case of any error Additional Information Values for pName are the same as for FS_FOpen Refer to FS_FOpen on page 48 for examples of valid names A timestamp is a packed value with the following format Bits Description 0 4 Second divided by 2 5 10 Minute 0 59 11 15 Hour 0 23 16 20 Day of month 1 31 21 24 Month January gt 1 February gt 2 etc 25 31 Year offset from 1980 Add 1980 to get current year Table 4 34 FS GetFileTime timestamp format description To convert a timestamp to a FS Filetime structure use the function FS_TimeStampToFileTime on page 98 For more information
218. perations B FS EFS CASE SENSITIVE 0 should be case sensitive define this macro to 1 Table 6 4 EFS configuration macros 6 2 4 OS support uC FS can be used with operating systems For no OS support at all set all of them to 0 If you need support for an additional OS you will have to provide functions described in the chapter OS Integration on page 277 Type Macro Default Description Set this to 1 determines that an operating system should be used When using an operating system generally every file system opera tion is locked by a semaphore When this macro is defined to 1 only one lock is used to lock each file system function Coarse lock granularity If FS_OS_LOCKING is defined to 2 the file system locks on every critical file system opera tion Fine lock granularity Fine lock granularity requires more semaphores B FS OS LOCKING 0 Table 6 5 Operating system support macros Default setting of uC FS is not configured for a multitasking environment User s amp reference manual for uC FS 2004 2007 Micrium 6 2 5 Debugging UC FS can be configured to display debug information at higher debug levels to locate a problem Error or potential problem To display information uC FS uses the logging routines s chapter Debugging on page 283 These routines can be blank they are not required for the functionality of uC
219. physical type Table 5 86 FS NOR SetPhyType parameter list Permitted values for parameter pPhyType One CFI compliant NOR flash chip with 16 bit interface Two CFI compliant NOR flash chip with 16 bit interfaces FS NOR PHY CFI 1x16 FS NOR PHY CFI 2x16 Additional information If you want to access special flash devices for example the internal NOR flash of a microcontroller you can define your own physical type Use the supplied template NOR Phy Template c for the implementation The template is located in the Sam ple Driver NOR directory Note Most NOR flashes cannot be read out during a program erase or identify operation This means that code cannot be read from the NOR flash during a program or erase operation If code which resides in the same NOR flash used for data storage User s amp reference manual for uC FS 2004 2007 Micrium 255 is executed during program or erase a program crash is almost certain To avoid this you have to make sure that routines which program erase or identify are located in RAM and interrupts are disabled The responsibility therefor is on user side Example Refer to FS NOR Configure on page 253 for an example of usage 5 6 6 Hardware functions The NOR flash driver for CFI complant chips does not need any hardware function User s amp reference manual for uC FS 2004 2007 Micrium 256 CHAPTER 5 Device drivers 5 6 7
220. pplication int SizeofFileName FS DIR Dir FS FIND DATA FindFileSample void FS FIND DATA fd char acFilename 20 if FS_FindFirstFile amp fd YourDir acFilename sizeof acFilename 0 do printf acFilename while FS FindNextFile amp fd FS_FindClose amp fd User s amp reference manual for uC FS 2004 2007 Micrium 73 4 7 2 FS FindFirstFile Description Searches files in a specified directory Prototype int FS FindFirstFile FS FIND DATA pfd const char sPath char sFilename int sizeofFilename Parameter Description pfd Pointer to a FS FIND DATA structure Pointer to a string containing the name of a directory which sPath should be scanned Pointer to a buffer used to store the name of a file which has sFilename been found x Size of the buffer which contains the name of a file which has sizeofFilename been found Table 4 39 FS_FindFirstFile parameter list Return value 0 The directory or file found 0 In case of any error Additional Information A fully qualified directory name looks like DevName UnitNum DirPathList DirectoryName where e DevName is the name of a device for example ram or mmc If not specified the first device in the device table will be used UnitNum is the number for the unit of the device If not specified unit O will be used Note that it is not a
221. r 122 FS ErrorNo2Text 125 FS FEof 123 FS FError 124 Extended functions FS FileTimeToTimeStamp 86 FS GetFileSize 87 FS GetFreeSpace 88 FS GetNumVolumes 89 FS GetTotalSpace 90 2004 2007 Micrium 308 FS_GetVolumeFreeSpace 91 FS_GetVolumelnfo 92 FS_GetVolumeName 94 FS GetVolumeSize 95 FS GetVolumeStatus 96 FS IsVolumeMounted 97 FS SetBusyLEDCallback 100 FS SetVolumeLabel 101 FS TimeStampToFileTime 98 FS WriteSector 139 Structure FS FILETIME 99 F FAQs 305 306 FAT configuration 272 FAT related functions FS FAT CheckDisk 110 FS FAT CheckDisk ErrCode2Text 112 FS FAT SupportLFN 114 FS FormatSD 113 File access FS FClose 47 FS FOpen 48 FS FReaa 50 FS FWrite 52 FS Read 51 FS Write 53 File positioning FS FSeek 54 FS FTell 55 FS GetFilePos 56 FS SetFilePos 57 File System API 9 File system configuration FS AddDevice 42 FS AddPhysDevice 44 FS LOGVOL AddDevice 46 FS LOGVOL Create 45 File system control FS Init 37 FS InitStorage 133 FS Mount 38 FS SetAutoMount 39 FS UnmountForcea 41 FS UnmountLL 138 Unmount 40 Formatting a medium FormatLow 82 FS_Format 83 FS_FormatLLifRequired 81 FS_IsHLFormatted 79 FS_IsLLFormatted 80 Structure FS DEV INFO 85 Structure FS FORMAT INFO 84 Function table for device drivers 264 User s amp reference manual for uC FS Index G Getting 13 Getting Started 13 19 I IDE CF HW FS I
222. r numbers by writing it into special head ers It does not matter to the upper layer were the logical sector is stored or how much flash memory is used as a buffer All logical sectors starting with Sector 0 always exist and are always available for user access Using the same NOR flash for code and data Most NOR flashes cannot be read out during a program erase or identify operation This means that code cannot be read from the NOR flash during a program or erase operation If code which resides in the same NOR flash used for data storage is exe cuted during program or erase a program crash is almost certain There are multiple options to solve this 1 Use multiple NOR flashes Use one flash for code and one for data 2 Use a NOR flash with multiple banks which allows reading Bank A while Bank B is being programmed 3 Make sure the hardware routines which program erase or identify the NOR flash are located in RAM and interrupts are disabled User s amp reference manual for uC FS 2004 2007 Micrium 251 Physical interfaces A device can consist of a single or two identical CFI compliant flash interfaces with a 16 bit interface The most common is a CFI compliant NOR flash chip with a 16 bit interface DO D15 Address bus CPU Beside this solution uC FS supports two CFI compliant NOR flash chip with a 16 bit interface which are connected to the same data bus DO D15 Address bus CPU D16 D31 The uC FS NOR
223. r that contains the data to be written to the card NumBytes Number of bytes to write Table 5 50 FS MMC HW X Write parameter list Additional Information This function is used to send a number of bytes from a memory buffer to the card Example void FS MMC HW X Write U8 Unit const U8 pData int NumBytes int i U8 mask U8 data for i data mask O i pDat 0x80 while mask if data SPI_SET else lt NumBytes i ali amp mask DATAOUT SPI CLR DATAOUT PI CLR C PI DELAY PL SET C PI DELAY ask gt gt SnNnnnY LK IG LK D3 1 SPI SET DATAOUT default state of data line is high User s amp reference manual for uC FS 2004 2007 Micrium 204 CHAPTER 5 Device drivers Timing diagram for write access SPI_CS SPI CLK SPI DIN To Data Input of SD MMC S Data is read by the CPU on the rising edge of SPI_CLK Data is changed by the CPU on the falling edge of SPI_CLK User s amp reference manual for yC FS 2004 2007 Micrium 205 5 4 7 Hardware functions Card mode Routine Explanation Operation condition detection and adjusting Sets the SD MMC clock speed The value FS MMC HW X SetMaxSpeed is represented in thousand cycles per second kHz FS M
224. ration The following excerpts of FS Conf h shows the used configuration options define FS OS LOCKING 0 Disable OS support define FS SUPPORT FAT 1 Support the FAT file system if enabled define FS DEBUG LEVEL 0 Set debug level 9 1 3 Sample project We use the following code to calculate the memory resources of commonly used functions You can easily reproduce the measurement when you compile the follow ing sample Build the application listed below and generate a linker listing to get the memory reguirements of an application which only includes startup code and the empty main function Afterwards set the value of the macro STEP to 1 to get the memory reguirement of the minimum file system Subtract the ROM reguirements from STEP 0 from the ROM reguirements of STEP 1 to get the exact ROM reguire ments of a minimal file system Increment the value of the macro STEP to include more file system functions and repeat your calculation include FS h include FS Int h KERR REREE EKER RE ERRERER EEE ERE RK kk kkk kkk kkk kkk kkk kkk kkk kkk kkk kkk kkk kk k k defines configurable User s amp reference manual for uC FS 2004 2007 Micrium 291 RRKKKKREKKEEK ERR K ERK KEKE KK ERE REE EKER EKER KERR RE KERR ERE REE REE EREEREEREKRER ER define STEP 0 Change this line to adjust which portions of code are linked RRR RRREKRERE RR ER KERR REE REE KER KEKE REE KEKE RE RE R ERK RR kkkh kkk kkk kkk
225. reading a sector the driver also reads the ECC stored in the spare area of the sector calculates the ECC based on the read data and compares the ECCs If the ECCs are not identical the driver tries to recover the data based on the read ECC When writing to a page the ECC is calculated based on the data the driver has to write to the page The calculated ECC is then stored in the spare area 5 3 2 1 Error correction code ECC The HC FS NAND driver is highly speed optimized and offers a better error detection and correction than a standard memory controller ECC The ECC is capable of single bit error correction and 2 bit random detection When a block for which the ECC is computed has 2 or more bit errors the data cannot be corrected Standard memory controllers compute an ECC for the complete blocksize 512 2048 bytes The uC FS NAND driver computes the ECC for data chunks of 256 bytes e g a page with 2048 bytes is divided into 8 parts of 256 bytes so the probability to detect and also correct data errors is much higher This enhancement is realized with a very good performance The ECC computation of the uC FS NAND driver is highly optimized so that a performance of 18 Mbytes second can be achieved with a ARM7 running at 48 MHz We suggest the use of the the uC FS NAND driver without the usage of a memory controller because the performance of the driver is very high and the error correc tion is much better if it is controlled from dr
226. ring to this file by calling the uC FS function FS FWrite Step over this function If a problem occurs compare the return value of FS FWrite with the length of the ASCII string which should be writ ten FS FWrite returns the number of elements which have been written If no problem occurs the function uC FS function FS_FClose should be reached FS FClose closes the file handle for file txt Step over this func tion 7 Continue stepping over until you reach the call to the call of FS GetFreeSpace The uC FS function FS GetFreeSpace returns available free drive space in bytes After you step over this function the variable v should have a value greater than zero 8 The return value is written in the console window User s amp reference manual for uC FS 2004 2007 Micrium 19 work emFile 3 output D ebug FS_Start exe 5632 bytes Write test data to file File txt Figure 2 4 FS_Start project console output User s amp reference manual for uC FS 2004 2007 Micrium 20 User s amp reference manual for uC FS CHAPTER 2 Getting Started 2004 2007 Micrium 21 Chapter 3 Running uC FS on target hardware This chapter explains how to integrate and run uC FS on your target hardware It explains this process step by step User s amp reference manual for uC FS 2004 2007 Micrium 22 CHAPTER 3 Running yC FS on target hardware Integrating pC FS The uC FS default configuration c
227. ription Checks whether a card is present or not Prototype char FS MMC HW X IsPresent U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 58 FS MMC HW X IsPresent parameter list Return value Return value Meaning FS MEDIA STATE UNKNOWN State of the media is unknown FS MEDIA NOT PRESENT No card is present FS MEDIA IS PRESENT Card is present Table 5 59 FS MMC HW X IsPresent list of return values Additional Information Usually a card slot provides a hardware signal that can be used for card presence determination The sample code below is for a specific hardware that does not have such a signal Therefore the presence of a card is unknown and you have to return FS MEDIA STATE UNKNOWN Then uC FS tries reading the card to figure out if a valid card is inserted into the slot Example char FS MMC HW X IsPresent U8 Unit GPIO PFDD amp 1 lt lt 5 Set PE 5 as input for card detect signal return __GPIO PFD gt gt 5 amp 1 FS MEDIA NOT PRESENT FS MEDIA IS PRESENT User s amp reference manual for uC FS 2004 2007 Micrium 5 4 7 8 FS MMC_HW_X_GetResponse 213 Description Retrieves the response after sending a command to the card Prototype int FS MMC HW X GetResponse U8 Unit void pBuffer U32 Size Parameter Meaning Unit Unit number 0 N pBuffer Pointer to a buffer for data
228. rn value 0 On success I 0 On error User s amp reference manual for uC FS 2004 2007 Micrium 105 4 10 4 FS STORAGE ReadSectors Description Reads multiple sectors from a device Prototype int FS STORAGE ReadSectors const char sVolume void pData U32 FirstSector U32 NumSectors Parameter Description eon Volume name If not specified the first device in the volume table will be used pData Pointer to a data buffer where the read data should be stored FirstSector First sector to read NumSectors Number of sectors which should be read Table 4 70 FS_STORAGE_ReadSectors parameter list Return value 0 On success I 0 On error User s amp reference manual for uC FS 2004 2007 Micrium 106 CHAPTER 4 API functions 4 10 5 FS STORAGE Sync Description Writes cached data to the storage medium and sends a command to the driver to finalize all pending tasks Prototype void FS STORAGE Sync const char sVolume Parameter Description sVolume Volume name If not specified the first device in the volume table will be used Table 4 71 FS STORAGE Sync parameter list User s amp reference manual for uC FS 2004 2007 Micrium 107 4 10 6 FS STORAGE _Unmount Description Unmounts a given volume at the driver layer The function also sends an unmount command to the driver and marks the volume as unmounted and uni
229. ros Alternative FS USE SMC DRIVER FS AddDevice FS NAND Driver FS SMC MAXUNIT FS NAND SetPhyType Refer to FS NAND SetPhyType on page 155 for detailed infor mation FS BMC MW SUPPORT PENT FS NAND SetBlockRange Refer to TNE_CHECK FS_NAND_SetBlockRange on page 156 for detailed information Table 10 9 Differences between uC FS v 2 x v 3 x adding a driver Hardware interface version 2 x Hardware interface version 3 x FS_SMC_HW_X_SetAddr FS SMC HW X SetCmd FS SMC HW X SetData FS SMC HW X SetStandby FS SMC HW X Vcco f n In uC FS version 3 the SMC small block FS SMC HW X ChkBusy NAND driver is integrated in the NAND FS SMC HW X ChkCardIn driver The NAND driver could be used to FS SMC HW X ChkPower access small and large block NAND FS SMC HW X ChkStatus flashes similarly FS SMC HW X ChkWP Refer to NAND flash driver on page 147 FS SMC HW X DetectStatus for detailed inforamtion about the NAND driver in uC FS version 3 x FS SMC HW X InData FS SMC HW X OutData FS SMC HW X ChkTimer FS SMC HW X SetTimer FS SMC HW X StopTimer FS SMC HW X WaitTimer Table 10 10 Differences between uC FS v 2 x v 3 x IDE driver hardware interface differences Refer to the section NAND flash driver on page 147 for detailed information about the NAND driver in uC FS version 3 x User s amp reference manual for uC FS 2004 2007 Micrium 302 CHAPTER 10
230. rview The screenshot shows the data flow of a correct initialization It has been captured with an oscilloscope User s amp reference manual for uC FS 2004 2007 Micrium 222 CHAPTER 5 Device drivers Verify command transfer Step 2 After sending 8 dummy bytes to the card CS is selected and the GO IDLE STATE command is sent to the card The GO IDLE STATE command is the reset comman dand It sets the card into idle state regardless of the current card state Check output of card Step 3 The card responses to the command with two bytes The SD Card Association defines that the first byte of the response should always be ignored The second byte is the answer from the card The answer to GO IDLE STATE command should be 0x01 This means that the card is in idle state If your card does not return 0x01 check your initialization sequence After the com mand sequence CS has to be deselected User s amp reference manual for uC FS 2004 2007 Micrium 223 Adapter On some evaluation boards the pins required for measuring are not accessible so that an oscilloscope or logic analyzer cannot capture the outputs An adapter which can be inserted between the card slot and the card is the best solution in those situ ations An example adapter is shown below and is available from Micrium Adapter schematics Use the schematic below to build an compatible adapt
231. s a cluster chain just like any other directory is Here BPB_RootEntCnt specifies the count of 32 byte directory entries in the root directory and as the citation says the number of sectors is computed from this value In addition which file system is used depends on the size of the medium that is the number of clusters and the cluster size where each cluster contains one or more sectors Using small cluster sizes for example cluster size 512 bytes one can use FAT32 on media with more than 32 MB FAT16 can address at least 216 clusters with a 512 byte cluster size That is 65536 512 33554432 bytes 32768 KB 32 MB If the media is smaller than or equal to 32 MB or the cluster size is greater than 512 bytes FAT32 cannot be used To actually set a custom root directory size for FAT12 FAT16 one can use the uC FS API function int FS_Format const char pDevice FS_FORMAT_INFO pFormatInfo Where FS FORMAT INFO is declared as typedef struct U16 SectorsPerCluster U16 NumRootDirEntries FS DEV INFO pDevInfo FS FORMAT INFO Set NumRootDirEntries to the desired number of root directory entries you want to store User s amp reference manual for uC FS 2004 2007 Micrium Index Symbols uC FS Add directories 25 Add files 24 Configuration of 26 features of 8 installing 14 Integrating into your system 22 layers 9 uC FS Configuration 267 276 A Add device driver source to projec
232. s most significant bit MSB to be sent out first To setup all these requirements the NAND flash driver will call the function FS_DF_HW_X_Init therefore the function FS DF Hw X Init can be used to ini tialize the SPI bus Refer to FS DF HW X Init on page 183 for further details User s amp reference manual for uC FS 2004 2007 Micrium 152 CHAPTER 5 Device drivers 5 3 1 5 Sample block schematics NAND Flash 0 NAND Flash 1 optional NAND Flash n optional 5 3 2 Theory of operation NAND flash devices are divided into physical blocks and physical pages One physical block is the smallest erasable unit one physical page is the smallest writable unit Small block NAND flashes contain multiple pages One block contain typically 16 32 64 pages per block Every page has a size of 528 bytes 512 data bytes 16 spare bytes Large block NAND Flash devices contain blocks made up of 64 pages each page containing 2112 bytes 2048 data bytes 64 spare bytes The driver uses the spare bytes for the following purposes 1 To check if the data status byte and block status are valid If they are valid the driver uses this sector When the driver detects a bad sector the User s amp reference manual for uC FS 2004 2007 Micrium 153 whole block is marked as invalid and its content is copied to a non defective block 2 To store read an ECC Error Correction Code for data reliability When
233. sPerBlock 256 NumberOfUsedBlocks 2048 MaxSectorSize 512 RAM usage 160 2 2048 4 256 1 04 512 bytes RAM usage 5813 bytes Example 2 GBit NAND flash with 2K pages 2048 blocks used 2048 byte sec tors One block consists of 64 pages each page holds 1 sector of 2048 bytes SectorsPerBlock 64 NumberOfUsedBlocks 2048 MaxSectorSize 2048 RAM usage 160 2 2048 4 64 1 04 2048 bytes RAM usage 6642bytes Example 512 MBit NAND flash with 512 pages 4096 blocks used 512 byte sec tors One block consists of 64 pages each page holds 1 sector of 512 bytes SectorsPerBlock 32 NumberOfUsedBlocks 8192 MaxSectorSize 512 RAM usage 160 2 4096 4 32 1 04 512 bytes RAM usage 9013 bytes 5 3 11 FAQs Q A Q A Are Multi Level Cell NAND flashes MLCs supported No the driver does not support MLCs Are NAND flashes with 4 Kbytes pages supported Not yet but this will be added You should get in touch with us to find out what the current status is User s amp reference manual for uC FS 2004 2007 Micrium 188 CHAPTER 5 5 4 MultiMedia amp SD card driver ucC FS supports MultiMedia SecureDigital SD and SecureDigital High Capacity SDHC cards Two optional generic drivers for Multi Media SecureDigital SD SecureDigital High Capacity SDHC Mini SecureDigital and Micro SecureDigital cards are available MultiMedia 4 SecureDigital SD cards can b
234. scription Tests for end of file on a given file pointer Prototype int FS FEof FS FILE pFile Parameter Description pFile Pointer to a data structure of type FS FILE Table 4 84 FS FEof parameter list Return value 0 If the end of file has not been reached 1 If the end of file has been reached Additional Information The FS FEof function determines whether the end of a given file pointer has been reached When end of file is reached read operations return an end of file indicator until the file pointer is closed or until FS FSeek or FS ClearErr is called against it Example int ReadFile FS File pFile char pBuffer int NumBytes FS FILE pFile char acBuffer 100 char acLog 100 int Count int Total 116 Error Total 0 pFile FS FOpen default txt r if pFile NULL FS X ErrorOut Could not open file Cycle until end of file reached while FS FEof pFile Count FS Read pFile amp acBuffer 0 sizeof acBu ffer Error FS FError pFile if Error sprintf acLog Could not read from file nReason s FS_ErrorNo2Text Error FS_X_ErrorOut acLog break Total up actual bytes read Total Count sprintf acLog Number of read bytes din Total FS X Log acLog FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 124 CHAPTER 4 API functions 4 13 3 FS_F
235. se can be one of the following Response Type Meaning FS_MMC_RESPONSE_FORMAT_NONE No response is expected from card Response type 1 is expected from card 48 Bit FS MMC RESPONSE FORMAT R1 data stream is sent by card through the CMD line Response type 2 is expected from card 136 Bit FS MMC RESPONSE FORMAT R2 data stream is sent by card through the CMD line Response type 3 is expected from card 48 Bit FS MMC RESPONSE FORMAT R3 data stream is sent by card through the CMD line Table 5 66 FS MMC HW X SendCmd list of possible responses If the specified command expects a response FS MMC HW X GetResponse will be called after FS MMC Hw X SendCmd Example void FS MMC HW X SendCmd U8 Unit unsigned Cmd unsigned CmdFlags unsigned ResponseType U32 Arg U32 CmdCon _StopMMCClock Unit CmdCon ResponseType if CmdFlags amp FS MMC CMD FLAG DATATRANSFER If data transfer CmdCon 1 lt lt 8 Set big endian flag for data transfers since this is how the data is in the 16 bit fifo 1 lt lt 2 Set DATA EN if CmdFlags amp FS MMC CMD FLAG WRITETRANSFER Abort transfer CmdCon 1 lt lt 3 Set WRITE bit if CmdFlags amp FS MMC CMD FLAG SETBUSY Set busy CmdCon 1 lt lt 5 Set ABORT bit if CmdFlags amp FS MMC CMD FLAG INITIALIZ CmdCon 1 lt lt 6 Set ABORT bit
236. sed on any media for which you can provide basic hardware access functions UC FS is a high performance library that has been optimized for speed versatility and memory footprint User s A reference manual for uC FS 2004 2007 Micrium 1 2 CHAPTER 1 Introduction to uC FS Features UC FS is written in ANSI C and can be used on virtually any CPU Some features of uC FS include MS DOS MS Windows compatible FAT12 FAT16 and FAT32 support An optional module that handles long file names of FAT media Multiple device driver support You can use different device drivers with uC FS which allows you to access different types of hardware with the file system at the same time Multimedia support A device driver allows you to access different media at the same time OS support uC FS can be easily integrated into any OS This allows using uC FS in a multi threaded environment ANSI C stdio h like API for user applications An application using the standard C I O library can easily be ported to use uC FS Very simple device driver structure uC FS device drivers need only basic func tions for reading and writing blocks There is an empty generic example included See device generic generic_drv c for more details An optional generic device driver for SmartMedia cards or NAND flash devices which can be easily used with any kind of card reader hardware An optional generic device driver for Multimedia amp SD cards using SPI mode tha
237. t can be easily integrated An optional generic IDE driver which is also suitable for CompactFlash using either True IDE or Memory Mapped mode An optional generic flash memory chip EEPROM driver that handles different flash sector sizes An optional proprietary file system EFS with native long file name support User s amp reference manual for uC FS 2004 2007 Micrium 1 3 Basic concepts 1 3 1 wC FS structure UC FS is organized in different layers illustrated in the diagram below A short description of each layer s functionality follows below Application Program using Storage API or FS API Responsibility of the application programmer File System API lt stdio h gt like functions like FS FOpen FS FRead FS FWrite Translation of file operations to sector operations uC FS Synchronisation of device operations for different file operations Low level routines to access sectors of a device and check status Low level routines to access your hardware Responsibility of application programmer API Layer The API Layer is the interface between uC FS and the user application It is divided in two parts Storage API and File System API The File System API declares file func tions in ANSI C standard I O style such as FS FOpen FS Fwrite etc The API Layer transfers any calls to these functions to the File System Layer Currently t
238. t 26 Add template for hardware routines 28 API 33 API functions 33 139 Directory functions 72 error handling 122 Extended functions 86 FAT related functions 110 file access 47 file positioning 54 file system cache 115 file system control 37 42 Formatting a medium 78 Obsolete functions 126 Operations on file 58 ATA drives Hardware 236 Hardware interface 237 Modes of operation 236 Pin functions 236 Supported modes of operation 236 True IDE mode 236 B Build 25 Build the project and test it 25 C Cache functions FS_AssignCache 115 FS Cache Clean 117 FS CACHE SetMode 118 FS CACHE SetAuota 120 CF IDE FS IDE HW ReadData 245 FS IDE HW ReadReg 243 User s amp reference manual for uC FS 307 FS IDE HW WriteData 246 FS IDE HW WriteReg 244 Checkdisk error codes 112 CompactFlash Hardware 231 Memory CARD mode 228 233 Modes of operation 232 Pin functions 225 Supported modes of operation 232 CRC 192 Creating a simple project without uC FS 23 D DataFlash HW FS DF HW X Write 185 FS FS HW X DisableCS 182 FS FS HW X EnableCs 181 Debugging 283 288 FS X ErrorOut 286 FS X Log 284 FS X Warn 285 Device 141 Device drivers 141 265 default names 142 function table for 264 integrating your own 265 Directory functions FS FindClose 72 FS FindFirstFile 73 FS FindNextFile 74 FS MkDir 75 FS RmDir 76 Structure FS FIND DATA 77 E EFS configuration 274 Error code 124 Error handling FS ClearEr
239. tFileTimeEx parameter list Permitted values for parameter Index Indicates that the creation timestamp should be returned Indicates that the access timestamp should be returned Indicates that the modify timestamp should be returned FS FILETIME CREATE FS FILETIME ACCESS FS FILETIME MODIFY Return value 0 The timestamp of the given file was successfully read and stored in pTimeS tamp 0 In case of any error Additional Information Values for pName are the same as for FS FOpen Refer to FS_FOpen on page 48 for examples of valid names A timestamp is a packed value with the following format Bits Description 0 4 Second divided by 2 5 10 Minute 0 59 11 15 Hour 0 23 16 20 Day of month 1 31 21 24 Month January gt 1 February gt 2 etc 25 31 Year offset from 1980 Add 1980 to get current year Table 4 26 FS GetFileTime timestamp format description To convert a timestamp to a Structure FS FILETIME on page 99 structure use the function FS TimeStampToFileTime on page 98 User s amp reference manual for uC FS 2004 2007 Micrium 62 CHAPTER 4 API functions 4 6 5 FS Move Description Moves an existing file or a directory including its children Prototype int FS Move const char sExistingName const char sNewName Parameter Description sExistingname Po
240. ta Pointer to a buffer for data to be receive NumBytes Number of bytes to be written Table 5 37 FS DF HW X Write parameter list Additional Information This function is DataFlash Example used to send a number of bytes from memory buffer to the dedicated void FS DF HW X Write U8 Unit const U8 pData int NumBytes int i U8 mask U8 data for a 0 1 lt NumBytes i data pDatalil mask 0x80 while mask 1 if data amp mask SPI SET DATAOUT else SPI CLR DATAOUT SPI CIR CI SPI DELAY LK 3 SPI SET CI SPI DELAY LK mask gt gt 1 SPI_SET_DATAOUT default state of data line is high User s amp reference manual f or uC FS 2004 2007 Micrium 186 CHAPTER 5 Device drivers 5 3 9 Additional Information Low level format Before using the NAND flash as a storage device a low level format has to be per formed Refer to FS FormatLow on page 83 and FS_FormatLLifRequired on page 82 for detailed information about low level format 5 3 10 Resource usage 5 3 10 1 ROM usage The ROM usage depends on the compiler options the compiler version and the used CPU The memory reguirements of the NAND driver presented in the tables below have been measured on a system as follows ARM7 IAR Embedded workbench V4 41A Thumb mode Size optimization
241. ta read from the IDE register Example U16 FS IDE HW _ReadReg U8 Unit unsigned Addroff volatile U16 pIdeReg FS USE PARA Unit pideReg Getp Addroff return pIdeReg User s amp reference manual for uC FS 2004 2007 Micrium 244 CHAPTER 5 5 5 6 5 FS_IDE_HW_WriteReg Description Device drivers Writes an IDE register Data to the IDE register are written 16 bit wide Prototype void FS_IDE_HW_WriteReg U8 unsigned AddrOff Unit U16 Data Parameter Meaning Unit Unit number 0 N Addroff Address offset that specifies which IDE register should be written Data Value that should be written to the register Table 5 80 FS IDE HW WriteReg parameter list Example void FS IDE HW WriteReg U8 Unit volatile U16 pldeReg FS USE PARA Unit pIldeReg Getp Addroff pIdeReg Data User s amp reference manual for uC FS unsigned AddrOff U16 Data 2004 2007 Micrium 245 5 5 6 6 FS_IDE HW ReadData Description Reads data from the IDE data register Prototype void FS IDE HW ReadData U8 Unit U16 pData unsigned NumBytes Parameter Meaning Unit Unit number 0 N pData Pointer to a read buffer NumBytes Number of bytes that should be read Table 5 81 FS IDE HW ReadData parameter list Example void FS IDE HW ReadData U8 Unit U8 pData unsigned Num
242. tandard How to use this manual This manual explains all the functions and macros that uC FS offers It assumes you have a working knowledge of the C language Knowledge of assembly programming is not required Typographic conventions for syntax This manual uses the following typographic conventions Style Used for Body Body text Cemara Text that you enter at the command prompt or that appears on the display that is system functions file or pathnames Parameter Parameters in API functions Sample Sample code in program examples Reference Reference to chapters tables and figures or other documents GUIElement Buttons dialog boxes menu names menu commands Emphasis Very important sections Table 1 1 Typographic conventions User s amp reference manual for uC FS 2004 2007 Micrium 6 CHAPTER About this document User s amp reference manual for uC FS 2004 2007 Micrium Table of Contents 1 ADOUE MIS document sea ee ner seed or statan ite 5 2 NRroduohon to GFS znate n sagan Seis ou tee tn ruk no De eee i teste Da sa 7 2 1 What iS GES vier AS RON A A rka a Ad o 7 2 2 FO ACUPES SES SR RE ne dan ae Matane tante ann Sen 8 2 3 Basic concepts 22e uen ane era alle da aie noue ee una een z dan een Ode V ke KO een os 9 2 4 Development environment compiler ss 12 3 Getting SL LUS te tura fadnesen 13 3 1 Installation s diodu en A Re RE Mn bo ot PA aa 14 3 2 Using the Windows sample sis
243. ted It invalidates all file handles If you use FS UnmountForced there is no guarantee that all file handles to this volume are closed and the directory entries for the files are updated User s amp reference manual for uC FS 2004 2007 Micrium 42 CHAPTER 4 API functions 4 3 File system configuration functions The file system control functions listed in this section can only be used in the runtime configuration phase This means in practice that they can only be called from within FS X AddDevices refer to FS X AddDevices on page 262 for more informa tion about this function 4 3 1 FS AddDevicef Description Adds a device to uC FS This consists of 2 operations 1 Add physical device This initialises the driver allowing the driver to identify the stor age device as far as reguired and allocate memory reguired for driver level manage ment of the device This makes sector operations possible 2 Add the devices as a logical device This makes it possible to mount the device making it accessible for the file system and allowing file operations Prototype FS VOLUME FS AddDevice const FS DEVICE TYPE pDevType Parameter Description Pointer to device driver table See Device driver function table on page 258 for additional information Table 4 6 FS AddDevice parameter list pbevType Return value Pointer of the volume added to uC FS Additional Information
244. ter Running uC FS on target hardware updated Some smaller structural changes Section Step 3 Add device driver simplified Section Step 4 Implement hardware routines simplified Section Troubleshooting moved to chapter debugging Chapter API functions Section File system configuration functions added FS_AddDevice moved into this section FS_AddPhysDevice added FS_LOGVOL_Create added FS_LOGVOL_AddDevice added Chapter Device drivers Section NAND FS_NAND_SetBlockRange added Chapter Configuration of uC FS Section Compile time configuration Miscellaneous configuration FS NO CLIB default value corrected Chapter Debugging FS X Log FS X Warn FS X ErrorOut function description enhanced Chapter OS Support updated 3 08 RO 070618 SK 3 02 RO 070405 SK User s amp reference manual for uC FS 2004 2007 Micrium About this document Assumptions This document assumes that you already have a solid knowledge of the following e The software tools used for building your application assembler linker C com piler e The C programming language e The target processor e DOS command line If you feel that your knowledge of C is not sufficient we recommend The C Program ming Language by Kernighan and Richie ISBN 0 13 1103628 which describes the standard in C programming and in newer editions also covers the ANSI C s
245. ter list Return value 0 If the file pointer has been positioned according to the parameters 1 In case of any error Additional Information The FS FSeek function moves the file pointer to a new location that is an offset in bytes from Origin You can use FS FSeek to reposition the pointer anywhere in a file The pointer can also be positioned beyond the end of the file Valid values for parameter Origin are Permitted values for parameter Origin FS SEEK SET The origin is the beginning of the file FS SEEK CUR The origin is the current position of the file pointer FS SEEK END The origin is the current end of file position This function is identical to FS SetFilePos Refer to FS_SetFilePos on page 57 for more information Example const char acText some text will be overwritten n void MainTask void FS FILE pFile pFile FS FOpen test txt w if pFile 0 FS FWrite acText 1 strlen acText pFile FS FSeek pFile 4 FS SEEK CUR FS FWrite acText 1 strlen acText pFile FS FClose pFile User s amp reference manual for uC FS 2004 2007 Micrium 55 4 5 2 FS FTell Description Returns the current position of a file pointer Prototype I32 FS FTell FS FILE pFile Parameter Description pFile Pointer to a data structure of type FS FILE Table 4 17 FS Tell parameter list
246. this mode This is an Output Enable strobe generated by the OE ATA host interface It is used to read data from the SEL I 9 CompactFlash Storage Card or CF Card in Memory Mode and to read the CIS and configuration regis ters Table 5 72 Pin functions in memory card mode User s amp reference manual for uC FS 2004 2007 Micrium 229 Signal name Dir Pin Description READY REG RESET WAIT WP O 37 44 41 13 38 33 4 42 36 24 In Memory Mode this signal is set high when the CompactFlash Storage Card or CF Card is ready to accept a new data transfer operation and is held low when the card is busy At power up and at Reset the READY signal is held low busy until the Com pactFlash Storage Card or CF Card has completed its power up or reset function No access of any type should be made to the CompactFlash Storage Card or CF Card during this time Note however that when a card is powered up and used with RESET continuously disconnected or asserted the reset function of this pin is disabled and conse quently the continuous assertion of RESET will not cause the READY signal to remain continuously in the busy state This signal is used during Memory Cycles to distin guish between Common Memory and Register Attribute Memory accesses High for Common Memory Low for Attribute Memory To use it with uC FS this signal should be high When the pin is
247. to receive the response NumBytes Number of bytes to receive Table 5 60 FS MMC HW X GetResponse parameter list Return value Return value Meaning FS MMC CARD NO ERROR All data have been read successfully FS MMC CARD RESPONSE TIMEOUT time FS MMC CARD READ CRC ERROR card host controller Card did not send the response in appropriate The received response failed the CRC check of Table 5 61 FS MMC HW X GetResponsef list of return values Additional Information This function is used to read the card s response to buffer memory Example int FS MMC HW X GetResponse U8 Unit void pBuffer U32 Size U16 pResponse U32 Index U32 Status pResponse U16 pBuffer Wait for response while 1 Status __SDMMC_ STATUS if Status amp MMC STATUS CLOCK DISABLED _StartMMCClock Unit gt if Status amp MMC STATUS END COMMAND RESPONSE break if Status amp MMC STATUS RESPONSE TIMEOUT return FS MMC CARD RESPONSE TIMEOUT if Status amp MMC STATUS RESPONSE CRC ERROR return FS MMC CARD RESPONSE CRC ERROR Read the necessary number of response words from the response FIFO for Index 0 Index lt Size 2 Index pResponse Index SDMMC RES FIFO return FS MMC CARD NO ERROR User s amp reference m
248. tory test default driver on default device Err FS_RmDir test mydir void FSTask2 void int Err Remove directory mydir RAM device driver on default device Err FS_RmDir ram mydir User s amp reference manual for uC FS 2004 2007 Micrium 77 4 7 6 Structure FS FIND DATA Description The FS FORMAT INFO and files Prototype typedef struct structure represents the information used to access directories Public elements to be used by application U8 Attributes U32 CreationTime U32 LastAccessTime U32 LastWriteTime U32 FileSize char sFileName Private elements Not be used by the application int SizeofFileName FS DIR Dir FS FIND DATA Members Description Attributes Specifies the file attributes of the file found CreationTime U32 value containing the time the file was created LastAccessTime U32 value containing the time that the file was last accessed LastWriteTime U32 value containing the time that the file was last written to FileSize U32 value specifies the size of the file sFileName String that is the name of the file rem Size of the file name Private element Not to be used by application nie Directory administration structure Private element Not to be used by an application Table 4 43 FS_FIND_DATA list of structure elements User s amp reference manual for uC FS 2004 2007 Mi
249. uffer that is large enough to hold the volume name Example void ShowAvailableVolumes void int NumVolumes int i int BufferSize char acVolume 12 BufferSize sizeof acVolume NumVolumes FS GetNumVolumes FS X Log Available volumes n for i 0 i lt NumVolumes i if FS GetVolumeName i amp acVolume 0 BufferSize lt BufferSize FS X Log acVolume FS X Log n User s amp reference manual for uC FS 2004 2007 Micrium 95 4 9 9 FS GetVolumeSizef Description Gets the total size of a specific volume Prototype U32 FS GetVolumeSize const char sVolume Parameter Description sVolume Volume name as a string Table 4 59 FS GetVolumeSize parameter list Return Value Volume size in bytes Volume sizes larger than 4 Gbyte are truncated to OxFFFFFFFF the maximum value of a U32 Additional Information Note that volume sizes larger than 4 Gbytes are reported as OxFFFFFFFF because a U32 cannot represent bigger values The function FS GetVolumeInfo can be used for larger media If you do not need to know if the total space is bigger than 4 Gbytes you can still reliably use FS GetVolumeSize Valid values for sVolume have the following structure DevName UnitNum where e DevName is the name of a device If not specified the first device in the volume table will be used UnitNum is the number of the unit of t
250. umber of blocks to be transferred Table 5 56 FS MMC HW X SetHWNumBlocks parameter list Additional Information Before sending the command to read or write data from or to the card This functions tells the card host controller how many blocks need to be transferred received Example void FS MMC HW X SetHWNumBlocks U8 Unit U16 NumBlocks ___ SDMMC NUM BLK NumBlocks User s amp reference manual for uC FS 2004 2007 Micrium 211 5 4 7 6 FS MMC_HW_X_IsWriteProtected Description Checks the status of the mechanical write protection of a SD card Prototype char FS MMC HW X IsWriteProtected U8 Unit Parameter Meaning Unit Unit number 0 N Table 5 57 FS MMC HW X IsWriteProtected parameter list Return value 0 If the card is not write protected 1 Means that the card is write protected Additional Information MultiMedia cards do not have mechanical write protection switches and should always return 0 If you are using SD cards be aware that the mechanical switch does not really protect the card physically from being overwritten it is the responsibility of the host to respect the status of that switch Example char FS MMC HW X IsWriteProtected U8 Unit return 0 Card slot has no write switch detector return 0 User s amp reference manual for uC FS 2004 2007 Micrium 212 CHAPTER 5 Device drivers 5 4 7 7 FS MMC HW X IsPresent Desc
251. ume is already mounted n else printf Volume is not mounted n User s amp reference manual for uC FS 2004 2007 Micrium 98 CHAPTER 4 API functions 4 9 12 FS TimeStampToFileTime Description Converts a given timestamp to a FS FILE TIME structure Prototype void FS TimeStampToFileTime U32 TimeStamp FS FILETIME pFileTime Parameter Description TimeStamp Timestamp to be converted Pointer to a data structure of type FS FILETIME to store the con pFileTime verted timestamp Table 4 63 FS TimeStampToFileTime parameter list Additional Information A TimeStamp is a packed value with the following format Bits Description 0 4 Second divided by 2 5 10 Minute 0 59 11 15 Hour 0 23 16 20 Day of month 1 31 21 24 Month January gt 1 February gt 2 etc 25 31 Year offset from 1980 Add 1980 to get current year Table 4 64 FS_TimeStampToFileTime timestamp format description User s amp reference manual for uC FS 2004 2007 Micrium 99 4 9 13 Structure FS FILETIME Description The FS_FILETIME structure represents a timestamp using individual members for the month day year weekday hour minute and second This can be useful for getting or setting a timestamp of a file or directory Prototype typedef struct U16 Year U16 Month U16 Day U16 Hour
252. ur SPI interface never generates a higher clock than MaxFreg specifies You can always run MultiMedia 8 SD cards at lower or equal but never on higher fre quencies The initial frequency must be 400kHz or less If the precise frequency is unknown typical for implementation using port pins bit banging the return value should be less than the maximum freguency leading to longer timeout values which is in general unproblematic You have to return the actual clock speed of your SPI interface because uC FS needs the actual frequency to calculate timeout values If the precise freguency is unknown typical for implementation using port pins bit banging the return value should be less than the maximum freguency leading to longer timeout values which is in general unproblematic Example using port pins define MMC MAXFREOUENCY 400 U16 FS MMC HW X SetMaxSpeed U8 Unit U16 MaxFreq Init return MMC MAXFREOUENCY We are not faster than this Example using SPI mode U16 FS MMC HW X SetMaxSpeed U8 Unit U16 MaxFreq U32 InFreg U32 SPIFreg if MaxFreg lt 400 MaxFreq 400 SPIFreq 1000 MaxFreq if SPIFreq gt 200000 InFreq 48000000 _sbcr InFreq SPIFreg 1 SPIFreg _InitSPI return MaxFreg We are not faster than this User s amp reference manual for uC FS 2004 2007 Micrium 5 4 6 4 FS MMC HW X SetVoltage Description Sets the operating voltage range for t
253. use it cannot access logical drives with CreateFile 5 7 2 Theory of operation ucC FS supports in this version FAT and EFS file systems only NTFS logical drives cannot be accessed by uC FS It can be used either to store access files on a floppy disk or using an USB Card reader for accessing flash cards It works also on FAT for mated hard disks or partitions Note Do not use this driver on partitions containing important data It is prima rily meant to be used for evaluation purposes Problems may occur if the program using uC FS is debugged or terminated using the task manager 5 7 3 Fail safe operation Although not important since the driver is not designed to be used in an embedded device the data is normally safe Data safety is handled by the underlying operating system and hardware 5 7 4 Wear leveling The driver does not need wear leveling 5 7 5 Configuring the driver 5 7 5 1 Adding the driver to pC FS To add the driver use FS_AddDevice with the driver label FS_WINDRIVE_Driver This function has to be called from within FS X AddDevices Refer to FS_X_AddDevices on page 262 for more information Example FS_AddDevice amp FS WINDRIVE Driver 5 7 5 2 FS Windrive Configure Description Configures a windows drive instance This function has to be called from within FS X AddDevices after adding an instance of the Windrive driver Refer to FS X AddDevices on page 262 for mor
254. utes of a given file directory FS GetFileTime Retrieves the creation access or modify timestamp of a given file directory FS GetFileTimeEx Retrieves the timestamp of a given file directory FS Move Moves an existing file or a directory includ ing its children FS Remove Deletes a file FS Rename Renames a file directory FS SetFileAttributes Sets the attributes of a given file or direc tory FS SekrilsrT me Sets the timestamp of a given file or direc tory Table 4 1 uC FS API function overview User s amp reference manual for uC FS 2004 2007 Micrium 35 Function Description FS SetFileTimeEx Sets the creation access or modify times tamp of a given file or directory FS SetEndOfFile Sets the end of a file FS Truncate Truncates a file to a specified size FS Verify Verifies a file with a given data buffer Direct ory functions FS FindClose Closes a directory PS Fingrirstrrle Searches for a file in a specified directory FS FindNextFile Continues file search in a directory FS MkDir Creates a directory FS RmDir Removes a directory Formatting a medium FS IsHLFormatted Checks if a device is high level formatted FS IsLLFormatted Checks if a device is low level formatted FS FormatLLIfRe
255. windDir 137 Operations on file FS CopyFile 58 FS GetFileAttributes 59 FS GetFileTime 60 FS GetFileTimeEx 61 FS Move 62 FS Remove 63 FS Rename 64 FS SetEndofFile 68 FS SetFileAttributes 65 FS SetFileTime 66 FS SetFileTimeEx 67 FS Truncate 69 FS Verify 70 OS 277 OS Integration 277 282 OS integration API functions 278 Examples 282 FS X OS Init 279 FS X OS Lock 280 FS X OS Unlock 281 OS support 274 P Performance 289 Performance and Resource usage 289 293 R Running 21 Running uC FS on target hardware 21 32 User s amp reference manual for uC FS 309 S Sample configuration 276 279 Sample project building 15 debugging 15 SD Card 188 SDHC Card 188 Search path configuration of 25 SecureDigital Card 188 SecureDigital High Capacity Card 188 SerialFlash HW FS DF HW X Read 184 FS FS HW X Init 183 Source code Generic 24 Storage API 9 Syntax conventions used 5 T Troubleshooting 287 W WinDrive disk driver 261 Configuration 261 2004 2007 Micrium
256. xamples of valid names A timestamp is a packed value with the following format Bits Description 0 4 Second divided by 2 5 10 Minute 0 59 11 15 Hour 0 23 16 20 Day of month 1 31 21 24 Month January gt 1 February gt 2 etc 25 31 Year offset from 1980 Add 1980 to get current year Table 4 24 FS GetFileTime timestamp format description To convert a timestamp to a Structure FS FILETIME on page 99 structure use the function FS TimeStampToFileTime on page 98 Example void MainTask void char ac 80 U32 TimeStamp FS FILETIME FileTime FS GetFileTime test txt amp TimeStamp FS TimeStampToFileTime TimeStamp amp FileTime sprintf ac File time of test txt d 2d 2d 2d 2d 2d FileTime Year FileTime Month FileTime Day FileTime Hour FileTime Minute FileTime Second FS X Log ac User s amp reference manual for uC FS 2004 2007 Micrium 61 4 6 4 FS_GetFileTimeEx Description Retrieves the creation access or modify timestamp for a specified file or directory Prototype int FS GetFileTime const char pName U32 pTimeStamp int Index Parameter Description pName Pointer to a string that specifies the name of a file or directory pTimeStamp Pointer to a U32 variable that receives the timestamp Index Flag that indicates which timestamp should be returned Table 4 25 FS Ge
257. ystem allocates RAM in the initialization phase and holds it while the file system is running The macro ALLOC SIZE which is located in the respective driver configuration file specifies the size of RAM used by the file system This value should be fine tuned according to the reguirements of your target system What to do Per default ALLOC SIZE is set to a value which should be appropriate for most target systems Nevertheless you should adjust it not to waste RAM Once your file system project is up and running you can check the real RAM reguirement of the driver with the public auxiliary variable FS NumBytesAllocated which is also located in the con figuration file of the respective driver Check the size of FS NumBytesAllocated and adjust the value of ALLOC SIZE to the value which FS NumBytesAllocated has had after initialization of the file system Note If you define ALLOC SIZE with a value which is smaller than the appropri ate size the file system will run into FS X Panic If you define ALLOC SIZE witha value which is above the limits of your target system the linker will give an error during the build process of the project User s amp reference manual for uC FS 2004 2007 Micrium 33 Chapter 4 API functions In this chapter you will find a description of each uC FS API functions An application should only access uC FS by these functions User s amp reference manual for uC F

uC/GUI user manual

Contents

Download Pdf Manuals

Related Search

Related Contents