Home

µC/FS User`s Manual v4.04

1. ecceeeeeeeeeeeeeeeneeeneeeees 38 uC CRC Checksums and Error Correction Codes cccccceeeeeeeeeeeee 40 uC FS Platform Independent Source Code cceceeeeeeeeeeeeeeeeeeeee 42 UC FS FAT Filesystem Source Code cecseesseeeceeeeeeeeeeeeeeeeeeeeeseneeees 45 HC FS Memory Device Drivers cceccccesseeeeeeeeeeeeeeeeeseeeeeeeesseeneeeeeeeee 46 3 11 3 12 3 13 Chapter 4 4 1 4 2 4 3 4 4 4 5 Chapter 5 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 7 1 5 7 2 Chapter 6 6 1 6 2 6 3 6 3 1 6 3 2 6 3 3 6 3 4 6 3 5 6 4 6 5 Chapter 7 7 1 7 1 1 UC FS Platform Specific Source Code ccceeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 50 UC FS OS Abstraction Layer cccesseecceseseeeeceeeeeeeeeeeesseeeeseeeeseeeeeeeeseees 51 EE 52 Miscela OUS a aeree et aa a ae S Te a aa n Ka ae eae aaa aaa daadaa a ade 59 N men lat re annaa eaa deed ea 59 UC FS Device and Volume Names cecceseeeeeeeeeeeeeeeeeeeeeeeeeeeeeneeeeees 61 uC FS File and Directory Names and Paths AEN EEN 62 HC FS Name Lengths wie scciveessetevcscescceieeeseccteeesessteveseeseeeeveessccreeeseste 63 Resource Usage 2 suste estate ASSEN EE dee 65 Devices and Volumes c s eeeceeeeeeeeeceeeeeeeeaneeeeeseeeeeeesnseeeseeeneeeeeeees 67 Device Operattons ee 68 Elle OR ELE 69 Using Removable Devices ccccccsseeecceeeseeeeeeeeeeeeeeeeeeeeeeseeeeeeeeeeeeesenenees 71 Sa EE 72 Volume Operations viesccescascccccceccsteezsceee
2. l End DMA FSDev_IDE_BSP_DMA End l Check for error Figure 11 4 Command execution 132 Chapter 12 Logical Device Driver The logical device driver is not released yet It should be released in a soon future 133 Chapter 13 MSC Driver The MSC driver supports USB mass storage class devices Oe USB drives thumb drives using the pC USB host stack 13 1 FILES AND DIRECTORIES The files inside the MSC driver directory are outlined in this section the generic file system files outlined in Chapter 3 Directories and Files on page 28 are also required Micrium Software uC FS Dev This directory contains device specific files Micrium Software uC FS Dev MSC This directory contains the MSC driver files fs_dev_msc constitute the MSC device driver Micrium Software uC USB This directory contains the code for uC USB For more information please see the uC USB user manual 134 MSC Driver 13 2 USING THE MSC DRIVER To use the MSC driver two files in addition to the generic file system files must be included in the build E fs dev_msc c E fs dev_msc h The file fs _dev_msc h must also be included in any application or header files that directly reference the driver for example by registering the device driver The following directory must be on the project include path E Micrium Software uC FS Dev MSC Before uC FS is initialized the pC USB h
3. BSP Template GPIO fs dev sd spi bsp c is a template GPIO bit banging BSP See section C 13 SD MMC SPI mode BSP on page 493 for more information 176 SD MMC Drivers Micrium Software uC FS Examples BSP Dev SD Card Each subdirectory contains an example BSP for a particular platform These are named according to the following rubric lt Chip Manufacturer gt lt Board or CPU gt fs_dev_sd_card_bsp c Micrium Software uC FS Examples BSP Dev SD SPI Each subdirectory contains an example BSP for a particular platform These are named according to the following rubric lt Chip Manufacturer gt lt Board or CPU gt fs_dev_sd_ spi bsp c 17 2 USING THE SD MMC CARDMODE DRIVER To use the SD MMC cardmode driver five files in addition to the generic file system files must be included in the build E fs dev _sd c E fs dev_sd h E fs deu ad card c E Te de ad card h E Te _dev_sd_card_bsp c The file Ce dev_sd_card h must also be included in any application or header files that directly reference the driver for example by registering the device driver The following directories must be on the project include path D Micrium Software uC FS Dev SD E Micrium Software uC FS Dev SD Card 177 SD MMC Drivers A single SD MMC volume is opened as shown in Listing 17 1 The file system initialization FS _Init function must have previously been called ROM RAM characteristics and performance benchmarks of the
4. 279 A 5 4 FSEntry_Del LC FS API Reference Manual void FSEntry Del CPU_CHAR name_full PG FLAGS entry type FS_ERR p err File Called from Code enabled by fs_entry c Application not FS_CFG_RD_ONLY_EN fs_rmdir fs_remove Delete a file or directory See also fs_remove and fs_rmdir ARGUMENTS name_full Pointer to character string representing the name of the entry See section 4 3 uC FS File and Directory Names and Paths on page 62 entry type Indicates whether the entry MAY be a file see Notes 1 and 2 FS ENTRY TYPE DIR FS ENTRY TYPE FILE FS ENTRY TYPE ANY if the entry must be a dir if the entry must be a file if the entry may be any type p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE FS_ERR_NULL PTR FS ERR NAME INVALID FS _ERR NAME PATH TOO LONG FS_ERR_ VOL NOT OPEN FS ERR VOL MOT MOUNTED FS ERR BUF NONE AVAIL FS_ERR_DEV Or entry error Entry date time set successfully Argument name_full passed a NULL pointer Entry name specified invalid OR volume could not be found Entry name specified too long Volume was not open Volume was not mounted Buffer not available Device access error 280 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS 1 When a file is removed the space occupied by the file is freed and shall no longer be accessible 2 A directory can be removed only if
5. BSP Template SPI GPIO fs_dev_nand_bsp c This is a template BSP for Atmel Dataflash devices accessed via GPIO bit banging See section C 8 NAND Flash SPI BSP on page 450 for more information BSP Template SPI fs_dev_nand_bsp c This is a template BSP for Atmel Dataflash devices accessed via SPI See section C 8 NAND Flash SPI BSP on page 450 for more information 138 NAND Flash Driver PHY This directory contains physical level drivers for specific NAND types fs_dev_nand_0512x08 512 byte page NAND 8 bit data bus fs_dev_nand_2048x08 2048 byte page NAND 8 bit data bus fs dev nand 2048x16 2048 byte page NAND 16 bit data bus fs_dev_nand_at45 Atmel AT45 serial flash PHY Template fs_dev_nand_phy c This is a template for a physical layer driver Micrium Software uC FS Examples BSP Dev NAND Each subdirectory contains an example BSP for a particular platform These are named according to the following rubric lt Chip Manufacturer gt lt Board or CPU gt fs_dev_nand_bsp c 14 2 DRIVER amp DEVICE CHARACTERISTICS All NAND devices share certain characteristics The medium is always organized into units called blocks which are erased at the same time when erased all bits are 1 Only an erase operation can change a bit from a 0 to a 1 only an unprogrammed byte can have its bits changed from 1 to 0 Each block is divided into pages which comprises a data area 139 NAND Flash Driver oft
6. gt are not part of the actual name lt board name gt This is the name of the evaluation board A board from Micrium will typically be called uC Eval xxxx where xxxx will be the name of the CPU or MCU used on the evaluation board The lt and gt are not part of the actual name lt compiler gt This is the name of the compiler or compiler manufacturer used to build the code for the evaluation board The lt and gt are not part of the actual name BSP This directory is always called BSP 34 Directories and Files VW These are the source files of the BSP Typically all the file names start with BSP_ but they don t have to It s thus typical to find bsp c and bsp h in this directory Again the BSP code should contain functions such as LED control functions initialization of timers interface to Ethernet controllers and more 3 4 pC CPU CPU SPECIFIC SOURCE CODE uC CPU consists of files that encapsulate common CPU specific functionality as well as CPU and compiler specific data types Micrium Software uC CPU cpu_core c cpu_core h cpu_def h Cfg Template cpu_cfg h lt architecture gt lt compiler gt cpu h cpu_a asm cpu_c c Micrium This directory contains all software components and projects provided by Micripm Software This sub directory contains all the software components and projects uC CPU This is the main pC CPU directory 35 Dire
7. A 7 2 FSVol_Fmt void FSVol_ Fmt CPU_CHAR name_ vol void p fs cfg FS_ERR p err File Called from Code enabled by fs_vol c Application not FS_CFG_RD_ONLY_EN Format a volume ARGUMENTS name vol Colume name p_fs cfg Pointer to file system driver specific configuration For all file system drivers if this is a pointer to NULL then the default configuration will be selected More information about the appropriate structure for the FAT file system driver can be found in Chapter 6 p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Volume formatted FS_ERR_DEV Device error FS_ERR_DEV_INVALID SIZE Invalid device size FG ERR NAME NULL Argument name_vol passed a NULL pointer FS ERR VOL DIRS OPEN Directories open on volume FS_ERR_VOL_ FILES OPEN Files open on volume PG ERR VOL INVALID SYS Invalid file system parameters PG ERR VOL NOT OPEN Volume not open REQUIRED CONFIGURATION None 317 LC FS API Reference Manual NOTES WARNINGS 1 Function blocked if files or directories are open on the volume All files and directories MUST be closed prior to formatting the volume For any file system driver if p fs cfg is a pointer to NULL then the default configuration will be selected If non NULL the argument should be passed a pointer to the appropriate configuration structure For the FAT file system driver p fs_cfg should be passed a pointer to
8. Argument p_info passed a NULL pointer Sector start or count invalid Or device access error see section B 4 Device Error Codes on page 377 RETURNED VALUE None NOTES WARNINGS None 261 LC FS API Reference Manual A 3 11 FSDev_Rd void FSDev_Rd CPU_CHAR name_dev void p dest FS_SEC_NBR start D PG SEC QTY cnt FS_ERR p err File Called from Code enabled by fs_dev c Application N A Read data from device sector s ARGUMENTS name_dev Device name p dest Pointer to destination buffer start Start sector of read cnt Number of sectors to read p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Sector s read FS_ERR_NAME NULL Argument name deyv passed a NULL pointer PG ERR NULL PTR Argument p dest passed a NULL pointer Or device access error see section B 4 Device Error Codes on page 377 RETURNED VALUE None 262 LC FS API Reference Manual NOTES WARNINGS Device state change will result from device I O not present or timeout error 263 LC FS API Reference Manual A 3 12 FSDev_Refresh CPU_BOOLEAN FSDev_Refresh CPU_CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev c Application N A Refresh a device ARGUMENTS name dev Device name p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Device opened successfully
9. FS_ERR p err File Called from Code enabled by fs c Application FS_CFG WORKING DIR EN fs_getcwd Get the working directory for the current task ARGUMENTS path dir String buffer that will receive the working directory path size Size of string buffer p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Working directory obtained FS_ERR NULL PTR Argument path_dir passed a NULL pointer FS_ERR_NULL ARG Argument size passed a NULL value FS_ERR_NAME BUF TOO SHORT Argument size less than length of path FS_ERR_VOL NONE EXIST No volumes exist RETURNED VALUE None NOTES WARNINGS If no working directory is assigned for the task the default working directory the root directory on the default volume will be returned in the user buffer and set as the task s working directory 205 LC FS API Reference Manual A 1 5 FS WorkingDirSet void FS WorkingDirSet CPU CHAR path dir FS_ERR p err File Called from Code enabled by fs c Application FS_CFG WORKING DIR EN fs_chdir Set the working directory for the current task ARGUMENTS path dir String buffer that specified EITHER a the absolute working directory path to set b a relative path that will be applied to the current working directory p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Working directory set FS_ERR NULL
10. If CPHA 0 data is read on the leading edge of the clock and changed on the following edge If CPHA 1 data is changed on the leading edge of the clock and read on the leading edge The most commonly supported settings are CPOL CPHA 0 0 and 1 1 D Slave select polarity The active level of the slave select may be electrically high or low Low is ubiquitous high rare 495 LUC FS Porting Manual SSEL 0 1 2 3 45 6 7 8 9 10 11 12 13 14 15 SCLK a oa Command 0x F Gendeod so Figure C 6 Example SPI transaction ee Response 0x20 A BSP is required that abstracts a CPU s SPI peripheral The port includes one code file named according to the following rubric FS_DEV_ lt dev_name gt _BSP C or FS DEV lt dev_name gt _SPI_BSP c This file is generally placed with other BSP files in a directory named according to the following rubric Micrium Software EvalBoards lt manufacturer gt lt board_name gt lt compiler gt BSP Several example ports are included in the uC FS distribution in files named according to the following rubric Micrium Software uC FS Examples BSP Dev NAND lt manufacturer gt lt cpu_name gt Micrium Software uC FS Examples BSP Dev NOR lt manufacturer gt lt cpu_name gt Micrium Software uC FS Examples BSP Dev SD SPI lt
11. The NOR driver can be ported to many physical organization command set bus type etc The NOR driver can be ported to any bus interface The NOR driver can be ported to any SPI peripheral for SPI flash The SD MMC driver can be ported to any SD MMC host controller for cardmode access The SD MMC driver can be ported to any SPI peripheral for SPI mode access C 1 DATE TIME MANAGEMENT Depending on the settings of uC Clk you might have to write time management functions that are specific to your application For example you might have to define the function Clk _ExtTS Get to obtain the timestamp of your system provided by a real time clock peripheral Please refer to pC Clk manual for more details 385 LUC FS Porting Manual C 2 CPU PORT uC CPU is a processor compiler port needed for uC FS to be CPU compiler independant Ports for the most popular architectures are already available in the pC CPU distribution If the pC CPU port for your target architecture is not available you should create your own based on the port template also available in uC CPU distribution You should refer to the pC CPU user manual to know how you should use it in your project C 3 OS KERNEL uC FS can be used with or without an RTOS Either way an OS port must be included in your project The port includes one code header file pair fs_os c fs_os h uC FS manages devices and data structures that may not be accessed by severally tas
12. Trace Configuration on page 534 about configuring the trace level MEM module now initialized FS Shell initialization succeeded FS INITIALIZATION Adding opening NAND volume nand Dr NAND PHY AT45 Recognized device Part nbr Atmel AT45DB161D Page cnt 8192 Page size 512 Blk cnt 1024 Blk size 4096 Manuf ID Ox1F Dev ID 0x27 NAND FLASH FOUND Name nand 0 Sec Size 12 bytes Size 8192 secs Replatemnt blks 3 opened device FSPartition_RdEntry Found possible partition Start 0 sector Size 0 sectors Type 00 FS_FAT_VolOpen File system found Type FAT12 Sec size 512 B Clus size 8 sec Vol size 8192 sec Clus 1018 FATs G t opened volume mounted init ded Figure 14 1 NAND detection trace output 145 NAND Flash Driver 14 3 1 DRIVER ARCHITECTURE When used with a NAND device the NAND driver is three layered as depicted in the figure below The generic NAND driver as always provides sector abstraction and performs wear leveling to make certain all blocks are used equally Below this the physical layer driver implements a particular command set to read and program the flash and erase blocks Lastly a BSP implements function to initialize the bus interface and access the NAND NAND Driver fs_dev_nand c h Provides generic driver interface e g init read write and performs wear leveling so all blocks are used equally Physical Layer Dr
13. carea Sheedacts devisesaccatesienivadeetlandsdeveeese 293 Fale ChE de eer eeneg aa Avie nan ate 294 FSFile ISEOF sasaki cea aA aad nara ai ck aes 295 FSFE ISEN Zug ege Eessen EE EES eee es eee 296 FSFle IsOpen sch ns ee 297 FSFile LOCKACCEPE cceccceveeseescec anaana aaaea aaa aiina naaa asiana naia luanan 299 FSFile LockGet onandia ege Ee 300 FSFilesLOCkSet areia teins aati dette EE 301 FSFE Openi siniora geg deel Ed de SE Eed ds 302 FSFile POSGEU Zeene EEN EE 305 FSFile POSSet 20 4asgeugeg gedd eege tiene dE dees date E 306 FSFile Query teuer eet ai ina eens eer A 308 FSFile Rd ororena aaaea EE EO AA EAA NAi 309 FSFile TrunCate ess EEER dE eet aaia aaia nataan aii 311 FS File WI enee EB a ae A aia E aA 312 Volume FUNCTIONS EE 314 FSVOIGlOSC AE T AT 316 FSVol Fm EE 317 FSVol_GetDfItVOINAMe ccccesseeccceesseeeeeeeeeseeeeeeeeeseaeeeeenseaaeeeeenenees 319 FSVOl GetVolGnit oreren eienenn anA AA AAE RA AAAA AEA 320 FSVol_GetVolICntMax cccceceeeeeceeeeeeeeeeceeeeseeeeseseeeeeessaneeeeeeeeenens 321 FSVol_GetVoIName ceseeccceeeseneeceeeeseeeeeeeeeseaeeeeenseaaeseeenseaaeeeeeneeaes 322 FSVol SD e eteieeereieedede acts TEEN a edel deg dee 323 FESVol_ISMouinted e zaud Eent sde Sege e cel nes aie 324 FSVol LabelG et w 3 i2 2c 83 cca eaea aA 325 Fayot Fabelen wenn nwa en tines Eeer 327 FSVOIZOPGN ees eeh asst EES 329 FSVOM QUO Ny secede set A E deen eege de eave iene 331
14. fs_dev_nor c fs_dev_nor h PHY fs_dev_nor_amd_1x08 c fs_dev_nor_amd_1x08 h fs_dev_nor_amd_1x16 c fs_dev_nor_amd_1x16 h fs_dev_nor_intel c fs_dev_nor_intel h fs_dev_nor_sst25 c fs_dev_nor_sst25 h fs_dev_nor_sst39 c fs_dev_nor_sst39 h fs_dev_nor_stm25 c fs_dev_nor_stm25 h fs_dev_nor_stm29_1x08 c fs_dev_nor_stm29_1x08 h fs_dev_nor_stm29_1x16 c fs_dev_nor_stm29_1x16 h Template fs_dev_nor _template c lt Cfg fs_dev_nor_template h lt Cfg BSP lt template gt fs_dev_nor_bsp c lt Cfg RAMDisk fs_dev_ram c fs_dev_ram h SD fs_dev_sd c fs_dev_sd h Card fs_dev_sd_card c fs_dev_sd_card h BSP Template fs_dev_sd_card_bsp c lt Cfg SPI fs_dev_sd_spi c fs_dev_sd_spi h 54 Directories and Files BSP Template fs_dev_sd_spi bsp c lt Cfg Template fs_dev_template c lt Cfg fs_dev_template h lt Cfg FAT fs_fat c fs_fat h fs_fat_dir c fs_fat_dir h fs_fat_entry c fs_fat_entry h fs_fat_fat12 c fs_fat_fat12 h fs_fat_fatl6 c fs_fat_fat16 h fs_fat_fat32 c fs_fat_fat32 h fs_fat_file c fs_fat_file h fs_fat_journal c fs_fat_journal h fs_fat_lfn c fs_fat_lfn h fs_fat_sfn c fs_fat_sfn h fs_fat_type h VOS lt template gt fs_os c lt Cfg fs_os h lt Cfg lt rtos_name gt fs_os c fs_os h Source fs_c fs h fs_api c 55 Directories and Files fs_api h fs_buf c fs_buf h fs_cache c fs_cache h fs_cfg_fs h fs_ctr h
15. Access Functions on page 94 108 Chapter File Systems FAT The FAT File Allocation Table file system introduced as a simple file system for small disk drives still predominates the removable storage market because it is supported by all major operating systems Since FAT s inception it has been extended to support larger disks as well as longer file names However it remains simple enough for the most resource constrained embedded system 109 File Systems FAT 9 1 FAT ARCHITECTURE A FAT volume consists of four basic areas 1 Reserved area The reserved area includes the boot sector which contains basic format information like the number of sectors in the volume 2 FAT The FAT is a large table with one entry for each cluster Each entry contains one of three values the free cluster mark indicating that it is not allocated the cluster number of the next entry in the file essentially a link in a list of the file s clusters or the end of cluster mark indicating that it is the final cluster in the file 3 Root directory Note that in FAT32 volumes the root directory is also part of the data area 4 Data area The data area contains files and directories which are just a special type of file 2 FAT Root FAT12 16 Fee Dir Data Area st FAT32 EE Data Area Area Area Figure 9 1 FAT Volume Layout 110 File Systems FAT 9 1 1 FAT12 FAT16 FAT32 The earliest version of FAT th
16. C FS NAME LENGTHS The configuration constants FS CFG MAX PATH NAME LEN FS CFG MAX FILE NAME LEN and FS_CFG MAX VOL NAME LEN in fs_cfg h set the maximum length of path names file names and volume names The constant FS_CFG MAX FULL NAME LEN is defined in fs_cfg_fs h to describe the maximum full name length The path name begins with a path separator character and includes the file name the file name is just the portion of the path name after the last non final path separator character The full name is composed of an explicit volume name optionally and a path name the maximum full name length may be calculated 63 Miscellaneous FullNameLenmax VolNameLenmax PathNameLenmax Figure 2 3 demonstrates these definitions Le full name cl LE A myvolume MyDir0 MyDir1 MyDir2 my_very_very_long_file_name txt EE parent name cl ben file name volume name Figure 4 1 File path and volume name lengths No maximum parent name length is defined though one may be derived The parent name must be short enough so that the path of a file in the directory would be valid Strictly the minimum file name length is 1 character though some OSs may enforce larger values eleven on some Windows systems thereby decreasing the maximum parent name length ParentNameLenmax PathNameLenmax FileNameLenmin 1 The configuration constants FS_CFG MAX DEV _DRV_NAME LEN and FS CFG MAX DEV NAME LEN in fs_cfg h set the maximum length of
17. CPU_INT32U time start uer CPU_BOOLEAN rdy GET CURRENT TIME IN MICROSECONDS time_start_us time_cur_us time_cur_us while time_cur_us time_start_us lt to_us 1 rdy poll _fnct p phy data 2 if rdy DEF_OK return DEF OK time cur_us GET CURRENT TIME IN MICROSECONDS return DEF_FAIL 3 Listing C 7 FSDev_NOR_BSP_WaitWhileBusy without hardware read busy signal LC 7 1 At least oO us microseconds should elapse before the function gives up and returns Returning early can cause disruptive timeout errors within the physical layer driver LC 7 2 poll_fnct should be called with p_phy_data as its sole argument If it returns DEF_OK then the device is ready and the function should return DEF_OK LC 7 3 If to_us microseconds elapse without the poll function or hardware ready busy signaling indicating success the function should return DEF_FAIL C 11 NOR Flash SPI BSP The NOR driver must adapt to the specific hardware using a BSP A serial NOR Flash will be interfaced on a SPI bus See Appendix C SPI BSP on page 494 for the details on how to implement the software port for your SPI bus 466 LUC FS Porting Manual C 12 SD MMC Cardmode BSP The SD MMC cardmode protocol is unique to SD and MMC compliant devices The generic driver handles the peculiarities for initializing reading and writing a card including state transitions and error handling but
18. FS ERR VOL INVALID SEC SIZE FS ERR VOL INVALID CLUS SIZE FS ERR VOL INVALID OP FS ERR VOL INVALID SEC NBR FS ERR VOL INVALID SYS FS ERR VOL NO CACHE FS ERR VOL NONE AVAIL FS ERR VOL NONE EXIST FS ERR VOL NOT OPEN FS ERR VOL MOT MOUNTED FS ERR VOL ALREADY OPEN FS ERR VOL FILES OPEN FS ERR VOL DIRS OPEN FS ERR JOURNAL ALREADY OPEN FS ERR JOURNAL CFG CHANGED FS ERR JOURNAL FILE INVALID FS ERR JOURNAL FULL FS ERR JOURNAL LOG INVALID ARG FS ERR JOURNAL LOG INCOMPLETE FS ERR JOURNAL LOG NOT PRESENT FS ERR JOURNAL NOT OPEN FS ERR JOURNAL NOT REPLAYING FS ERR JOURNAL NOT STARTED FS ERR JOURNAL NOT STOPPED FS ERR VOL LABEL INVALID FS ERR VOL LABEL NOT FOUND FS ERR VOL LABEL TOO LONG LIC FS Error Codes SEN is not avail LFN entry orphaned Invalid volume name Invalid volume size Invalid volume sector size Invalid volume cluster size Volume operation invalid Invalid volume sector number Invalid file system on volume No cache assigned to volume No vol avail No vols exist Vol NOT open Vol NOT mounted Vol already open Files open on vol Dirs open on vol Journal already open File system suite cfg changed since log created Journal file invalid Journal full Invalid arg read from journal log Log not completely entered in journal Log not present in journal Journal not open Journal not being replayed Journaling not started Journaling not stopped Volume label is invalid Vol
19. FS_DEV_NAND lt device_name gt C PG DEV NAND lt device_name gt H The physical layer driver acts via a BSP The generic drivers for traditional NAND flash require a BSP as described in Appendix C NAND Flash BSP on page 440 The drivers for SPI flash like Atmel Dataflash require a SPI BSP as described in Appendix C NAND Flash SPI BSP on page 450 Parallel Interface Physical Layer Driver fs_dev_nand_0512_x08 fs_dev_nand_2048_x08 fs_dev_nand_2048_x16 Accesses NAND on a bus interface Initialize uninitial ize read write on the NAND Device Jfs_dev_nand_bsp c Jfs_dev_nand_bsp c NAND Driver Jfs_dev_nand c h Provides generic driver interface e g init read write and performs wear leveling so all blocks are used equally Serial Interface Physical Layer Driver fs_dev_nand_at45 Accesses NAND on an SPI interface BSP BSP Initialize uninitial ize read write on the SPI interface NAND Device Figure C 3 NAND Driver Architecture 426 LUC FS Porting Manual Each physical layer driver must implement the functions to be placed into a FS_DEV_NAND PHY APT structure const FS_DEV_NAND PHY API FSDev_NAND FSDev_NAND_PHY_Open FSDev_NAND_PHY_Close FSDev_NAND_PHY_RdPage FSDev_NAND_PHY_RdSpare FSDev_NAND_PHY_WrPage FSDev_NAND_PHY_WrSpare FSDev_NAND_PHY_CopyBack FSDev_NAND_PHY_EraseBlk FSDev_NAND_PHY_IO Ctrl ti The functions which must be implemented are
20. FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout error RETURNED VALUE None NOTES WARNINGS None 457 LUC FS Porting Manual C 9 6 IOC void IO Ctrl FS_DEV_NOR PHY DATA p phy data CPU_INTO8U opt void p data FS_ERR p err File Called from Code enabled by NOR physical layer driver various N A Perform NOR device I O control operation ARGUMENTS p phy data Pointer to NOR phy data opt Control command p data Buffer which holds data to be used for operation OR Buffer in which data will be stored as a result of operation p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Control operation performed successfully FS ERR DEV INVALID IO CTRL I O control unknown to driver FS_ERR_DEV_INVALID OP Invalid operation for device FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout error RETURNED VALUE None NOTES WARNINGS None 458 LUC FS Porting Manual C 10 NOR Flash BSP A traditional NOR flash has two buses one for addresses and another for data For example the host initiates a data read operation with the address of the target location latched onto the address bus the device responds by outputting a data word on the data bus A BSP abstracts the flash interface for the physical layer driver The port includes one code file FS DEV_NOR_BSP C This file is generally placed with other
21. command CPU_INT16U p cmd gt Cmd lt lt 8 Calc command register value 3 if DEF_BIT IS SET p_cmd gt Flags FS_DEV_SD CARD CMD FLAG DATA START DEF YES command BIT COMMAND DATA PRESENT if DEF_BIT_IS SET p_cmd gt Flags FS _DEV_SD CARD CMD FLAG IX VALID DEF YES command BIT COMMAND DATA COMMAND IX CHECK if DEF_BIT IS SET p_cmd gt Flags FS_DEV_SD CARD CMD FLAG CRC_ VALID DEF_YES command E BIT COMMAND DATA COMMAND CRC CHECK if DEF_BIT_IS_SET p_cmd gt Flags FS_DEV_SD_CARD_CMD_FLAG_RESP DEF YES if DEF_BIT_IS_SET p_cmd gt Flags FS_DEV_SD_CARD_CMD_FLAG_RESP_LONG DEF_YES command BIT_COMMAND DATA COMMAND RESPONSE LENGTH_136 else if DEF_BIT_IS_SET p_cmd gt Flags FS DEV Sp CARD CMD FLAG BUSY DEF YES command BIT_COMMAND DATA COMMAND RESPONSE LENGTH 48 else command BIT_COMMAND DATA COMMAND RESPONSE LENGTH 48 BUSY H 475 LUC FS Porting Manual Write registers to exec cmd 4 REG SDMA ADDESS p data REG BLOCK _ COUNT p_cmd gt BlkCnt REG BLOCK SIZE p cmd gt BlkSize REG_ARGUMENT p_cmd gt Arg REG_TRANSFER_MODE transfer_mode REG_COMMAND command p err FS DEV_SD CARD ERR NONE LC 8 1 LC 8 2 LC 8 3 LC 8 4 Listing C 8 FSDev_SD_Card_BSP_CmdStart Check whether the controller is busy Though no successful operation should return without the controller idle an error condition programming mistake o
22. opened device r n Low fmt invalid opened device not low level formatted r n d 4 ay low level format failed r n sd r n r n err Device error 157 NOR Flash Driver dE ME of FSVol_Open CPU_CHAR nor 0 a CPU_CHAR nor 0 b FS PARTITION NBR 0 c FS_ERR amp err switch err case FS_ERR_NONE APP_TRACE_DBG Opened volume mounted r n break case FS _ERR_PARTITION_NOT FOUND Volume error Gi APP_TRACE_DBG opened device not formatted r n FSVol_Fmt nor 0 void 0 amp err 6 if err FS ERR NONE APP_TRACE DBG format failed r n return DEF FAIL break default Device error ef APP_TRACE_DBG opening volume failed w err d r n r n err return DEF FAIL return DEF_OK Listing 15 1 Opening a NOR device volume 115 101 Register the NOR device driver FSDev_NOR L15 1 2 The NOR device configuration should be assigned For more information about these parameters see section D 4 FS_DEV_NOR_CFG on page 513 L15 1 3 FSDev_Open opens initializes a file system device The parameters are the device name 3a and a pointer to a device driver specific configuration structure 3b The device name a s composed of a device driver name nor a single colon an ASCII formatted integer the unit number and another colon L15 1 4 FSDev_
23. or wtb FS FILE ACCESS MODE RD FS FILE ACCESS MODE WR FS FILE ACCESS MODE CREATE FS FILE ACCESS MODE TRUNC at or abt or atb FS FILE ACCESS MODE RD FS FILE ACCESS MODE WR FS FILE ACCESS MODE CREATE FS FILE ACCESS MODE APPEND Table 7 2 fopen mode strings and mode equivalents 7 1 2 GETTING INFORMATION ABOUT A FILE Detailed information about an open file such as size and date time stamps can be obtained using the FSFile Query function FS_ENTRY_INFO info FSFile Query p file lt file pointer amp info lt pointer to info structure amp err lt return error The FS_ENTRY_INFO structure has the following members 100 Files E Attrib contains the file attributes see section 7 2 1 File and Directory Attributes on page 104 D Size is the size of the file in octets E DateTimeCreate is the creation timestamp of the file E DateAccess is the access timestamp date only of the file E DateTimeWr is the last write or modification timestamp of the file E BlkCnt is the number of blocks allocated to the file For a FAT file system this is the number of clusters occupied by the file data a size of a cluster BlkSize is the size of each block allocated in octets For a FAT file system this is the DateTimeCreate DateAccess and DateTimeWr are structures of type CLK_TS_SEC 7 1 3 CONFIGURING A FILE BUFFER The file module has functions t
24. p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE File copied successfully FS_ERR_NULL PTR Argument name _full_src or name full dest passed a NULL pointer FS_ERR_NAME INVALID Entry name specified invalid OR volume could not be found FS ERR NAME PATH TOO LONG Entry name specified too long FS_ERR_VOL_NOT_OPEN Volume was not open FS_ERR_VOL_NOT MOUNTED Volume was not mounted FS_ERR_BUF_NONE AVAIL Buffer not available FS_ERR_DEV Device access error 276 LC FS API Reference Manual Or entry error See section B 8 Entry Error Codes on page 378 RETURNED VALUE None NOTES WARNINGS 1 name full src must be an existing file It may not be an existing directory 2 If excl is DEF_NO name_full_dest must either not exist or be an existing file it may not be an existing directory If excl is DEF_YES name full dest must not exist 277 LC FS API Reference Manual A 5 3 FSEntry_Create void FSEntry Create CPU_CHAR name_full FS_FLAGS entry type CPU_BOOLEAN excl FS_ERR p err File Called from Code enabled by fs_entry c Application not FS_CFG_RD_ONLY_EN fs_mkdir Create a file or directory See also fs_mkdir ARGUMENTS name full Name of the entry See section 4 3 uC FS File and Directory Names and Paths on page 62 entry type Indicates whether the new entry shall be a directory or a file see Note 1 FS_ ENTRY TYPE DIR if the en
25. struct dirent 0 Chk if file is dir if DEF_BIT IS SET dirent Info Attrib FS ENTRY ATTRIB DIR DEF YES str 0 dir Chk if file is rd only 94 POSIX API if DEF_BIT IS SET dirent Info Attrib FS _ENTRY_ATTRIB WR DEF_YES str 2 wW str 5 w str 8 w Get file size EA if p_dirent gt Info Size 0 if DEF_BIT_IS_CLR dirent Info Attrib FS_ENTRY_ ATTRIB DIR DEF_YES Str_Copy amp str 11 0 else Str_FmtNbr_Int32U dirent Info Size 10 10 0 DEF_NO DEF NO amp str 11 Get file date time if p_dirent gt Info DateTimeCreate Month 0 Str_Copy amp str 22 CPU_CHAR App MonthNames dirent Info DateTimeCreate Month 1 Str_FmtNbr_Int32U dirent Info DateTimeWr Day 2 10 DEE MO DEF_NO amp str 26 Str_FmtNbr_Int32U dirent Info DateTimeWr Hour 2 10 DEF_NO DEF NO amp str 29 Str_FmtNbr_Int32U dirent Info DateTimeWr Minute 2 10 DEE NO DEF NO amp str 32 Output info for entry Es APP_TRACE_INFO s s r n str dirent Name Rd next dir entry void fs_readdir_r pdir amp dirent amp p_dirent fs_closedir p dir Close dir If dir could not be opened dir does not exist EA APP_TRACE_INFO Dir does not exist s r n p_cwd_path Listing 6 5 Directory Listing Output example 95 POSIX API COM1 PuTTY
26. tbiedieeen ebe eege cette enak aiaa iaiaaeaia 150 NOR Flash Dniver E 151 Files and Directories csi 5 cecccsc secs te eent eaa aaa a aea aa iaaiiai aaia 152 Driver amp Device Characteristics cccccccccssessssesessssssssssessseeeeeeeeeeees 154 Using a Parallel NOR Device cceecceceseeeeeeeeeeneeeeeeeeeeeeeeeeeeseeeeeeeeenes 156 Driver Architecture Zeie oy saves sentenced exec kves P E e aat aarian Ss 160 Hard ME EE 160 NOR BSP OVerviIeW e eee aide eit ths 162 Using a Serial NOR Device cccccecceeseeeeeeeeeeeeeeeeeeeeseeeseeesaneeeeeeees 163 Hard Wate EE 164 NOR SPI BSP Overview cccccccseeeeeeeeeeeeeeeeesseseseseeeeeeeaeaeaseeeeeeeeeees 165 Physical Layer Drivers ccseecccceseeeeeeeeeeeeeeeeeeeseeeeeeeeseeeseeeeeseaeseeeeeenes 166 FSDev_NOR_AMD_1x08 FSDev_NOR_AMD_1x16 00000 167 FSDev NOR Bit AT 167 FSDev NOR SST O aea aaa a a inne e EN 168 FSDev NOR STM enee a a a a aa a aaa a eaaa ai ta ira ae na 168 FSDev NOR2SS sees aa a raaraa a A EN ENEE Ee dE EEN 169 RAM DISK Drivel deed dE aa a aa A deen 170 Files andi Directories iv eege a ee a e 170 Using the RAM Disk Driver sussssssnsssununnnrnnunrnnnnnnnnnnunnnnnnnnnnnnnnnnnnnnnnn 171 SD MMG Divers k aaaea aa eaa aaaea aaa aE aii ae deg de ea 174 17 1 17 2 17 2 1 17 2 2 17 2 3 17 3 17 3 1 17 3 2 17 3 3 Appendix A A 1 A 1 1 A 1 2 A 1 3 A 1 4 A 1 5 A 2 A 2 1 A 2 2 A 2 3 A 2 4 A 2 5 A 2 6 A 2 7 A 2 8 A 2 9
27. to be deleted later P Invalid cluster The cluster specified in a directory entry or linked in a chain may be invalid The only recourse is to zero the cluster Gf in a directory entry or replace with end of cluster Gf in a chain 116 File Systems FAT E Chain length mismatch Too many or too few clusters may be linked to a file compared to its size If too many the extra clusters should be freed If too few the file size should be adjusted P Lost cluster A lost cluster is marked as allocated in the FAT but is not linked to any file Optionally lost cluster chains may be recovered to a file 9 2 3 JOURNALING Since cluster allocation information is stored separately from file information and directory entries most operations such as adding data to a file are non atomic The repercussions can be innocuous e g wasted disk space or serious e g directory corruption C FS includes an optional journaling add on to its FAT system driver System actions such as creating a new file are wrapped by updates to a special journal file The journal is a compendium of logs descriptions of the system before and after When an operation is started an enter log is added to the journal upon completion an exit log is added Logs for more complex operations may be nested the outer log giving additional context to the inner void App InitFS void FS_ERR err Init the FS Open Device and Volume s FS_FAT_Jour
28. A 2 10 A 2 11 A 2 12 A 2 13 A 2 14 A 2 15 A 2 16 A 2 17 A 2 18 A 2 19 A 2 20 Files and Directories l uc cesses sessed enges dss geed dees Neue de Ee 176 Using the SD MMC CardMode Driver cccccccesseecceeesseeeeeeeeeseeeeeeeeeeees 177 SD MMC CardMode Communication ee EEN 180 SD MMC CardMode Communication Debugging See 182 SD MMC CardMode BSP Overview ccecceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeenees 187 Using the SD MMC SPI Driver esssesseeeeeeeeeeeeeeeeeeeeeeeseeeeeeeeeees 189 SD MMC SPI Communication EENEG 193 SD MMC SPI Communication Debugging esesseeeeeeeeeeeeeeeeeneereeeens 194 SD MMC SPI BSP OVerView cccccesscceeeeesseeeeeeeesseeeeeessseeeeeneeseseeeens 197 uC FS API Reference Manual ccccccceseeeeseeseeeeeeeeeeeeeeeeeeeeeeeneaees 198 General File System FUNCTIONS ccccceeeeeeneeeeeeeeeeeeeeseeeneeeenseeeneeeenes 200 FS DevDrvAda ccica ciecessvendentsteedereestel E T 201 FS ott zegee deeg det ege Mendel del de deel a Ra ead 203 EELEE A E E 204 FS WorkingDirGet anesini EEGEN dese 205 FS WorkingDirSet ici sessececcsscccteecesesteecesccntenceces nadana iiaae SEENEN SEA 206 P six API FUNCIONS aain iaeni ennan in inaidai aiana eiaha dandani aiaiai aa 207 fs asctime r erria ananena ete Aaa aaa aaaea aaan aa aaa a a aAa anaana ninina 210 LE CHOIR EE 211 TS CLS AOU E 212 Te closed EE 213 te CUIME E 214 Ee 215 TS TOON E 216 EC NEE 217 FS UTC Tt SE 218 E te Et gi
29. ATA Host NAND NOR SD MMC Figure C 1 uC FS Ports Architecture pC Clk act as a centralized clock management module If you use an external real time clock you will have to write functions to let uC FS know the date and time The CPU port within pC CPU adapts the file system suite to the CPU and compiler characteristics The fixed width types eg CPU_INT16U used in the file system suite are defined here The RTOS port adapts the file system suite to the OS kernel if any included in the application The files FS_OS C H contain functions primarily aimed at making accesses to devices and critical information in memory thread safe uC FS interfaces with memory devices through drivers following a generic driver model It is possible to create a driver for a different type of device from this model template 384 FC 1 5 FC 1 6 PC IO FC 1 8 FC 1 9 FC 1 10 FC 1 11 FC 1 12 FC 1 13 LUC FS Porting Manual The IDE CF driver can be ported to any ATA host controller or bus interface The NAND driver can be ported for many physical organizations page size bus width etc The NAND driver can be ported to any bus interface A NAND device can also be located directly on GPIO and accessed by direct toggling of port pins The NAND driver can be ported to any SPI peripheral for SPI flash A NAND device can also be located directly on GPIO and accessed by direct toggling of port pins
30. Argument p file or p info passed a NULL pointer Argument p file s type is invalid or unknown File NOT open 308 LC FS API Reference Manual A 6 15 FSFile_Rd CPU_SIZE T FSFile Rd FS_FILE p file void p dest CPU_SIZE T size FS_ERR p err File Called from Code enabled by fs file c Application N A fs_fread Read from a file See fs_fread for more information ARGUMENTS p file Pointer to a file p dest Pointer to destination buffer size Number of octets to read p err Pointer to variable that will the receive return error code from the function FS_ERR_NONE File read successfully FS_ERR_EOF End of file reached FS_ERR_NULL PTR Argument p file p dest passed a NULL pointer FS_ERR_INVALID TYPE Argument p file s type is invalid or unknown FS_ERR_FILE MOT OPEN File NOT open FG ERR FILE INVALID OP Invalid operation on file FS_ERR_DEV Device access error 309 RETURNED VALUE The number of bytes read if file read successful 0 otherwise NOTES WARNINGS None LC FS API Reference Manual 310 LC FS API Reference Manual A 6 16 FSFile_Truncate void FSFile Truncate FS_FILE p file FS FILE SIZE size FS_ERR p err File Called from Code enabled by fs file c Application not FS_CFG_RD_ONLY_EN fs_ftruncate Truncate a file See fs_ftruncate for more information ARGUMENTS p file Pointer to a file size Size of the file after truncation p err Pointer to variable t
31. Below this the physical layer driver implements a particular command set to read and program the flash and erase blocks Lastly a BSP implements function to initialize and unitialize the bus interface Device commands are executed by direct access to the NOR at locations appropriately offset from the configured base address NOR Driver fs_dev_nor c h Provides generic driver interface e g init read write and performs wear leveling so all blocks are used equally Physical Layer Driver fs_dev_nor_amd_1x16 fs_dev_nor_cfi_intel fs_dev_nor_cfi_sst39 Implements particular NOR flash command set accesses NOR directly on bus interface Bus interface BSP fs_dev_nor_bsp c Initialize uninitial ize bus interface Figure 15 2 NOR driver architecture parallel NOR flash 15 3 2 HARDWARE Parallel NOR devices typically connect to a host MCU MPU via an external bus interface EBD with an 8 or 16 bit data lines and 20 or more address lines depending on the device size Many silicon vendors offer parallel NOR product lines most devices currently marketed are conformant to the Common Flash Interface CFI A set of query information allows the pC FS NOR driver physical layer drivers to interface with almost any NOR flash without configuration or modification The standard query information provides the following details 160 NOR Flash Driver E Command set Three different command sets are common Intel AMD and
32. Data registers see section A 11 SD MMC Driver Functions on page 364 FS ERR App FS AddSD SPI void FS_ERR err FS_DevDrvAdd FS_DEV_API amp FSDev_SD_SPI 1 FS_ERR amp err if err FS ERR NONE amp amp err FS ERR DEV DRV ALREADY ADDED return DEF FAIL 190 SD MMC Drivers 2 FSDev_Open CPU_CHAR sd 0 a void 0 b ES PER amp err switch err case FS_ERR_NONE break case ES ERR DEV case PS ERR DEV IO case FS_ERR_DEV_TIMEOUT case PS ERR DEV HOT PRESENT return DEF_FAIL default return DEF_FAIL fe N SA FSVol_Open CPU_CHAR sd 0 a CPU_CHAR sd 0 b FS_PARTITION NBR 0 L c FS_ERR amp err switch err case FS_ERR_NONE APP_TRACE_DBG Opened volume mounted r n break case FS_ERR_DEV case PS ERR DEV_I0 case FS_ERR_DEV_TIMEOUT case PS ERR DEV NOT PRESENT case FS_ERR PARTITION NOT FOUND APP_TRACE_DBG opened device unmounted r n return DEF_FAIL default APP_TRACE_DBG opening volume failed w err d r n r n err return DEF_FAIL return DEF_OK Listing 17 2 Opening a SD MMC device volume L17 2 1 Register the SD MMC SPI device driver FSDev_SD_SPT 191 L17 2 2 117 23 SD MMC Drivers FSDev_Open opens initializes a file system device The parameters are the device name la and a pointer to a device driver
33. FS_ERR_DEV_INVALID SEC SIZE Invalid device sector size FS_ERR_DEV_INVALID SIZE Invalid device size FS_ERR_DEV_INVALID UNIT NR Specified unit number invalid FS ERR NAME NULL Argument name_dev passed a NULL pointer Or device access error see section B 4 Device Error Codes on page 377 RETURNED VALUE DEF_YES if the device has not changed DEE MO if the device has not changed 264 LC FS API Reference Manual NOTES WARNINGS 1 If device has changed all volumes open on the device must be refreshed and all files closed and reopened A device status change may be caused by a A device was connected but no longer is b A device was not connected but now is c A different device is connected 265 LC FS API Reference Manual A 3 13 FSDev_Wr void FSDev_Wr CPU_CHAR name_dev void p src FS_SEC_ NBR start FS_SEC_QTY cnt FS_ERR p err File Called from Code enabled by not FS_CFG_RD_ONLY_EN fs_dev c Application Write data to device sector s ARGUMENTS name_dev Device name p sre Pointer to source buffer start Start sector of write cnt Number of sectors to write p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Sector s written FG ERR NAME NULL Argument name_dev passed a NULL pointer FS_ERR_NULL PTR Argument p sre passed a NULL pointer Or device access error see section B 4 Device Error Codes on page 37
34. Function Description FSEntry AttribSet Set a file or directory s attributes FSEntry_Copy Copy a file FSEntry_Create Create a file or directory FSEntry_Del Delete a file or directory FSEntry_Query Get information about a file or directory FSEntry_Rename Rename a file or directory FSEntry_TimeSet Set a file or directory s date time Table 7 3 Entry API Functions 103 Files 7 2 1 FILE AND DIRECTORY ATTRIBUTES The FSEntry Query function gets information about file system entry including its attributes which indicate whether it is a file or directory writable or read only and visible or hidden FS_FLAGS attrib FS ENTRY INFO info FSEntry Query path_name amp info amp err attrib info Attrib lt pointer to full path name lt pointer to info lt return error The return value is a logical OR of attribute flags FS ENTRY ATTRIB RD FS ENTRY ATTRIB WR FS ENTRY ATTRIB HIDDEN FS ENTRY ATTRIB DIR FS ENTRY ATTRIB ROOT DIR Entry is readable Entry is writable Entry is hidden from user level processes Entry is a directory Entry is a root directory If no error is returned and FS_ENTRY_ATTRIB DIR is not set then the entry is a file An entry can be made read only or writable or hidden or visible by setting its attributes The second argument should be the logical OR of relevant attribute flags 104 Files attrib FS_ENTRY_ATTRIB_RD FSEn
35. IA 92 4096 and the RAM usage is approximately templ 32 8 32 2 68 temp2 4096 2 8192 temp3 FL TOTAL 68 8192 512 8772 D In this example as in most situations increasing the sector size will decrease the RAM usage If the sector size were 1024 B only 5188 B would have been needed but a moderate performance penalty would be paid 155 NOR Flash Driver 15 3 USING A PARALLEL NOR DEVICE To use the NOR driver five files in addition to the generic file system files must be included in the build E fs dev_nor c E fs dev_nor h E fs dev nor bsp c located in the user application or BSP E A physical layer driver typically one provided in Micrium Software uC FS Dev NOR PHY The file fs dev_nor h must also be included in any application or header files that directly reference the driver for example by registering the device driver The following directories must be on the project include path E Micrium Software uC FS Dev NOR P Micrium Software uC FS Dev NOR PHY A single NOR volume is opened as shown in Table 15 1 The file system initialization FS_Init function must have previously been called ROM characteristics and performance benchmarks of the NOR driver can be found in section 10 1 1 Driver Characterization on page 121 The NOR driver also provides interface functions to perform low level operations see section A 10 NOR Driver Functions on page 350 15
36. IEEE Std 1003 1 The basis of some of this functionality in particular buffered input output lies in the ISO C standard ISO IEC 9899 though many extensions provide new features and clarify existing behaviors Functions and macros prototyped in four header files are of particular importance stdio h Standard buffered input output fopen fread etc operating on FILE objects dirent h Directory accesses opendir readdir etc operating on DIR objects unistd h Miscellaneous functions including working directory management chdir getcwd ftruncate and rmdir sys stat h File statistics functions and mkdir uC FS provides a POSIX compatible API based on a subset of the functions in these four header files To avoid conflicts with the user compilation environment files functions and objects are renamed 4 All functions begin with fs For example fopen is renamed fs_fopen opendir is renamed fs_opendir getcwd is renamed fs_getcwd etc All objects begin with FS_ So fs_fopen returns a pointer to a FS FILE and fs_opendir returns a pointer to a FS_DIR Some argument types are renamed For example the second and third parameters of fs fread are typed fs_size t to avoid conflicting with other size_t definitions 83 POSIX API 6 1 SUPPORTED FUNCTIONS The supported POSIX functions are listed in the table below These are divided into four groups First the functions
37. Receives information about a volume MEMBERS State The volume state FS VOL STATE CLOSED FS VOL STATE CLOSING FS VOL STATE OPENING FS VOL STATE OPEN FS VOL STATE PRESENT FS VOL STATE MOUNTED DevState The device state FS DEV STATE CLOSED FS DEV STATE CLOSING FS DEV STATE OPENING FS DEV STATE OPEN FS DEV STATE PRESENT Second argument of FSVol_Query Volume is closed Volume is closing Volume is opening Volume is open Volume device is present Volume is mounted Device is closed Device is closing Device is opening Device is open but not present Device is present but not low level formatted 523 LIC FS Types and Structures FS DEV STATE LOW FMT VALID Device low level format is valid DevSize The number of sectors on the device DevSecSize PartitionSize VolBadSecCnt VolFreeSecCnt VolUsedSecCnt VolTotSecCnt NOTES None The size of each device sector The number of sectors in the partition The number of bad sectors on the volume The number of free sectors on the volume The number of used sectors on the volume The total number of sectors on the volume 524 Appendix UC FS Configuration uC FS is configurable at compile time via approximately 30 defines in an application s fs_cfg h file uC FS uses defines because they allow code and data sizes to be scaled at compile time based on enabled features In other words this allows the ROM and RAM footprints
38. This value must be between 5 and 100 except if 0 is specified whereupon the default will be used 20 PhyPtr MUST point to the appropriate physical layer driver FSDev_NOR_AMD 1x08 CFl compatible parallel NOR implementing AMD command set 8 bit data bus FSDev_NOR_AMD 1x16 CFl compatible parallel NOR implementing AMD command set 16 bit data bus FSDev_NOR_ Intel 1x16 CFl compatible parallel NOR implementing Intel command set 16 bit data bus FSDev_NOR_SST39 SST SST39 Multi Purpose Flash FSDev_NOR_STM25 ST M25 serial flash FSDev_NOR_SST25 SST SST25 serial flash Other User developed 514 NOTES None LIC FS Types and Structures For a parallel NOR the bus configuration is specified via BusWidth BusWidthMax and PhyDevCnt BusWidth is the bus width in bits between the MCU MPU and each connected device BusWidthMax is the maximum width supported by each connected device PhyDevCnt is the number of devices interleaved on the bus For a serial flash the maximum clock frequency is specified via MaxClkFreq 515 LIC FS Types and Structures D 5 FS_DEV_RAM CFG typedef struct fs deu ram cfg FS_SEC_ SIZE SecSize FS SEC QTY Size void DiskPtr FS_DEV_RAM CFG File Used for fs_dev_ramdisk h Second argument of FSDev_Open when opening a RAM disk Configures the properties of a RAM disk that will be opened A pointer to this structure is passed as the second argument of FSDev_Open for a
39. Yes Yes No Yes Yes Table 6 2 fs_fopen mode strings interpretations After a file is opened any of the file access functions valid for that its mode can be called The most commonly used functions are fs_fread and fs_fwrite which read or write a certain number of items from a file number of items read gt cnt fs_fread p buf lt pointer to buffer Ty lt size of each item 100 lt number of items p_file lt pointer to file The return value the number of items read or written should be less than or equal to the third argument If the operation is a read this value may be less than the third argument for one of two reasons First the file could have encountered the end of file EOF which means that there is no more data in the file Second the device could have been removed or some other error could have prevented the operation To diagnose the cause the fs_feof function should be used This function returns a non zero value if the file has encountered the EOF Once the file access is complete the file must be closed if an application fails to close files then the file system suite resources such as file objects may be depleted An example of reading a file is given in Listing 6 1 88 void App Fnct void POSIX API FS_FILE p file fs_size t cnt unsigned char buf 50 p_file fs_fopen file txt r Open file af if p file FS_FILE 0 If
40. a p file fs fopen file txt w b p file fs fopen sd 0 dir01 fileO1l txt w c p file fs _opendir sd 0 d p file fs_opendir e p file fs opendir sd 0 dir01 62 Miscellaneous Which demonstrate a opening a file in the root directory of a specified volume b opening a file in the root directory on a default volume c opening a file in a non root directory d opening the root directory of a specified volume e opening the root directory of the default volume f opening a non root directory Relative paths can be used if working directories are enabled FS_CFG_WORKING DIR EN is DEF _ ENABLED see Appendix E FS_CFG_WORKING_DIR_EN on page 529 A relative path begins with neither a volume name nor a V lt Relative Path gt lt File gt where lt Relative Path gt is the file path which must not begin with a V but must end with a V lt File gt is the file or leaf directory name including any extension Two special path components can be used moves the path to the parent directory keeps the path in the same directory basically it does nothing A relative path is appended to the current working directory of the calling task to form the absolute path of the file or directory The working directory functions fs_chdir and fs_getcwd can be used to set and get the working directory 4 4
41. access mode amp err lt return error if p file FS_FILE 0 Handle error The return value of this function should always be verified as non NULL before the application proceeds to access the file The second argument to this function is a logical OR of mode flags FS_FILE ACCESS MODE RD File opened for reads FS_FILE ACCESS MODE WR File opened for writes FS_FILE ACCESS MODE CREATE File will be created if necessary FS_FILE ACCESS MODE TRUNC File length will be truncated to 0 FS_FILE ACCESS MODE APPEND All writes will be performed at EOF FS_FILE ACCESS MODE EXCL File will be opened if and only if it does not already exist FS_FILE ACCESS MODE CACHED File data will be cached For example if you wanted to create a file to write to if and only if it does not exist you would use the flags FS FILE ACCESS MODE WR FS FILE ACCESS MODE CREATE FS FILE ACCESS MODE EXCL 99 Files It is impossible to do this in a single atomic operation using fs_fopen The table below lists the mode flag equivalents of the s_fopen mode strings upr or rb FS_FILE_ACCESS_MODE_RD w or wb FS_FILE ACCESS MODE WR FS FILE ACCESS MODE CREATE FS FILE ACCESS MODE TRUNC a or ab PG FILE ACCESS MODE WR FS FILE ACCESS MODE CREATE PG FILE ACCESS MODE APPEND r or rbt or rtb FS_FILE ACCESS _MODE_RD FS_FILE ACCESS _MODE_WR gt or wbt
42. ee tESEEEERENSER HESE EES EEEE pet ontana aeaiiai 534 EIER Tu DEE 535 Files And Directories 2 cccceeeceeeeeeeeeseeeeeeeeeeeeeeeeseseeesseeeeeeeeeeeeens 536 Using the Shell Commande eseeeecceeeeeeeeeeeeeeeeeeeeeeseeeeeeeeeseeeseeeeeeees 537 elle EE 540 PSE CET 541 ER W 542 EE e EE 544 TSO EC 545 fs EE 546 PSUS ee rcete E A AA de scadcien suc ducitedl E 547 Te Ok Wee che tr ege 548 E UU EE 549 E E 550 E EE 551 PS OC WEE 552 E e EE 553 LC EE 554 LES e Te 555 TS TOUCH eecesseseacscesiccecegeczs tas ated ee e ee ticectia seston 556 TS Te EE 557 PS EWC es ee ee wed tics Eer 558 UU DE e TE 559 BibllOGraphy iis sc eee tec A tine sheds T ted dee eens 561 PGC FS LICENSING PONCY ces iicsccsccsecitecs aiani aaia dra annaia aaan aiant acces 563 C FS Licensing EE 563 HES Source Code eeegeee ataukebueegeeENSE Ek iaiia i ueiaire isi 563 UC FS Maintenance Renewal ccccccecceseeeeeeseeeneeeeeeeeeeeeeeeeeeeeneaees 564 HC FS Source Code Updates cecseceeceeseeneeeeeeeeeneeeeseeeneeeeseneeneeeenees 564 ULOVA nee elio 0X01 a GE 564 Chapter Introduction Files and directories are common abstractions which we encounter daily when sending an e mail attachment downloading a new application or archiving old information Those same abstractions may be leveraged in an embedded system for similar tasks or for unique ones A device may serve web pages play or record media images video or music or log data The
43. fs_def h fs_dev c fs_dev h fs_dir c fs_dir h fs_entry c fs_entry h fs_err c fs_err h fs_file c fs_file h fs_partition c fs_partition h fs_pool c fs_pool h fs_sys c fs_sys h fs_type h fs_unicode c fs_unicode h fs_util c fs_util h fs_vol c fs_vol h VOS lt architecture gt lt compiler gt os_cpu h os_cpu_a asm os_cpu_c c uC CPU 56 cpu_core c cpu_core h cpu_def h Cfg Template cpu_cfg h lt architecture gt lt compiler gt cpu h cpu_a asm cpu_c c Template clk_cfg h lt rtos_name gt clk_os c Source clk c clk h Template erc_cfg h lt architecture gt lt compiler gt ecc_bch 4bit_a asm ecc_bch_8bit_a asm ecc_hamming a asm edc_crc_a asm Source edc_crc h edc_crce c ecc_hamming h ecc_hamming c ecc_bch_ 8bit h ecc_bch_ 8bit c Directories and Files lt Cfg lt Cfg lt Cfg 57 Directories and Files ecc_bch_4bit h ecc_bch_4bit c ecc_bch h ecc_bch c ecc h uC LIB lib_ascii c lib_ascii h lib det hb lib_math c lib math h lib_mem c lib_mem h lib_str c lib_str h Cfg Template lib_cfg h lt Cfg 58 Chapter Miscellaneous This chapter provides information on various concepts used in uC FS We decided to include this chapter early in the pC FS manual so that you can start using uC FS as soon as possible In fact we assume you know little about uC FS and file system
44. is equivalent to void fs_fseek p file 0 FS SEEK SET except that it also clears the error indictor of the file 241 LC FS API Reference Manual A 2 30 fs_rmdir int fs_rmdir const char name full File Called from Code enabled by fs_api c Application FS_CFG_API_EN and not FS_CFG_RD_ONLY_EN Delete a directory ARGUMENTS name full Name of the file RETURNED VALUE 0 if the directory is removed 1 if the directory is NOT removed NOTES WARNINGS 1 A directory can be removed only if it is an empty directory 2 The root directory cannot be removed 242 LIC FS API Reference Manual EXAMPLE 243 LC FS API Reference Manual A 2 31 fs_setbuf int fs_setbuf FS _FILE p file fs size t size File Called from Code enabled by fs_api c Application FS_CFG AGT EN and FS CFG FILE BUF EN Assign buffer to a file ARGUMENTS p file Pointer to a file size Size of buffer in octets RETURNED VALUE 1 if an error occurs 0 if no error occurs NOTES WARNINGS 1 fs_setbuf is equivalent to fs_setvbuf invoked with FS___IOFBF for mode and FS_BUFSIZE for size 244 LC FS API Reference Manual A 2 32 fs_setvbuf int fs_setvbuf FS FILE p file char p buf int mode fs size t size File Called from Code enabled by fs_api c Application FS_CFG AGT EN and FS_CFG FILE BUF_EN Assign buffer to a file ARGUMENTS p file Pointer to a file p buf Point
45. nor 0 Low level formating associates physical areas sectors of the device with logical sector numbers A NOR medium MUST be low level formatted with this driver prior to access by the high level file system a requirement which the device module enforces 352 LC FS API Reference Manual A 10 2 FSDev_NOR_LowMount void FSDev_NOR_LowMount CPU CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev_nor c Application N A Low level mount a NOR device ARGUMENTS name_dev Device name see Note p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Device low level mounted successfully FS ERR NAME NULL Argument name_dev passed a NULL pointer FS ERR DEV_INVALID Argument name_dev specifies an invalid device PG ERR DEV MO ODEN Device is not open PG ERR DEV MO PRESENT Device is not present FS ERR DEV_INVALID LOW FMT Device needs to be low level formatted FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NOR device e g nor 0 Low level mounting parses the on device structure detecting the presence of a valid low level format If FS_ERR_DEV_INVALID_LOW_FMT is returned the device is NOT low level formatted 353 LC FS API Reference Manual A 10 3 FSDev_NOR_LowUnmount void FSDev_NOR_LowUnmount CPU_CHAR name dev FS_ERR p err Fi
46. opening a NOR device Configures the properties of a NOR device that will be opened A pointer to this structure is passed as the second argument of FSDev_Open for a NOR device MEMBERS AddrBase MUST specify 1 the base address of the NOR flash memory for a parallel NOR 2 0x00000000 for a serial NOR RegionNbr MUST specify the block region which will be used for the file system area Block regions are enumerated by the physical layer driver for more information see the physical layer driver header file on monolithic devices devices with only one block region this MUST be 0 513 LIC FS Types and Structures AddrStart MUST specify 1 the absolute start address of the file system area in the NOR flash memory for a paralel NOR 2 the offset of the start of the file system in the NOR flash for a serial NOR The address specified by AddrStart MUST lie within the region RegionNbr DevSize MUST specify the number of octets that will belong to the file system area SecSize MUST specify the sector size for the NOR flash either 512 1024 2048 or 4096 PctRsvd MUST specify the percentage of sectors on the NOR flash that will be reserved for extra file system storage to improve efficiency This value must be between 5 and 35 except if 0 is specified whereupon the default will be used 10 EraseCntDiffTh MUST specify the difference between minimum and maximum erase counts that will trigger passive wear leveling
47. 10 1 1 Chapter 11 11 1 11 2 11 2 1 11 2 2 Chapter 12 Chapter 13 Getting Information About a File cccceessseeeeeeeeeeeeeeeeeeeeeeeeeeseeneeeenees 100 Configuring a File Buffer cccccceesseneeeeeeseeeeeeeeeeeeeeeeeseeeneeeeeneeneeeeenss 101 File Error e Te de 102 Atomic File Operations Using File LOCK csceeccssseeeeeeseeeeeeeeeneeeeeees 102 Entry Access FUNCtIONS cc0 ic ccsessecsienceescetc NENNEN S 103 File and Directory Attributes ceceeeseeeeeee cee ceee eee REENEN 104 Creating New Files and Directories s eeceeeeeeeeeeeeeeeenseeeneeees 105 Deleting Files and Directories cessseseeeeeeeceeeeeeeeeeeeneeeeneeeeeeeeeees 106 DIFECTONCS fie ian cease co ve ENEE dee 107 Directory ACCESS FUNCTIONS 2 cccceeseeeseeeeeeeeeeeee eee eeeeeeeeneeneeeeeeeeeees 108 File Systems FAT eege RENE Eed 109 FAT Areh eC Ue eege dee Ee Eege deeg e 110 FATI2 FAT IG MR 111 Short and Long File Names ccccceesseeeeeeeeeceeeeeeeeeeeneeeeeasseeeeeenseseeeees 111 Directories and Directory Entries ceseeeccesesseeeeeeeeseeeeeeeeeseeeeeeeeeeee 112 FAT System Driver Architecture cccccsseeceeeeeseeeeeeseseeeeeeeeseeeeeeeeeseees 114 Operation 5 epee dices si cestieccen ted cach eases daaa ula aeaa Daaa Eaa aeaa Eae aaa 115 Su le WE 115 IIe 116 JOUNNALING BE 117 D6 VICE BI ANET eegene EE Ee 119 Provided Device Drivers 2 ccccccecesseesseeeeeeceeeeeee
48. 3 4 5 and 6 are standard MCU MPU IDE Drive CF Card D 0 15 D00 D15 A O 2 A00 A02 CS0 CS0 CS1 CS1 IORD IORD IOWR IOWR IORDY IORDY INTRQ INTRQ RESET RESET DMARQ DMARQ DMACK DMACK DASP DASP CD1 CD1 CD2 CD2 CSEL ATA_SEL Figure 11 2 True IDE ATA host device connection 128 Pin Name s IDE CF Driver Function A00 A01 A02 CSO CS1 Address group Use by host to select the register or data port that will be accessed IORD Asserted by host to read register or data port IOWR Asserted by host to write register or data port IORDY INTRQ Interrupt request to the host RESET Hardware reset signal DMARQ Asserted by device when it is ready for a DMA transfer DMACK DMA acknowledge signal asserted by host in response to DMARQ DASP Disk Active Slav Present signal in Master Slave handshake protocol CD1 CD2 Chip detect The host controls the device via 8 registers see Figure 11 3 Seven of these registers comprise the command block FR SC SN CYL CYH DH and CMD The command block registers are written in sequence to execute a command Afterwards the error and status register return to the host a failure indicator or otherwise signal device operation completion The need to poll these registers is removed if the host is instead alerted by an interrupt request on the INTRQ signal to attend to the device Up
49. Application FS_CFG FILE BUF EN fs_fflush Flush buffer contents to file See fs_fflush for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE File buffer flushed successfully FS ERR NULL PTR FS ERR INVALID TYPE FS ERR FILE NOT OPEN RETURNED VALUE None NOTES WARNINGS None Argument p file passed a NULL pointer Argument p file s type is invalid or unknown File NOT open 292 A 6 3 FSFile_Close void FSFile Close FS FILE p file PG ERR p err LC FS API Reference Manual File Called from Code enabled by fs file c Application N A fs_fclose Close and free a file See fs_fclose for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE File closed FS ERR NULL PTR FS ERR INVALID TYPE FS ERR FILE NOT OPEN RETURNED VALUE None NOTES WARNINGS None Argument p file passed a NULL pointer Argument p file s type is invalid or unknown File NOT open 293 LC FS API Reference Manual A 6 4 FSFile_ClrErr void FSFile ClrErr FS FILE p file PG ERR p err File Called from Code enabled by fs file c Application N A fs_clearerr Clear EOF and error indicators on a file See fs_clearerr for more information ARGUMENTS p file Pointer t
50. Dev IDE Each subdirectory contains an example BSP for a particular platform These are named according to the following rubric lt Chip Manufacturer gt lt Board or CPU gt fs_dev_ide bsp c 124 IDE CF Driver 11 2 USING THE IDE CF DRIVER To use the IDE CF driver five files in addition to the generic file system files must be included in the build E fs _dev_ide c located in the directory specified in Section 9 01 E fs _dev_ide h located in the directory specified in Section 9 01 E fs dev ide bsp c located in the user application or BSP The file Ca dev_ide h must also be included in any application or header files that directly reference the driver for example by registering the device driver The following directories must be on the project include path E Micrium Software uC FS Drivers IDE A single IDE CF volume is opened as shown in Listing 11 1 The file system initialization FS _Init function must have been previously called ROM RAM characteristics and performance benchmarks of the IDE driver can be found in section 10 1 1 Driver Characterization on page 121 CPU_BOOLEAN App FS AddIDE void FS_ERR err FS_DevDrvAdd FS_DEV_API amp FSDev_IDE 1 FS_ERR amp err if err FS ERR NONE amp amp err FS ERR DEV DRV ALREADY ADDED return DEF FAIL 2 FSDev_Open CPU_CHAR ide 0 a void 0 b PS ERR amp err 1
51. EN is used to clear internal file system data structures when allocated or deallocated When DEF_ENABLED internal file system data structures will be cleared FS_CFG_DBG_WR_VERIFY_EN FS CFG DBG WR VERIFY FN is used verify writes by reading back data This is a particularly convenient feature while debugging a driver E 5 ARGUMENT CHECKING CONFIGURATION Most functions in uC FS include code to validate arguments that are passed to it Specifically uC FS checks to see if passed pointers are NULL if arguments are within valid ranges etc The following constants configure additional argument checking FS_CFG_ARG CHK EXT EN FS_CFG ARG CHK EXT EN allows code to be generated to check arguments for functions that can be called by the user and for functions which are internal but receive arguments from an API that the user can call 531 UC FS Configuration FS_CFG_ARG CHK _DBG_EN FS CFG ARG CHK DBG EN allows code to be generated which checks to make sure that pointers passed to functions are not NULL that arguments are within range etc E 6 FILE SYSTEM COUNTER CONFIGURATION uC FS contains code that increments coutners to keep track of statistics such as the number of packets received the number of packets transmitted etc Also uC FS contains counters that are incremented when error conditions are detected FS_CFG CTR_STAT_EN FS_CFG CTR STAT EN determines whether the code and data space used to keep track of statistics will be inclu
52. FS Porting Manual void FSDev_NAND BSP _WrWord_08 FS Om unit_nbr CPU_ADDR addr_src CPU_INTO8U datum void FSDev_NAND BSP _WrWord_16 FS Om unit_nbr CPU_ADDR addr_src CPU_INT16U datum File Called from Code enabled by fs_dev_nor_bsp c NOR physical layer driver Write data to bus interface ARGUMENTS unit_nbr Unit number of NOR addr_srce Source address datum Word to write RETURNED VALUE None NOTES WARNINGS N A Data should be written o the bus in words sized to the data bus for any unit only the function with its access width will be called 464 LUC FS Porting Manual C 10 6 FSDev_NOR_BSP_WaitWhileBusy CPU_BOOLEAN FSDev_NOR_BSP_WaitWhileBusy FS_OTY unit_nbr FS DEV NOR PHY DATA p phy data CPU_BOOLEAN poll_fnct FS_DEV_NOR_PHY DATA CPU_INT32U to_us File Called from Code enabled by fs_dev_nor bsp c NOR physical layer driver N A Wait while NAND is busy ARGUMENTS unit_nbr Unit number of NOR p phy data Pointer to NOR phy data poll _fnct Pointer to function to poll if there is no hardware ready busy signal to_us Timeout in microseconds RETURNED VALUE DEF_OK if NAND became ready DEF_FAIL otherwise NOTES WARNINGS None 465 LUC FS Porting Manual CPU_BOOLEAN FSDev_NOR_BSP_WaitWhileBusy FS_QTY unit_nbr FS DEV NOR PHY DATA p phy data CPU_BOOLEAN poll_fnct FS_DEV_NOR PHY DATA CPU_INT32U to_us CPU_INT32U time our oer
53. FS_CFG_RD_ONLY_EN DEF_DISABLED FSDev_NAND LowFmt nand 0 amp err 4 E endif if err FS_ERR_NONE APP_TRACE_DBG low level format failed r n return DEF_FAIL break case FS_ERR_DEV Device error SG case PS ERR DEV_IO case FS_ERR_DEV_TIMEOUT case FS_ERR_DEV_NOT PRESENT default APP_TRACE_DBG opening device failed w err d r n r n err return DEF_FAIL 142 NAND Flash Driver IES 3 E FSVol_Open nand 0 SS a nand 0 Z b 0 EJA amp err switch err case FS_ERR_NONE APP_TRACE_DBG opened volume mounted r n break case FS_ERR PARTITION NOT FOUND Volume error APP_TRACE_DBG opened device not formatted r n if FS_CFG_RD_ONLY_EN DEF DISABLED FSVol_Fmt nand 0 void 0 amp err 6 endif if err FS_ERR_NONE APP_TRACE _DBG e eformat failed r n return DEF FAIL break case FS_ERR_DEV Device error SG case PS ERR DEV 0 case FS_ERR_DEV_TIMEOUT case PS ERR DEV MOT PRESENT APP_TRACE_DBG Opened volume unmounted r n return DEF_FAIL default APP_TRACE_DBG opening volume failed w err d r n r n err return DEF_FAIL return DEF OK Listing 14 1 Opening a NAND device volume L14 1 1 Register the NAND device driver FSDev_NAND 114 1 2 The NAND device configuration should be assigned For more information about these parame
54. JEDEC compatible ID Manufacturer Device Capacity Block Size Block Count SST SST25VF010B 1 Mb 4 KB 32 SST SST25VF020B 2 Mb 4 KB 64 SST SST25VF040B 4 Mb 4 KB 128 SST SST25VF080B 8 Mb 32 KB 32 SST SST25VF016B 16 Mb 32 KB 64 SST SST25VF032B 32 Mb 32 KB 128 Table 15 8 Supported SST25 serial flash 169 Chapter 16 RAM Disk Driver The simplest device driver is the RAM disk driver which uses a block of memory internal or external as a storage medium 16 1 FILES AND DIRECTORIES The files inside the RAM disk driver directory are outlined in this section the generic file system files outlined in Chapter 3 Directories and Files on page 28 are also required Micrium Software uC FS Dev This directory contains device specific files Micrium Software uC FS Dev RAMDisk This directory contains the RAM disk driver files fs_dev_ramdisk constitute the RAM disk device driver 170 RAM Disk Driver 16 2 USING THE RAM DISK DRIVER To use the RAM disk driver two files in addition to the generic FS files must be included in the build E fs_dev_ramdisk c E fs_dev_ramdisk h The file Ce dev_ramdisk h must also be included in any application or header files that directly reference the driver for example by registering the device driver The following directory must be on the project include path E Micrium Software uC FS Dev RAMDisk A single RAM disk is opened as shown in The
55. LEN characters long and must not contain either of the characters V or It is typical to name a volume the same as a device for example a volume may be opened FSVol_Open sd 0 a sd 0 b void 0 amp err 61 Miscellaneous In this case the name of the volume a is the same as the name as the device b When multiple volumes exist in the same application the volume name should be prefixed to the file or directory path name p file fs fopen sd 0 dir01 fileO1 txt w File on SD card fs_fopen ram 0 dir01 file01l txt w File on RAM disk p file 4 3 uC FS FILE AND DIRECTORY NAMES AND PATHS Files and directories are identified by a path string for example a file can be opened p file fs fopen test file001 txt wi In this case test ile001 txt is the path string An application specifies the path of a file or directory using either an absolute or a relative path An absolute path is a character string which specifies a unique file and follows the pattern lt vol_name gt lt Path gt lt File gt where lt vol_name gt is the name of the volume identical to the string specified in FSVol_Open lt Path gt is the file path which must always begin and end with a V lt File gt is the file Cor leaf directory name including any extension For example p file fs fopen sd 0 file txt w
56. LOW FMT then the device is present and responsive but must be low level formatted The application should next call FSDev_NOR_LowFmt for the NOR flash 70 Devices and Volumes m If the return error code is FS ERR _DEV_NOT PRESENT FG ERR DEV_IO or FS ERR DEV TIMEOUT the device is either not present or did not respond This is an important consideration for removable devices It is still registered with the file system suite and the file system will attempt to re open the device each time the application accesses it P If any other error code is returned the device is not registered with the file system The developer should examine the error code to determine the source of the error 5 3 USING REMOVABLE DEVICES uC FS expects that any call to a function that accesses a removable device may fail since the device may be removed powered off or suddenly unresponsive If uC FS detects such an event the device will need to be refreshed or closed and re opened FSDev_Refresh refreshes a device chngd FSDev_Refresh CPU_CHAR ide 0 lt b device name PS ERR amp err lt c return error There are several cases to consider E If the return error is FS_ERR_NONE and the return value a is DEF_YES then a new device e g SD card has been inserted All files and directories that are open on volumes on the device must be closed and all volumes that are open on the device must be closed or refreshed m If the r
57. RAM disk MEMBERS SecSize The sector size of RAM disk either 512 1024 2048 or 4096 Size The size of the RAM disk in sectors DiskPtr The pointer to the RAM disk NOTES None 516 LIC FS Types and Structures D 6 FS_DIR_ENTRY struct fs_dirent typedef struct fs_dirent CPU_CHAR Name FS CFG MAX FILE NAME LEN lu FS ENTRY INFO Info FS_DIR_ENTRY File Used for fs_dir h Second argument of fs_readdir_r and FSDir_Rd Receives information about a directory entry MEMBERS Name The name of the file Info Entry information For more information see section D 2 FS_DEV_INFO on page 510 NOTES None 517 LIC FS Types and Structures D 7 FS_ENTRY_INFO typedef struct fs_entry info FS FLAGS Attrib FS FILE SIZE Size CLK_TS SEC DateTimeCreate CLK_TS_ SEC DateAccess CLK_TS SEC DateTimeWr FS SEC QTY BlkCnt FS SEC SIZE BlkSize FS_ENTRY INFO File Used for fs_entry h Second argument of FSEntry_ Query and FSFileQuery The Info member of FS_DIR_ENTRY struct fs_dirent Receives information about a file or directory MEMBERS Attrib The file or directory attributes see section 7 2 1 File and Directory Attributes on page 104 Size The size of the file in octets DateTimeCreate The creation timestamp of the file or directory DateAccess The last access date of the file or directory DateTimeWr The last write or modification timestamp of the file or director
58. SST All three are supported E Geometry A device is composed of one or more regions of identically sized erase blocks Uniform devices contain only one region Boot block devices often have one or two regions of small blocks for code storage at the top or bottom of the device All of these are supported by the NOR driver Offset Length Bytes Contents 0x10 1 Query string Q 0x11 1 Query string R 0x12 1 Query string Y 0x13 2 Command set 0x27 1 Device size in bytes 2n 0x2A 2 Maximum number of bytes in multi byte write 2N 0x2C 1 Number of erase block regions m 0x2D 2 Region 1 Number of erase blocks x 1 0x2F 2 Region 1 Size of each erase block y 256 bytes 0x31 2 Region 2 Number of erase blocks x 1 0x33 2 Region 2 Size of each erase block y 256 bytes 0x2D m 1 4 2 Region m Number of erase blocks x 1 Ox2F m 1 4 2 Region m Size of each erase block y 256 bytes Table 15 2 CFI query information Table 15 2 gives the format of CFI query information The first three bytes should constitute the marker string QRY by which the retrieval of correct parameters is verified A two byte command set identifier follows this must match the identifier for the command set supported by the physical layer driver Beyond is the geometry information the device size the number of erase block regions and the size and number of blocks in each
59. Specific CPU H CPU_A ASM CPU_CORE C H Software Firmware Directories and Files 1 Application Code APP C H FS_APP C H pC LIB 5 Libraries LIB_ASCII C H LIB_DEF H LIB_MATH C H LIB_MEM C H LIB_STR C H 6 pC Clk Ve CLK C H CLK_OS C H 7 uC CRC ECC H EDC_CRC C H ECC_HAMMING C H 12 uciFs OS Specific FS_OS C H 3 2 BSP CPU Board Support Package BSP C H C SH Memory Devices Hardware Interrupt Controller Figure 3 1 uC FS Architecture 29 F3 1 1 F3 1 2 F3 16 F3 1 4 F3 1 5 F3 1 6 F3 1 7 F3 1 8 Directories and Files The application code consist of project or product files For convenience we simply called these app c and app h but your application can contain any number of files and they do not have to be called app The application code is typically where you would find main Quite often semiconductor manufacturers provide library functions in source form for accessing the peripherals on their CPU Central Processing Unit or MCU Micro Controller Unit These libraries are quite useful and often save valuable time Since there is no naming convention for these files c and h are assumed The Board Support Package BSP is code that you would typically write to interface to peripherals on your target board For example you can have code to turn on and off LEDs light emitting diodes functions to turn on and off relay
60. TRANSFER WIDTH else REG HOST CONTROL BIT HOST CONTROL DATA TRANSFER WIDTH Listing C 12 FSDev_SD_Card_BSP_SetBusWidth 490 LUC FS Porting Manual C 12 10 FSDev_SD_ Card BSP_SetClikFreq void FSDev_SD Card BSP SetClkFreq PG Om unit_nbr CPU_INT32U freq Called from File Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_Refresh N A Set clock frequency ARGUMENTS unit_nbr Unit number of SD MMC card freq Clock frequency in Hz RETURNED VALUE None NOTES WARNINGS The effective clock frequency MUST be no more than freq If the frequency cannot be configured equal to freq it should be configured less than freq 491 LUC FS Porting Manual C 12 11 FSDev_SD Card BSP_SetTimeoutData void FSDev_SD Card BSP SetTimeoutData FS OTY unit_nbr CPU_INT32U to_clks File Called from Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_Refresh N A Set data timeout ARGUMENTS unit_nbr Unit number of SD MMC card to clks Timeout in clocks RETURNED VALUE None NOTES WARNINGS None 492 LUC FS Porting Manual C 12 12 FSDev_SD Card BSP_SetTimeoutResp void FSDev_SD Card BSP SetTimeoutResp FS OTY unit_nbr CPU_INT32U to ms Called from File Code enabled by fs_dev_sd card bsp c FSDev_SD_Card_Refresh N A Set data timeout ARGUMENTS unit_nbr Unit number of SD MMC card to_ms Timeout in milliseconds RE
61. _SetTimeoutData Set data timeout FSDev_SD Card BSP _SetTimeoutResp Set response timeout Table C 7 SD MMC cardmode BSP functions Each BSP must implement the functions in Table C 7 For information about creating a port for a platform accessing a SD MMC device in SPI mode see section C 13 SD MMC SPI mode BSP on page 493 This software interface was designed by reviewing common host implementations as well as the SD card association s SD Specification Part A2 SD Host Controller Simplified Specification Version 2 00 which recommends a host architecture and provides the state machines that would guide operations Example function implementations for a theoretical compliant host are provided in this chapter Common advanced requirements such as multiple cards per slot and optimizations such as DMA are possible No attempt has been made however to accommodate non storage devices that are accessed on a SD MMC cardmode including SDIO devices The core operation being abstracted is the command response sequence for high level card transactions The key functions CmdStart CmdWaitEnd CmdDataRd and CmdDataWr are called within the state machine of Figure C 5 If return error from one of the functions will abort the state machine so the requisite considerations such as preparing for the next command or preventing further interrupts must be handled if an operation cannot be completed 468 LUC FS Porting Manual E
62. a directory 106 Chapter Directories An application stores information in a file system by creating a file or appending new information to an existing file At a later time this information may be retrieved by reading the file However if a certain file must be found or all files may be listed the application can iterate through the entries in a directory using the directory access or simply directory functions The available directory functions are listed in Table 6 1 A separate set of directory operations or entry functions manage the files and directories available on the system Using these functions the application can create delete and rename directories and get and set a directory s attributes and date time More information about the entry functions can be found in section 7 2 Entry Access Functions on page 103 The entry functions and the directory Open function accept one or more full directory paths For information about using file and path names see section 4 3 uC FS File and Directory Names and Paths on page 62 The functions listed in Table 8 1 are core functions in the directory access module FSDir_ 44 functions These are matched by API level functions that correspond to standard C or POSIX functions More information about the API level functions can be found in Chapter 6 POSIX API on page 83 The core and API functions provide basically the same functionality the benefits of the
63. a software flaw LC 11 2 Check if an error occurred The error status register is decoded to produce the actual error condition That is not necessary strictly but error counters that accumulate within the generic driver based upon returned error values may be useful while debugging a port LC 11 Return no error The data has been transferred already from the memory buffer using DMA 486 LUC FS Porting Manual C 12 7 FSDev_SD_ Card _BSP_GetBlkCntMax CPU_INT32U FSDev_SD Card BSP_GetBlkCntMax FS Org unit_nbr CPU_INT32U blk size File Called from Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_Refresh N A Get maximum number of blocks that can be transferred with a multiple read or multiple write command ARGUMENTS unit_nbr Unit number of SD MMC card blk_size Block size in octets RETURNED VALUE Maximum number of blocks NOTES WARNINGS 1 The DMA region from which data is read or written may be a limited size The count returned by this function should be the maximum number of blocks of size blk_size that can fit into this region 2 If the controller is not capable of multiple block reads or writes 1 should be returned 3 If the controller has no limit on the number of blocks in a multiple block read or write DEF_INT_32U_MAX VAL should be returned 4 This function SHOULD always return the same value If hardware constraints change at run time the device MUST be closed and re
64. always be named fs_os uC FS has been tested with pC OS II wC OS II and without an RTOS The RTOS layer files are found in the following directories Micrium Software uC Clk 0S None fs_os Micrium Software uC Clk 0S Template fs_os Micrium Software uC Clk 0S uCOS II fs_os Micrium Software uC Clk 0S uCOS III fs_os 3 13 SUMMARY Below is a summary of all the directories and files involved in a uC FS based project The lt Cfg on the far right indicates that these files are typically copied into the application Oe project directory and edited based on project requirements Micrium Software EvalBoards lt manufacturer gt lt board name gt lt compiler gt lt project name gt app c app h other BSP bsp c bsp h 52 other CPU lt manufacturer gt lt architecture gt L uC FS APP Template fs_app c lt Cfg fs_app h lt Cfg CFG Template fs_cfg h lt Cfg Dev VIDE fs_dev_ide c fs_dev_ide h BSP Template fs_dev_ide_bsp c lt Cfg MSC fs_dev_msc c fs_dev_msc h NAND fs_dev_nand c fs_dev_nand h PHY fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h Template fs_dev_nand_template c fs_dev_nand_template h BSP lt template gt fs_dev_nand_bsp c lt Cfg NOR Directories and Files 53 Directories and Files
65. be freed made available for future allocation to avert a crippling memory leak The internal file system function FS WorkingDirObjFree releases the string to an object pool In the port for pC OS III that function is called by FS_OS WorkingDirFree which must be called by the assigned task delete hook FS_OS_Dly_ms Device drivers and example device driver ports delay task execution FS_OS Dly ms Common functions allow BSP developers to optimize implementation easily A millisecond delay may be accomplished with an OS kernel service if available The trivial implementation of a delay particularly a sub millisecond delay is a while loop better performance may be achieved with hardware timers with semaphores for wait and asynchronous notification The best solution will vary from one platform to another since the additional context switches may prove burdensome No matter which strategy is selected the function MUST delay for at least the specified time amount otherwise sporadic errors can occur Ideally the actual time delay will equal the specified time amount to avoid wasting processor cycles void FS BSP Dly ms CPU_INT16U ms Insert code to delay for specified number of millieconds Listing C 3 FS_OS_Dly_ms 390 LUC FS Porting Manual FS_OS_Sem The four generic OS semaphore functions provide a complete abstraction of a basic OS kernel service FS_OS SemCreate creates a semaphore which may lat
66. boards supported by Micrium lt manufacturer gt Is the name of the manufacturer of the evaluation board The lt and gt are not part of the actual name lt board name gt This is the name of the evaluation board A board from Micrium will typically be called uC Eval xxxx where xxxx will represent the CPU or MCU used on the evaluation board The lt and gt are not part of the actual name lt compiler gt This is the name of the compiler or compiler manufacturer used to build the code for the evaluation board The lt and gt are not part of the actual name lt project name gt This is the name of the project that will be demonstrated For example a simple uC FS project might have a project name of FS Ex1 The Ex1 represents a project containing only pC FS A project name of FS Probe Ex1 would represent a project containing uC FS as well as uC Probe The lt and gt are not part of the actual name VW These are the source files for the project product You are certainly welcomed to call the main files APP for your own projects but you don t have to This directory also contains the configuration file FS_CFG H and other files as needed by the project 32 Directories and Files 3 2 CPU As shown below is the directory where we place semiconductor manufacturer peripheral interface source files Of course you can use whatever directory structure
67. cardmode initialization and state transitions 184 Command Response SD MMC Drivers GO_IDLE_STATE Fig 15 6 1 No response SEND_IF_COND Fig 15 6 2 Response only for SD V2 cards Voltage range Reserved 0x00000 0x1 20 bits 4 bits Check pattern 0xA5 8 bits SD_SEND_OP_COND Card power May not be 1 on initial up status reading s Card Capacity 1 High capacity Status Reserved VDD Voltage Window 0 Standard capacity Fig 15 6 3 0x00 OxFF8000 6 bits 24 bits OCR Example 127 R 0x03534453 0x44303247 63 PSN 0x80021A7C MDT ceee H 0x83008B3A ALL SEND_CID Ja E MID Manufacturer ID 0x03 Fig 15 6 5 OID OEM Application ID 0x5344 PNM Product name 0x5344303247 SD02G PRV Product revision 0x80 8 0 PSN Product serialnumber 0x021A7C83 MDT Manufacturing date 0x008 Examples 0x400E0032 gt 0x5B590000 S 0x1E5C7F80 SEND_CSD S 0x0A4040DE Fig 15 6 6 5 2 2 127 TRAN_SPEED 0x00260032 5 i s 0x5F5A83C9 bd 2 Ox3EFBCFFF a 0x928040CA Figure 17 5 Command responses SD card 185 Command Response SD MMC Drivers GO_IDLE_STATE Fig 15 6 1 No response SEND_OP_COND Card power May not be 1 on initial up status reading s Reserved VDD Voltage Window Fig 15 6
68. chapter explains this API Chapter 9 FAT File System This chapter details the low level architecture of the FAT file system Though the API of uC FS is file system agnostic the file system type does affect performance reliability and security as explained here as well Chapter 10 Device Drivers All hardware accesses are eventually performed by a device driver This chapter describes the drivers available with wC FS and broadly profiles supported media types in terms of cost performance and complexity Chapter 11 IDE Devices The IDE driver supports compact flash CF cards and ATA IDE hard drives Chapter 12 Logical Devices Driver This feature is not available yet Chapter 13 Mass Storage Class MSC Driver The now common USB drive implements the Mass Storage Class MSC protocol and a CPU with a USB host interface can access these devices with appropriate software The MSC driver discussed in this chapter with pC USB Host is just such appropriate software Chapter 14 NAND Flash NAND flash is the first category of flash media Write speeds are fast Compared to NOR flash at the expense of slower read speeds and complexities such as bit errors and page program limitations This chapter describes the functions of these devices and the architecture of the supporting driver Chapter 15 NOR Flash NOR flash is the second category of flash media They suffer slow write speeds balanced with blazingly fast read speeds Important
69. code if err FS_ERR_NONE APP_TRACE_INFO Error could not assign Volume cache return pfile FSFile Open sdcard 0 file txt FS_FILE ACCESS MODE WR FS_FILE ACCESS MODE CACHED amp err if pFile FS FILE 0 return DO THE WRITE OPERATIONS TO THE FILE E FSFile Close pFile amp err FSVol_CacheFlush sdcard 0 amp err lt Flush volume cache Listing 5 1 Cache L5 1 1 Percent of cache buffer dedicated to management sectors L5 1 2 Percent of cache buffer dedicated to directory sectors The application using uC FS volume cache should vary the third and fourth parameters passed to FSVol_CacheAssign and select the values that give the best performance For an efficient cache usage it is better to do not allocate space in the cache for sectors of type file when the write size is greater than sector size When the cache is used in write back mode all cache dirty sectors will be updated on the media storage only when the cache is flushed 81 Devices and Volumes 5 7 2 OTHER CACHING amp BUFFERING MECHANISMS Volume cache is just one of several important caching mechanisms which should be balanced for optimal performance within the bounds of platform resources The second important software mechanism is the file buffer see section 7 1 3 Configuring a File Buffer on page 101 which makes file accesses more efficient by buffering data so a full sector s wor
70. dev void p src void p spare PG SEC NBR sec_nbr phy FS_ERR p err void FSDev_NAND PhyEraseBlk CPU_CHAR CPU_INT32U FS ERR name_dev blk_nbr_phy p err 340 LC FS API Reference Manual A 9 1 FSDev_NAND_LowFmt void FSDev NAND LowFmt CPU_CHAR name_ dev FS_ERR p err File Called from Code enabled by fs_dev_nand c Application N A Low level format a NAND device ARGUMENTS name_dev Device name see Note p_err Pointer to variable that will receive the return error code from this function FS_ERR_ NONE Device low level formatted successfully FS_ERR NAME NULL Argument name deyv passed a NULL pointer FS ERR DEV_INVALID Argument name_dev specifies an invalid device PG ERR DEV MO ODEN Device is not open PG ERR DEV MO PRESENT Device is not present FS_ ERR DEV_INVALID LOW FMT Device needs to be low level formatted FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NAND device e g nand 0 Low level formating associates physical areas sectors of the device with logical sector numbers A NAND medium MUST be low level formatted with this driver prior to access by the high level file system a requirement which the device module enforces 341 LC FS API Reference Manual A 9 2 FSDev_NAND_LowMount void FSDev_NAND LowMount CPU_CHAR name dev FS_ERR p err File Called fro
71. device MUST be a NAND device e g nand 0 345 A 9 5 FSDev_NAND PhyWrSec void FSDev_NAND PhyWrSec CPU_CHAR LC FS API Reference Manual name_dev void p src void p spare PG SEC MR sec_nbr phy FS_ERR p err File Called from Code enabled by fs_dev_nand c Application Write to a NAND device from a buffer ARGUMENTS name_dev Device name see Note p sre Pointer to source buffer N A p_spare Pointer to buffer that contains the spare data sec_nbr_phy Sector to write p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Octets written successfully FS ERR NAME NULL FS ERR NULL PTR FS ERR DEV INVALID FS ERR DEV NOT OPEN FS ERR DEV NOT PRESENT FS ERR DEV IO FS ERR DEV TIMEOUT Argument name_dev passed a NULL pointer Argument p_ sre passed a NULL pointer Argument name_dev specifies an invalid device Device is not open Device is not present Device I O error Device timeout 346 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS The device MUST be a NAND device e g nand 0 Care should be taken if this function is used while a file system exists on the device or if the device is low level formatted The page modified is NOT verified as being outside any existing file system or low level format information During a program operation only 1 bits can be changed a 0 bit cannot be changed to
72. device driver names and device names as shown in Figure 2 4 The device name is between three and five characters longer than the device driver name since the unit number the integer between the colons of the device name must be between 0 and 255 a de _ sdcard 0 ER driver name Figure 4 2 Device and device driver name lengths Each of the maximum name length configurations specifies the maximum string length without the NULL character Consequently a buffer which holds one of these names must be one character longer than the define value 64 4 5 RESOURCE USAGE Miscellaneous uC FS resource usage of both ROM and RAM depends heavily on application usage How many and which interface functions are referenced determines the code and constant data space requirements The greater the quantity of file system objects buffers files directories devices and volumes the more RAM needed Table 2 1 give the ROM usage for the file system core plus additional components that can be included optionally collected on IAR EWARM v5 4 The core ROM size includes ail file system components and functions except those itemized in the table this is significantly larger than most installations because most applications use a fraction of the API Component ROM Thumb Mode ROM ARM Mode High Size Opt High Speed Opt High Size Opt High Speed Opt Core 44 1 kB 52 5 kB 66 5 kB 79 4 kB OS port uC OS III 0 2 k
73. devices Of course your hardware would most likely contain other devices such as UARTs Universal Asynchronous Receiver Transmitters ADCs Analog to Digital Converters and Ethernet controller s Moreover your application may include other middleware components like an OS kernel networking TCP IP stack or USB stack that may integrate with pC FS A Windows based development platform is assumed The directories and files make references to typical Windows type directory structures However since uC FS is available in source form then it can certainly be used on Unix Linux or other development platforms This of course assumes that you are a valid pC FS licensee in order to obtain the source code The names of the files are shown in upper case to make them stand out The file names however are actually lower case 28 FS_CFG H 13 HC FS Configuration yC FS Platform Independent FS C H FS_API C H FS_BUF C H FS_CACHE C H FS_CFG_FS H FS_CTR H FS_DEV C H FS_DIR C H FS_ENTRY C H FS_ERR C H FS_FILE C H FS_PARTITION C H FS_POOL C H FS_SYS C H FS_TYPE H FS_UNICODE C H FS_UTIL C H FS_VOL C H uC FS Filesystem Driver FS_FAT C H FS_FAT_DIR C H FS_FAT_ENTRY C H FS_FAT_FAT12 C H FS_FAT_FAT16 C H FS_FAT_FAT32 C H FS_FAT_FILE C H FS_FAT_JOURNAL C H FS_FAT_LFN C H FS_FAT_SFN C H FS_FAT_TYPE H yC FS Device Drivers FS_DEV_ C H Platform Specific FS_DEV_ _BSP C 4 pC CPU CPU
74. driver begins to access the SPI The application should NOT use the same bus to access another device until the matching call to Unlock has been made The clock frequency set by the SetClkFreq function is a parameter of the device not the bus If multiple devices are located on the same bus those parameters must be saved in memory when set and restored by Lock The same should be done for initialization parameters such as transfer unit size and shift direction that vary from device to device 502 LUC FS Porting Manual C 14 4 Rail void FSDev_BSP SPI Rd FS QTY unit _nbr void p dest CPU_SIZE T cnt File Called from Code enabled by fs_dev_ lt dev_name gt _bsp c Device driver N A Read from SPI bus ARGUMENTS unit_nbr Unit number of device p dest Pointer to destination buffer cnt Number of octets to read RETURNED VALUE None NOTES WARNINGS None 503 LUC FS Porting Manual C 14 5 Wr void FSDev_BSP SPI Wr FS QTY unit _nbr void p src CPU_SIZE T cnt File Called from Code enabled by fs_dev_ lt dev_name gt _bsp c Device driver N A Write to SPI bus ARGUMENTS unit_nbr Unit number of device p sre Pointer to source buffer cnt Number of octets to write RETURNED VALUE None NOTES WARNINGS None 504 C 14 6 ChipSelEn ChipSelDis void FSDev_ BSP _SPI_ChipSelEn FS Om unit_nbr void FSDev_BSP_ SPI _ChipSelDis FS QTY unit_nbr File Called from L
75. enabled by fs_api c Application FS_CFG API EN and FS_CFG_WORKING_DIR_EN Set the working directory for the current task ARGUMENTS path dir String buffer that specifies EITHER a the absolute working directory path to set b relative path that will be applied to the current working directory RETURNED VALUE 0 if no error occurs 1 otherwise NOTES WARNINGS None 211 LC FS API Reference Manual A 2 3 fs_clearerr void fs _clearerr FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG_API_EN Clear EOF and error indicators on a file ARGUMENTS p file Pointer to a file RETURNED VALUE None NOTES WARNINGS None 212 LC FS API Reference Manual A 2 4 fs_closedir int fs_closedir FS DIR p dir File Called from Code enabled by fs_api c Application FS_CFG_API_EN and FS_CFG DIR EN Close and free a directory ARGUMENTS p dir Pointer to a directory RETURNED VALUE 0 if the directory is successfully closed 1 if any error was encountered NOTES WARNINGS After a directory is closed the application MUST desist from accessing its directory pointer This could cause file system corruption since this handle may be re used for a different directory 213 LC FS API Reference Manual A 2 5 fs_ctime_r char fs ctime_r const fs time t p ts char str_time File Called from Code enabled by fs_api c App
76. entries for file named abcdefghijklm op 9 1 4 FAT SYSTEM DRIVER ARCHITECTURE As shown in Figure 9 2 the FAT system driver intermediates between functions that access files and directories e g fs_fopenQ and volume read write functions Internally the FAT system driver is divided into three subsystems as shown in Figure 9 4 The first consists of the core functions directly called by file directory entry and volume modules Next are the functions that understand the layout of the File Allocation Table and can allocate and free clusters The final subsystem can create SFN and LFN directory entries and search a directory for a specific entry 114 File Systems FAT Files Directories Entries Ss_file Ss_dir Ss_entry fans Ree FAT Directory Entries System NI i Ss_fat_sfn Driver FAT Access Ss_fat_fat12 Ss_fat_fatl6 Ss_fat_fat32 Figure 9 5 FAT system driver architecture 9 2 OPERATIONS The application rarely needs to know about the underlying file system the FAT system driver within uC FS handles file and volume accesses in a transparent manner A few specific cases the application may benefit from increased awareness of FAT operation 9 2 1 FORMATTING A volume once it is open may need to be formatted before files or directories can be created The default format is selected by passing a NULL pointer as the second parameter of FSVol_Fmt Alternatively the exact pro
77. err File Called from Code enabled by NAND physical layer driver FSDev_NAND_PhyRdSecHandler N A Read from a NAND device and store data in buffer ARGUMENTS p_phy data Pointer to NAND phy data p dest Pointer to destination buffer p_dest_spare Pointer to destination spare buffer sec_nbr phy Physical sector to read from the page p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Octets read successfully FS_ERR_DEV_INVALID OP Device invalid operation FS ERR DEV INVALID ECC Invalid ECC FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout error RETURNED VALUE None 432 LUC FS Porting Manual NOTES WARNINGS None 433 LUC FS Porting Manual C 6 4 RdSpare void RdSpare FS_DEV_NAND PHY DATA p phy data void p dest FS_SEC_NBR sec_nbr_ phy CPU_INTO8U offset CPU_INTO8U bytes _nbr FS_ERR p err File Called from Code enabled by NAND physical layer driver FSDev_NAND_PhyRdSpareHandler N A Read data from NAND page spare area and store data in buffer ARGUMENTS p phy data Pointer to NAND phy data p_dest Pointer to destination buffer sec_nbr_ phy Physical sector to read from the page offset Offset in the spare area bytes nbr Number of bytes to read p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Octets read successfully FS_ERR_DEV_INVALI
78. file is opened af read from file do cnt fs_fread amp buf 0 1 sizeof buf p file if cnt gt 0 APP TRACE INFO Read d bytes r n cnt while cnt gt sizeof buf eof fs feof p file Chk for EOF St if eof 0 See Note 1 Si App TRACE INFO Reached EOF r n else err fs _ferror p file Chk for error af if err 0 See Note 2 APP TRACE INFO Read error r n fs_fclose p file Close file af else APP_TRACE_INFO Could not open file txt r n Listing 6 1 Example file read L6 1 1 To determine whether a file read terminates because of reaching the EOF or a device error removal the EOF condition should be checked using fs_feof L6 1 2 In most situations either the EOF or the error indicator will be set on the file if the return value of fs_fread is smaller than the buffer size Consequently this check is unnecessary 89 6 3 2 GETTING OR SETTING THE FILE POSITION POSIX API Another common operation is getting or setting the file position The fs_fgetpos and fs_fsetpos allow the application to store a file location continue reading or writing the file and then go back to that place at a later time An example of using file position get and set is given in Listing 6 2 void App Fnct void FS_FILE p file fs_fpos_t pos int err p file fs_fopen file txt ri
79. file system FSDev_Wr Write sector on device Table 5 1 Device API functions 5 2 USING DEVICES A device is opened with FSDev_Open FSDev_Open CPU_CHAR ide 0 lt a device name void SE lt b pointer to configuration FS_ERR amp err lt c return error The parameters are the device name a and a pointer to a device driver specific configuration structure b If a device driver requires no configuration structure as the IDE CF driver does not the configuration structure b should be passed a NULL pointer For other devices like RAM disks this must point to a valid structure 69 Devices and Volumes Device Object Pool Device closed All references released Device not present Device could not be initialized Device removed or unresponsive Device low level formatted Figure 5 2 Device state transition Prior to FSDev_Open being called a software is ignorant of the presence state or characteristics of the particular device After all references to the device are released b this ignorance again prevails and any buffers or structures are freed for later use The return error code from this functions provides important information about the device state m If the return error code is FS_ERR_NONE then the device is present responsive and low level formatted basically it is ready to use m If the return error code is FS_ERR_DEV_INVALID
80. file system software which performs such actions must meet the general expectations of an embedded environment a limited code footprint for instance which still delivering good performance 1 1 WHAT IS A FILE SYSTEM A file system is a collection of files and directories since directories are containers of files a hierarchical organization results A PC operating system such as Windows or Linux presents its file systems through a visual interface e g Windows Explorer with a tree like structure of entries that can be moved renamed or deleted with menus or actions like dragging and dropping Alternatively a headless system like DOS or any other command line integrates utilities to accomplish the same operations Above we stated that a system presents its file systems file systems plural because each drive is a separate file system a separate collection of files Each of these is anchored by some unique drive letter Windows or mount point Linux within the larger context of a virtual file system wherein every entry has a unique identifier Within the everything is a file mentality of Linux this is taken further but that is beyond this discussion Being separate each file system may have a different format one may be FAT the next NTFS and will be located on different physical devices or on separate partitions of the same device If files are to be read from a volume file system softwar
81. former are enhanced capabilities a consistent interface and meaningful return error codes 107 Directories 8 1 DIRECTORY ACCESS FUNCTIONS The directory access functions provide an API for iterating through the entries within a directory The FSDir Open function initiates this procedure and each subsequent call to FSDir_ Rd until all entries have been examined returns a FS_DIRENT which holds information about a particular entry The FSDir_Close function releases any file system structures and locks Function Description FSDir_Open Open a directory FSDir_Close Close a directory FSDir_Rd Read a directory entry FSDir_IsOpen Determine whether a directory is open or not Table 8 1 Directory API Functions These functions are almost exact equivalents to POSIX API functions the primary difference is the advantage of valuable return error codes to the application Directory Module Function FS_DIR FSDir Open CPU_CHAR FS_ERR void FSDir_Close FS_DIR void FSDir Rd FS_ERR FS_DIR FS_DIR_ENTRY FS_ERR p name full p err p dir p err p dir p dir entry p_err POSIX API Equivalent FS_DIR fs_opendir const char dirname int fs_closedir FS_DIR dirp int fs_readdir_r FS_DIR dirp struct fs_dirent entry struct fs_dirent result For more information about and an example of using directories see section 6 4 Directory
82. fs mktime struct fs tm p time File Called from Code enabled by fs_api c Application FS_CFG API_EN Convert date time to timestamp ARGUMENTS p time Pointer to date time to convert RETURNED VALUE Time value if NO errors fs_time t 1 otherwise NOTES WARNINGS None 234 LC FS API Reference Manual A 2 25 fs_opendir FS DIR fs_opendir const char name full File Called from Code enabled by fs_api c Application FS_CFG AGT EN and FS_CFG DIR_EN Open a directory ARGUMENTS name full Name of the directory See section 4 3 uC FS File and Directory Names and Paths on page 62 for information about directory names RETURNED VALUE Pointer to a directory if NO errors Pointer to NULL otherwise NOTES WARNINGS None 235 LC FS API Reference Manual A 2 26 fs_readdir_r int fs _readdir FS DIR p dir struct fs dirent p dir entry struct fs dirent pp result File Called from Code enabled by fs_api c Application FS_CFG API_EN and FS_CFG DIR_EN Read a directory entry from a directory ARGUMENTS p dir Pointer to a directory p_dir entry Pointer to variable that will receive directory entry information pp result Pointer to variable that will receive a p dir entry if NO error occurs AND directory does not encounter EOF b pointer to NULL if an error occurs OR directory encounters EOF RETURNED VALUE 1 if an error occurs 0 otherwise
83. fs_dev_nor_bsp c This is a template BSP for serial SPI NOR devices See section C 11 NOR Flash SPI BSP on page 466 for more information BSP Template SPI GPIO fs_dev_nor_bsp c This is a template BSP for serial SPI NOR devices using GPIO bit banging See section C 11 NOR Flash SPI BSP on page 466 for more information 152 PHY NOR Flash Driver This directory contains physical level drivers for specific NOR types fs_dev_nor_amd_1x08 fs_dev_nor_amd_ 1x16 fs_dev_nor_intel fs_dev_nor_sst39 fs_dev_nor_stm25 fs_dev_nor_sst25 CFl compatible parallel NOR implementing AMD command set 1 chip 8 bit data bus CFl compatible parallel NOR implementing AMD command set 1 chip 16 bit data bus CFI compatible parallel NOR implementing Intel command set 1 chip 16 bit data bus SST SST39 Multi Purpose Flash ST STM25 serial flash SST SST25 serial flash Micrium Software uC FS Examples BSP Dev NOR Each subdirectory contains an example BSP for a particular platform These are named according to the following rubric lt Chip Manufacturer gt lt Board or CPU gt fs_dev_nor_bsp c 153 NOR Flash Driver 15 2 DRIVER amp DEVICE CHARACTERISTICS NOR devices no matter what attachment interface serial or parallel share certain characteristics The medium is always organized into units called blocks which are erased at the same time when erased all bits are 1 Only an erase oper
84. full FS_FLAGS attrib FS_ERR p err void FSEntry Copy CPU_CHAR name_full_src CPU_CHAR name full dest CPU_BOOLEAN excl FS_ERR p err void FSEntry_ Create CPU_CHAR name full FS_FLAGS entry type CPU_BOOLEAN excl FS_ERR p err void FSEntry Del CPU_CHAR name full FS_FLAGS entry type FS_ERR p err void FSEntry Query CPU_CHAR name_full FS_ENTRY INFO p info FS_ERR p err void FSEntry_ Rename CPU_CHAR name full src CPU_CHAR name full dest CPU_BOOLEAN excl FS_ERR p err void FSEntry TimeSet CPU_CHAR name full FS DATE TIME p time CPU_INTO8U flag FS_ERR p err 273 LC FS API Reference Manual A 5 1 FSEntry_AttribSet void FSEntry AttribSet CPU_CHAR name full FS FLAGS attrib FS_ERR p err File Called from Code enabled by fs_entry c Application not FS_CFG_RD_ONLY_EN Set a file or directory s attributes ARGUMENTS name full Name of the entry See section 4 3 uC FS File and Directory Names and Paths on page 62 attrib Entry attributes to set see Note 2 p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Entry attributes set successfully FS_ERR_NULL PTR Argument name_full passed a NULL pointer FS_ERR_NAME INVALID Entry name specified invalid OR volume could not be found FS_ERR_NAME PATH TOO LONG Entry name specified too long FS_ERR_VOL MOT OPEN Volume was not
85. listed and described in Table C 5 The first argument of each of these is a pointer to a FS_DEV_NAND_ PHY DATA structure which holds physical device information Specific members will be described in subsequent sections as necessary The NAND driver populates an internal instance of this type based upon configuration information Before the file system suite has been initialized the application may do the same if raw device accesses are a necessary part of its start up procedure Function Description Open Open initialize a NAND device and get NAND device information Close Close uninitialize a NAND device RdPage Read a page from a NAND device and store data in buffer RdSpare Read a spare area from a NAND device and store data in buffer WrPage Write to a page of a NAND device from data in buffer WrSpare Write to a spare area of a NAND device from data in buffer WrCopyBack Copy data from one block to another EraseB1lk Erase block of NAND device IO Ctrl Perform NAND device I O control operation 427 LUC FS Porting Manual Table C 3 NAND flash physical layer driver functions 428 LUC FS Porting Manual C 6 1 Open void Open FS _DEV_NAND PHY DATA p phy data FS_ERR p err File Called from Code enabled by NAND physical layer driver FSDev_NAND_ Open N A Open initialize a NAND device instance and get NAND device information ARGUMENTS p ph
86. manufacturer gt lt cpu_name gt Check all of these directories for ports for a CPU if porting any SPI device the CPU may be been used with a different type of device but the port should support another with none or few modifications Each port must implement the functions to be placed into a FS_DEV_SPI_APT structure 496 LUC FS Porting Manual const FS DEV SPI_API FSDev_ BSP_SPI FSDev_BSP_SPI_ Open FSDev_BSP_SPI Close FSDev_BSP_SPI_Lock FSDev_BSP_SPI_Unlock FSDev_BSP_SPI_Rd FSDev_BSP_SPI_ Wr FSDev_BSP_SPI_ChipSelEn FSDev_BSP_SPI_ChipSelDis FSDev_BSP_SPI_SetClkFreq The functions which must be implemented are listed and described in Table C 9 SPI is no more than a physical interconnect The protocol of command response interchange the master follows to control a slave is specified on a per slave basis Control of the chip select SSEL is separated from the reading and writing of data to the slave because multiple bus transactions e g a read then a write then another read are often performed without breaking slave selection Indeed some slaves require bus transactions or empty clocks AFTER the select has been disabled Function Description Open Open initialize hardware for SPI Close Close uninitialize hardware for SPI Lock Acquire SPI bus lock Unlock Release SPI bus lock Rd Read from SPI bus Wr Write to SPI bus ChipSelEn Enable device
87. module based on application requirements fs_cfg h specifies which features of uC FS you want in your application If uC FS is provided in linkable object code format then this file will be provided to show you what features are available in the object file See Appendix B uC FS Configuration Manual 43 Directories and Files Source This directory contains the platform independent source code for uC FS All the files in this directory should be included in your build assuming you have the source code Features that you don t want will be compiled out based on the value of define constants in fs_cfg h fs c h contain core functionality for pC FS including FS_Init called to initialize uC FS and FS WorkingDirSet FS WorkingDirGet used to get and set the working directory fs h is the ONLY core header file that should be included by the application fs_api c h contains the code for the POSIX compatible API See Chapter x API for details about the POSIX compatible API fs_buf c h contains the code for the buffer management used internally by pC FS fs_dev c h contains code for device management See Chapter x Devices for details about devices fs_dir c h contains code for directory access See Chapter x Directories for details about directory access fs_entry c h contains code for entry access See Chapter x Entries for details about entry access fs_file c h contains code for file access See Chapter x Fi
88. not present FS_ ERR DEV_INVALID LOW FMT Device needs to be low level formatted FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NOR device e g nor 0 Compacting groups sectors containing high level data into as few blocks as possible If an image of a file system is to be formed for deployment to be burned into chips for production then it should be compacted after all files and directories are created 355 LC FS API Reference Manual A 10 5 FSDev_NOR_LowDefrag void FSDev NOR LowDefrag CPU_CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev_nor c Application N A Low level defragment a NOR device ARGUMENTS name_dev Device name see Note p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Device low level defragmented successfully FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_DEV_INVALID Argument name dev specifies an invalid device FS_ERR_DEV_NOT_OPEN Device is not open FS_ERR_DEV_NOT_PRESENT Device is not present FS ERR DEV _INVALID LOW FMT Device needs to be low level formatted FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NOR device e g nor 0 Defragmentation groups sectors containing high level data into
89. occurred Non zero value if EOF indicator is set NOTES WARNINGS 1 The return value from this function should ALWAYS be tested against 0 rtn fs_feof p file if rtn 0 EOF indicator is NOT set else EOF indicator is set 2 If the end of file indicator is set G e fs_feof returns DEF_YES fs_clearerr can be used to clear that indicator 216 LC FS API Reference Manual A 2 8 fs_ferror int fs _ferror FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG_API_EN Test error indicator on a file ARGUMENTS p file Pointer to a file RETURNED VALUE 0 if error indicator is NOT set or if an error occurred Non zero value if error indicator is set NOTES WARNINGS 1 The return value from this function should ALWAYS be tested against 0 rtn fs _ferror p file if rtn 0 Error indicator is NOT set else Error indicator is set 2 If the error indicator is set G e fs_ferror returns a non zero value fs_clearerr can be used to clear that indicator 217 LC FS API Reference Manual A 2 9 fs_fflush int fs fflush FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG_API_EN and FS_CF_FILE_BUF_EN Flush buffer contents to file ARGUMENTS p file Pointer to a file RETURNED VALUE 0 if flushing succeeds FS_EOF otherwise NOTES WARNINGS 1 Ifthe most recent operation is output write
90. od Dump file contents to the terminal output USAGES fs od file ARGUMENTS file Path of file to dump to terminal output OUTPUT File contents in hexadecimal form REQUIRED CONFIGURATION Available only if FS_SHELL_CFG_OD_EN is DEF_ENABLED NOTES WARNINGS None GZ COM4 PuTTY DER gt A 00000010 2 00000020 FE28726F d OO6FOL 00000030 OO6F 4 570020 0072006F 00000040 00200064 I d 6 004D002D 00000050 00 61 61 OO6FO064 00000060 OOOOO0EO 41 000000F0 610069 00000100 690041 00000110 200074 6F 64 7200 2pD002000 Figure F 7 fs_od Output 552 F 3 12 fs_ pwd Write to terminal output pathname of current working directory USAGES fs_pwd ARGUMENTS None OUTPUT Pathname of current working directory REQUIRED CONFIGURATION Available only if FS_SHELL CFG PWD EN is DEF_ENABLED NOTES WARNINGS None Shell Commands 553 Shell Commands F 3 13 fs rm Remove a file USAGES fs rm file ARGUMENTS file File path OUTPUT None REQUIRED CONFIGURATION Available only if FS_SHELL CFG RM EN is DEF ENABLED and FS CFG RD ONLY EN is DEF DISABLED NOTES WARNINGS None 554 Shell Commands F 3 14 fs rmdir Remove a directory USAGES fs rmdir dir ARGUMENTS dir Directory path OUTPUT None REQUIRED CONFIGURATION Available only if FS SHELL CFG RMDIR EN is DEF ENABLED and FS CFG RD ONLY EN is DEF_DISABLED NOTES WARNINGS None 5
91. of Hamming code edc_crce_a asm contains the assembly language functions to optimize the calculation speed of CRC cyclic redundancy checks Source This is the directory that contains all the CPU independent source code files of wC CRC 41 Directories and Files 3 8 uC FS PLATFORM INDEPENDENT SOURCE CODE The files in these directories are available to uC FS licensees see Appendix H Licensing Policy Micrium Software APP Template fs_app c fs_app h Cf g Template fs_cfg h OS Template fs_os c fs_os h Source fs_c fs h fs_api c fs_api h fs_buf c fs_buf h fs_cache c fs_cache h fs_cfg_fs h fs_ctr h fs_def h fs_dev c fs_dev h fs_dir c fs dir h fs_entry c fs_entry h fs_err c fs_err h fs_file c fs_file h 42 Directories and Files fs_partition c fs_partition h fs_pool c fs_pool h fs_sys c fs_sys h fs_type h fs_unicode c fs_unicode h fs_util c fs_util h fs_vol c fs_vol h Micrium This is where we place all software components and projects provided by Micrium Software This sub directory contains all the software components and projects uC FS This is the main pC FS directory APP Template This directory contains a template of the code for initializing the file system Cfg Template This directory contains a configuration template file Cib_cfg h that is required to be copied to the application directory to configure the wC FS
92. on that device analogous to mounting This operation will succeed if and only if the device responds and the file system control structures for FAT the Boot Parameter Block or BPB are located and validated In this manual as in the design of uC FS the terms device and volume have distinct non overlapping meanings We define a device as a single physical or logical entity which contains a continuous sequence of addressable sectors An SD MMC card is a physical device We define a volume as a collection of files and directories on a device These definitions were selected so that multiple volumes could be opened on a device as shown in Figure 5 1 without requiring ambiguous terminology ide 0 ide 1 partition2 Device layer partition partition1 ide ta ide 1b Volume layer Figure 5 1 Device and volume architecture 67 5 1 DEVICE OPERATIONS Devices and Volumes The ultimate purpose of a file system device is to hold data Consequently two major operations that can occur on a device are the reading and writing of individual sectors Five additional operations can be performed which affect not just individual sectors but the whole device E A device can be opened During the opening of a device it is initialized and its characteristics are determined sector size number of sectors vendor A device can be partitioned Partitioning ivides the final
93. opened for any changes to be effective 487 LUC FS Porting Manual C 12 8 FSDev_SD_ Card BSP_GetBusWidthMax CPU_INTO8U FSDev_SD Card BSP_GetBusWidthMax FS QTY unit_nbr File Called from Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_Refresh N A Get maximum bus width in bits ARGUMENTS unit_nbr Unit number of SD MMC card RETURNED VALUE Maximum bus width NOTES WARNINGS 1 Legal values are typically 1 4 and 8 2 This function SHOULD always return the same value If hardware constraints change at run time the device MUST be closed and re opened for any changes to be effective 488 LUC FS Porting Manual C 12 9 FSDev_SD Card BSP_SetBusWidth void FSDev_SD Card BSP _SetBusWidth PS Om unit_nbr CPU_INTO8U width Called from File Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_Refresh N A FSDev_SD Card _SetBusWidth Set bus width ARGUMENTS unit_nbr Unit number of SD MMC card width Bus width in bits RETURNED VALUE None NOTES WARNINGS None 489 LUC FS Porting Manual EXAMPLE The implementation of FSDev_SD_ Card _BSP_SetBusWidth in Listing C 12 is targeted for the same host controller as the other listings in this chapter for more information see FSDev_SD Card BSP CmdStart void FSDev_SD Card BSP SetBusWidth FS QTY unit_nbr CPU_INTO8U width if width lu REG DOS CONTROL amp BIT_HOST_ CONTROL DATA
94. p cmd void p dest FS_ERR p err File Called from Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_RdData N A Read data following a command ARGUMENTS unit_nbr Unit number of SD MMC card p_cmd Pointer to command that was started p dest Pointer to destination buffer p err Pointer to variable that will receive the return error code from this function FS_DEV_SD CARD ERR NONE No error FS_DEV_SD CARD ERR NO CARD No card present FS DEV GD CARD ERR UNKNOWN Unknown or other error FS _DEV_SD CARD ERR WAIT TIMEOUT Timeout in waiting for data PG DV _ SD CARD ERR DATA OVERRUN Data overrun FS DEV GD CARD ERR DATA TIMEOUT Timeout in receiving data FS DEV SD CARD ERR DATA CHKSUM Error in data checksum FS DEV SD CARD ERR DATA START BIT Data start bit error FS_DEV_SD CARD ERR DATA Other data error RETURNED VALUE None NOTES WARNINGS None 481 LUC FS Porting Manual EXAMPLE The implementation of FSDev_SD_Card_BSP_CmdDataRd in Listing C 10 is targeted for the same host controller as the other listings in this chapter for more information see FSDev_SD Card BSP _CmdStart void FSDev_SD_Card BSP_CmdDataRd FS_QTY unit_nbr FS_DEV_SD CARD CMD p cmd void p dest FS_ERR p err CPU_INT16U interrupt_status CPU_INT16U error_status CPU_INT16U timeout timeout 0u Wait until data xfer compl 1 interrupt status REG_INTERRUPT_STATUS while DEF_BIT_IS CLR interrupt_s
95. protocols Table 15 1 briefly compares these two technologies specific listings of supported devices are located in section 15 5 Physical Layer Drivers on page 166 Device Category Typical Packages Manufacturers Description Parallel NOR Flash TSOP32 TSOP48 AMD Spansion Intel Parallel data 8 or 16 bit and BGA48 TSOP56 Numonyx SST ST address bus 20 bits Most devices BGA56 Numonyx have CFI query information and use one of several standard command sets Serial NOR Flash SOIC 8N SOIC 8W Atmel SST ST SPI or multi bit SPl like interface SOIC 16 WSON Numonyx Command sets are generally similar USON Table 15 1 NOR Flash Devices 151 NOR Flash Driver 15 1 FILES AND DIRECTORIES The files inside the RAM disk driver directory are outlined in this section the generic file system files outlined in Chapter 3 Directories and Files on page 28 are also required Micrium Software uC FS Dev This directory contains device specific files Micrium Software uC FS Dev NOR This directory contains the NOR driver files fs_dev_nor These files are device driver for NOR flash devices This file requires a set of BSP functions be defined in a file named fs_dev_nor_bsp c to work with a certain hardware setup BSP Template fs_dev_nor_bsp c This is a template BSP for traditional parallel NOR devices See section C 10 NOR Flash BSP on page 459 for more information BSP Template SPI
96. ram 0 void 0 amp err 6 if err FS ERR NONE APP_TRACE DBG format failed r n return DEF FAIL break default Device error ef APP_TRACE_DBG opening volume failed w err d r n r n err return DEF_FAIL return DEF OK Listing 16 1 Opening a RAM disk volume L16 1 1 The sector size and number of sectors in the RAM disk must be defined The sector size should be 512 1024 2048 or 4096 the number of sectors will be determined by your application requirements This defines a 24 MB RAM disk 49152 512 B sectors On most CPUs it is beneficial to 32 bit align the RAM disk since this will speed up access L16 1 2 Register the RAM disk driver FSDev_RAM 116 13 The RAM disk parameters sector size size in sectors and pointer to the disk should be assigned to a FS_DEV_RAM CFG structure 172 L16 1 4 L16 165 L16 1 6 RAM Disk Driver FSDev_Open opens initializes a file system device The parameters are the device name 3a and a pointer to a device driver specific configuration structure 3b The device name a s composed of a device driver name Cram a single colon an ASCII formatted integer the unit number and another colon FSVol_Open opens mounts a volume The parameters are the volume name 5a the device name 5b and the partition that will be opened 5c There is no restriction on the volume name 5a however it is typical to give th
97. region For most flash these regions are contiguous and sequential the first at the beginning of the device the second just after Since this is not always true see section 15 5 3 161 NOR Flash Driver FSDev_NOR_SST39 on page 168 for an example the manufacturer s information should always be checked and for atypical devices the physical layer driver copied to the application directory and modified Command Set Identifier Description 0x0001 Intel 0x0002 AMD Spansion 0x0003 Intel 0x0102 SST 15 3 3 NOR BSP OVERVIEW Table 15 3 Common command sets A BSP is required so that a physical layer driver for a parallel flash will work on a particular system The functions shown in the table below must be implemented Pleaser refer to section C 10 NOR Flash BSP on page 459 for the details about implementing your own BSP Function Description FSDev_NOR_BS FSDev_NOR_BS P_Open P Close Open initialize bus for NOR Close uninitialize bus for NOR FSDev_NOR_BS P_Rd_XX Read from bus interface FSDev_NOR_BS P_RdWord XX Read word from bus interface FSDev_NOR_BS P WrWord XX Write word to bus interface FSDev_NOR_BS P WaitWhileBusy Wait while NOR is busy Table 15 4 NOR BSP functions The Open Close functions are called upon open close these calls are always matched 162 NOR Flash Driver The remaining f
98. specific configuration structure 1b The device name la is composed of a device driver name sd a single colon an ASCII formatted integer the unit number and another colon Since the SD MMC SPI driver requires no configuration the configuration structure 1b should be passed a NULL pointer Since SD MMC are often removable media it is possible for the device to not be present when FSDev_Open is called The device will still be added to the file system and a volume opened on the not yet present device When the volume is later accessed the file system will attempt to refresh the device information and detect a file system see section 5 2 Using Devices on page 69 for more information FSVol_Open opens mounts a volume The parameters are the volume name 2a the device name 2b and the partition that will be opened 2c There is no restriction on the volume name 2a however it is typical to give the volume the same name as the underlying device If the default partition is to be opened or if the device is not partition then the partition number 2c should be zero If the SD MMC initialization succeeds the file system will produce the trace output as shown in Figure 17 10 Gf a sufficiently high trace level is configured See section E 9 Trace Configuration on page 534 about configuring the trace level Figure 17 10 SD MMC detection trace output 192 SD MMC Drivers 17 3 1 SD MMC SPI COMMU
99. table below are equivalent to the standard UNIX commands of the same names though the functionality is typically simpler with few or no special options Command Description fs_cat Print file contents to the terminal output fs_cd Change the working directory fs_cp Copy a file fs_date Write the date and time to terminal output or set the system date and time fs df Report disk free space fs_ls List directory contents fs_mkdir Make a directory fs_mkfs Format a volume fs_mount Mount volume fs_mv Move files Ce od Dump file contents to terminal output fs_pwd Write to terminal output pathname of current working directory fs mm Remove a directory entry fa rmdir Remove a directory fs_touch Change file modification time fs_umount Unmount volume fs_we Determine the number of newlines words and bytes in a file Table F 1 Commands Information about each command can be obtained using the help h option COM4 PuTTY Print file cc to terminal output Figure F 3 Help option output 540 Shell Commands F 3 1 te cat Print file contents to the terminal output USAGES fs cat file ARGUMENTS file Path of file to print to terminal output OUTPUT File contents in the ASCII character set Non printable non space characters are transmitted as full stops periods character code 46 For a more convenient display of binary files use
100. to two devices known as master and slave or device 0 and device 1 may be located on a single conventional bus The active device the target for the next command is selected by the DEV bit in the DH register and generally only one device can be accessed at a time meaning that a read or write to one cannot interrupt a read or write to the other 129 IDE CF Driver SRST Software reset bit DEVCTRL DIEN Device interrupt enable DEV Device selected 0 Device 0 Master DH S 1 Device 1 Slave Command depen m ABRT Command has Obsolete ERR TA VY been aborted 3 43222 Er Reserved DRDY DRQ Device is ready to Device is ready to transfer a word of accept commands data STATUS and ALTSTATUS BSY Device is busy Error occurred during execution of previous command Figure 11 3 Register definitions Control Signals Abbreviation Name R W cs1 cso A02 A01 A00 DATA Data R W 0 1 0 0 0 ERR Error R 0 1 0 0 1 FR Features W 0 1 0 0 1 SC Sector Count W 0 1 0 1 0 SN Sector Number W 0 1 0 1 1 CYL Cylinder Low WwW 0 1 1 0 0 CYH Cylinder High WwW 0 1 1 0 1 DH Card Drive Head WwW 0 1 1 1 0 CMD Command W 0 1 1 1 1 STATUS Status R 0 1 1 1 1 ALTSTATUS Alternate Status R 1 0 1 1 0 DEVCTRL Device Control W 1 0 1 1 0 130 11 2 2 IDE BSP OVERVIEW IDE CF Driver A BSP is required so that the IDE drive
101. types and structures Appendix E uC FS API Configuration Manual uC FS is configured via defines in a single configuration file fs_cfg h The configuration manual specifies each define and the meaning of possible values Appendix F pC FS Shell Commands A familiar method of accessing a file system at least to engineers and computer scientists is the command line In an embedded system a UART is a port over which commands can be executed easily even for debug purposes A set of shell commands have been developed for pC FS that mirror the syntax of UNIX utilities as described in this chapter Appendix G Bibliographhy Appendix H Licensing Policy 21 Chapter UC FS Architecture uC FS was written from the ground up to be modular and easy to adapt to different CPUs Central Processing Units RTOSs Real Time Operating Systems file system media and compilers Figure 2 1 shows a simplified block diagram of the different uC FS modules and their relationships Notice that all of the uC FS files start with fs_ This convention allows you to quickly identify which files belong to pC FS Also note that all functions and global variables start with FS and all macros and defines start with FS 22 Your Application JS oh LIB lib_def h lib_ascii lib_mem lib_str E UC FS Architecture POSIX API Layer fs_api AA FS Layer Ou Ss_dev Ss_buf Js_d
102. 1 FS_CFG typedef struct fs cfg FS QTY DevCnt FS QTY VolCnt FS OI FileCnt FS QTY DirCnt FS QTY BufCnt FS_QTY DevDrvCnt FS_SEC_ SIZE MaxSecSize FS_CFG File Used for fs h First argument of FS_Init A pointer to a FS_CFG structure is the argument of FS_Init It configures the number of devices files and other objects in the file system suite MEMBERS DevCnt The maximum number of devices that can be open simultaneously MUST be greater than or equal to 1 Volcnt The maximum number of volumes that can be open simultaneously MUST be greater than or equal to 1 FileCnt The maximum number of files that can be open simultaneously MUST be greater than or equal to 1 DirCnt Maximum number of directories that can be open simultaneously If DirCnt is 0 the directory module functions will be blocked after successful initialization and the file system will operate as if compiled with directory support disabled If directory support is disabled DirCnt is ignored otherwise if directories will be used DirCnt should be greater than or equal to 1 508 LIC FS Types and Structures BufCnt Maximum number of buffers that can be used successfully The minimum necessary BufCnt can be calculated from the number of volumes BufCnt gt VolCnt 2 If FSEntry Copy or FSEntry Rename is used then up to one additional buffer for each volume may be necessary DevDrvCnt Maximum number of device drivers tha
103. 14 C 14 1 C 14 2 C 14 3 C 14 4 C 14 5 C 14 6 C 14 7 Appendix D D 1 D 2 D 3 D 4 D 5 D 6 D 7 D 8 D 9 D 10 Appendix E E 1 E 2 E 3 E 4 E 5 FSDev_SD_Card_BSP_CmdWaitEnd ccccceseeesseeeeeeeeeeeeeeeeeees 477 FSDev_SD_Card_BSP_CmdDataRd c cccesscceesseeeeesseeesseeeeeeeeees 481 FSDev_SD_Card_BSP_CmdDatawr ccccccceseeeseeeeeeeceeeeeeeeeeees 484 FSDev_SD_Card_BSP_GetBIkCntMax c cccceeseeeeeeesseeeeeeeenseees 487 FSDev_SD_Card_BSP_GetBusWidthMax ssssssseeeeeereeeeeeeees 488 FSDev_SD_Card_BSP_SetBuSWidth cc cccssseesseeeessseeeeeseeeeeeees 489 FSDev_SD_Card_BSP_SetClkFreq cccccceceseeeeeeeeeeeeeeeeeeenees 491 FSDev_SD_Card_BSP_SetTimeoutData sceseeseeeneeeeeeeeeeees 492 FSDev_SD_Card_BSP_SetTimeoutResp ccssessccesssseeeeeeeeeeees 493 SD MMC SPI mode BSP eneen iaaii Naa 493 SPINBSP ET 494 07013 p MEP en wee eee rane bc cad Seve havc en cade E T AE 499 GClOS6 carson SCENE Eege EEN ded vedanta 501 LOCK A Hpleektt ce cceissccesssactesewersesieensenscntsensncieaverearsavstnsenscenucersertezs 502 R ttgen EE E A E dE eed ae eS 503 WY cdi dies ed eae iis eels 504 ChipSelEn ChipSelDis c ccsssscceessssceeeesseeeeeeessseeeeeeeeseeeeeeeees 505 SetCIKFreq scisieiocs satectects tescctess te acctcess a ie 506 UC FS Types and Structures ccccccececeeeeeeeeseeeneee
104. 17 1 Opening a SD MMC device volume Register the SD MMC CardMode device driver FSDev_SD_ Card FSDev_Open opens initializes a file system device The parameters are the device name la and a pointer to a device driver specific configuration structure 1b The device name la is composed of a device driver name sdcard a single colon an ASCII formatted integer the unit number and another colon Since the SD MMC CardMode driver requires no configuration the configuration structure 1b should be passed a NULL pointer Since SD MMC are often removable media it is possible for the device to not be present when FSDev_Open is called The device will still be added to the file system and a volume opened on the not yet present device When the volume is later accessed the file system will attempt to refresh the device information and detect a file system see section 5 2 Using Devices on page 69 for more information FSVol_Open opens mounts a volume The parameters are the volume name 2a the device name 2b and the partition that will be opened 2c There is no restriction on the volume name 2a however it is typical to give the 179 SD MMC Drivers volume the same name as the underlying device If the default partition is to be opened or if the device is not partition then the partition number 2c should be zero If the SD MMC initialization succeeds the file system will produce the trace output as s
105. 2 The name MUST be constant each time this function is called the same name MUST be returned 3 The device driver NameGet function is called while the caller holds the FS lock 396 LUC FS Porting Manual C 4 2 Init static void FSDev_ Init void File Called from Code enabled by fs_dev_ H f c FS_DevDrvAdd N A The device driver Init function should initialize any structures tables or variables that are common to all devices or are used to manage devices accessed with the driver This function SHOULD NOT initialize any devices that will be done individually for each with the device driver s Open function ARGUMENTS None RETURNED VALUE None NOTES WARNINGS 1 The device driver Init function is called while the caller holds the FS lock 397 LUC FS Porting Manual C 4 3 Open static void FSDev_ HH Open FS DEV p dev void p dev Go PG ERR p err File Called from Code enabled by fs_dev_ HH c FSDev_Open N A The device driver Open function should initialize the hardware to access a device and attempt to initialize that device If this function is successful Oe it returns FS_ERR_NONE then the file system suite expects the device to be ready for read and write accesses ARGUMENTS D deu Pointer to device to open p_dev_cfg Pointer to device configuration p err Pointer to variable that will receive the return error code from this function FS_ERR_
106. 2 byte page SLC flash 8 bit bus FSDev_NAND_2048x08 fs_dev_nand_2048x08 Supports 2048 byte page SLC flash 8 bit bus FSDev_NAND_2048x16 fs_dev_nand_2048x16 Supports 2048 byte page SLC flash 16 bit bus FSDev_NAND_AT45 fs_dev_nand_at45 Supports various Atmel AT45 DataFlash serial devices Figure 14 3 Physical layer drivers 14 4 1 FSDEV_NAND_0512X08 FSDev_NAND_0512x08 supports small page 512 byte SLC NAND flash The ECC is a 1 bit correct 2 bit detect code this implementation uses a Hamming code The sector size cannot exceed the page size so the configured sector size MUST be 512 bytes 14 4 2 FSDEV_NAND_2048X08 FSDEV_NAND_2048X16 FSDev_NAND 2048x08 and FSDev_NAND_4096x08 support large page 2048 byte SLC NAND flash The ECC is a 1 bit correct 2 bit detect code this implementation uses a Hamming code The sector size cannot exceed the page size so the configured sector size MUST be less than 2048 bytes This physical layer driver advertises its page size as the selected sector size to take advantage of the partial page programming ability of SLC NAND If a sector size of 512 bytes is used the device MUST support at least four partial page programming operations between erases if a sector size of 1024 bytes is used the device MUST support at least two partial page programming operations between erases 149 14 4 3 FSDEV_NAND_AT45 NAND Flash Driver FSDev_NAND AT45 supports Atmel s AT45 s
107. 25 switch err case case case case case FS_ERR_NONE break FS_ERR_DEV FS_ERR_DEV_IO FS_ERR_DEV_TIMEOUT FS_ERR_DEV_NOT_PRESENT return DEF_FAIL default return DEF_FAIL PROS Ze FSVol_Open CPU_CHAR ide 0 a CPU_CHAR ide 0 b FS_PARTITION NBR 0 c FS_ERR amp err switch err case case case case case case FS_ERR_NONE break FS_ERR_DEV FS_ERR_DEV_IO FS_ERR_DEV_TIMEOUT FS_ERR_DEV_NOT_PRESENT FS_ERR_PARTITION_NOT_FOUND 4 return DEF_FAIL default return DEF_FAIL return DEF_OK IDE CF Driver Listing 11 1 Opening a IDE CF device volume 111 10 Register the IDE CF device driver L11 1 2 FSDev_Open opens initializes a file system device The parameters are the device name la and a pointer to a device driver specific configuration structure 1b The device name 1a is composed of a device driver name ide a single colon an ASCII formatted integer the unit number and another colon Since the IDE CF driver requires no configuration the configuration structure 1b should be passed a NULL pointer 126 L11 1Q3 L11 1 4 IDE CF Driver Since IDE CF are often removable media it is possible for the device to not be present when FSDev_Open is called The device will still be added to the file system and a volume opened on the not yet present device Wh
108. 4 1 0x00 OxFF8000 7 bits 24 bits OCR Example 127 mD OID Ox1EFFFF4D PNM 0x4D432020 63 PRV PSN 0x20105E60 MDT cee f 0x21BA5B7E ALL SEND CID a ae MID Manufacturer ID 0x1E Fig 15 6 5 OID OEM Application ID OxFFFF PNM Product name 0x4D4D43202020 MMC PRV Product revision 0x10 1 0 PSN Product serialnumber 0x5E6021BA MDT Manufacturing date 0x5B Examples 127 TAAC NSAC TRAN_SPEED 0x902F002A CH ccc C_SIZE Ox1F5A83C7 Fig 15 6 6 63 0x6DB7 9F FF 0x9680000E Figure 17 6 Command responses MMC card SD_BUS_WIDTHS Bit 0 1 bit Bit 2 4 bit Figure 17 7 SD SCR Register 186 511 00b 1 bit 01b 4 bit SIZE_OF_PROTECTED_AREA SD MMC Drivers DAT_BUS_WIDTH 0x0000 Regular rd wr card SD_CARD_TYPE SPEED_CLASS 0x00 Class 0 0x01 Class 2 0x02 Class 3 0x03 Class 4 Figure 17 8 SD Status 17 2 3 SD MMC CARDMODE BSP OVERVIEW A BSP is required so that the SD MMC cardmode driver will work on a particular system The functions shown in the table below must be implemented Pleaser refer to section C 12 SD MMC Cardmode BSP on page 467 for the details about implementing your own BSP Functio n Description FSDev_S D Card BSP _Open Open initialize SD MMC card interface FSDev_S D Card _BSP_Close Close uninitialize SD MMC card interface FSDev_S D Card _BSP_
109. 52 FSDev_NOR_LOWMOuN1t ccccceeceeeeeeseeeeeeeeeeeeeeeeseseeesseaeeeeeeeeeeeees 353 FSDev_NOR_LOWUnMOUNK cccceceeeeeeceeeeeneeeeeeeeneeeeeeensenaeeeeenenees 354 FSDev_NOR_LOWCOmMpa CU ccceeceeeeeseeeeeeeeeeeeeeeeeeeeeeesseaeeeeeeeeeeeees 355 FSDev_NOR_LOWDe rag ccceeeeceeeeeeeeeeeeeeeeeeeeseeeeseeeeeeeeeeeeeneeeneenees 356 FSDev_NOR_PhyR cccccceceeeseeeeeeeeseaeeeeeeeneaeeeeeesseaeeeeeeneaeseeenenees 357 FSDev NOR PhyWr ss ictaeat ceived anand heed ates 359 FSDev_NOR_PhyEraseBIK cesseeeceeeeseeeeeeeeeseeeeeeeeseeeeeeeeeseeeeeeeesenes 361 FSDev_NOR_PhyErasSeChip ccccesseeccceeeeseeeeeeeeseeeeeeenseeeeeeeenenees 363 SD MMC Driver Functions keen 364 FSDev_SD_xxx_QuerySD ccesseccceeeseeeeeeeeeseeeeeeeeeseaeeeeenseaaeeeeeseeaes 365 FSDev_ SD ox ROCID seirian eege deeg aeaa ara iiaeaa aaa 367 FSDev_SD_xxx_RACSD ee 369 FAT System Driver Functions sce seeeeeee cece eee eeeeeeeeesseaeeeeeeeeeenees 370 FS FATJournalOpen eseu EENEENEEN see cdvveesteseneccecseteeseeeees 371 FS_FAT_JournalClose e aaa an eaaa aaa dadaa aunan aandaa ahaaa adana 372 FS FAT JourmalStart 2s i e ra ENEE ANE EEN 373 FS_FAT_JOurnalStop cccccessseeeceeeesseeceeenseeaeeeeeeseaaeeeseeseaeeeeeeseeaes 374 FS FAT VOIGHK iiss ee adn aia cai nad lain edd 375 PC FS Error COGS wives scececccccsessitincdenceetensiteccrususdntedaveus aeaa Sa aaan Eaa 376 System Err
110. 55 Shell Commands F 3 15 fs touch Change file modification time USAGES fs touch file ARGUMENTS file File path OUTPUT None REQUIRED CONFIGURATION Available only if FS SHELL CFG TOUCH EN is DEF ENABLED and FS CFG RD ONLY EN is DEF_DISABLED NOTES WARNINGS The file modification time is set to the current time 556 F 3 16 fs umount Unount volume USAGES fs_umount vol ARGUMENTS vol Volume to unmount OUTPUT None REQUIRED CONFIGURATION Available only if FS_SHELL CFG _UMOUNT_EN is DEF_ENABLED NOTES WARNINGS None Shell Commands 557 F 3 17 fs we Determine the number of newlines words and bytes in a file USAGES fs we file ARGUMENTS file Path of file to examine OUTPUT Number of newlines words and bytes equivalent to Shell Commands printf d d d Ser newline cnt word ont byte ont file REQUIRED CONFIGURATION Available only if FS_SHELL CFG _WC_EN is DEF_ENABLED NOTES WARNINGS None COM4 PuTTY fs we lib str c 15091 Figure F 8 fs_we Output 558 Shell Commands F 4 CONFIGURATION Configuration constants can be used to enable disable features within the uC FS shell commands FS_SHELL_CFG_BUF_LEN FS FAT CFG BUF LEN defines the length of the buffer in octets used to read write from files during file access operations Since this buffer is placed on the task stack the task stack must be sized appropraitel
111. 6 CPU_BOOLEAN App FS AddNOR void FS_DEV_NOR_CFG nor cfg FS_ERR err FS_DevDrvAdd FS_DEV_API amp FSDev_Nor FS_ERR amp err if err FS_ERR_NONE NOR Flash Driver ER KN St amp amp err PG ERR DEV_DRV_ALREADY ADDED return DEF FAIL nor_cfg AddrBase APP CFG PG MO nor_cfg RegionNbr APP CFG PG MO 2 R_ADDR_BASE R REGION NBR nor_cfg AddrStart APP CFG PG MO APP_CFG ES MO APP_CFG ES MO APP_CFG ES MO APP CFG PSG NO nor_cfg DevSize nor_cfg SecSize nor_cfg PctRsvd nor_cfg PctRsvdSecActive R_ADDR_START R_DEV SIZE R_SEC_SIZE R_PCT_RSVD R_PCT RSVD_SEC_ACTIVE nor_cfg EraseCntDiffTh APP_CFG PG MO R ERASE CNT DIER H nor_cfg PhyPtr nor_cfg BusWidth APP CFG FS MO nor_cfg BusWidthMax APP CFG FS MO FS_DEV_NOR_PHY_API APP CFG FS NOR PHY PTR R_BUS WIDTH R_BUS WIDTH MAX nor_cfg PhyDevCnt APP CFG PG MO R_PHY DEV_CNT nor_cfg MaxClkFreq APP CFG PG MO R_MAX CLK FREQ FSDev_Open CPU_CHAR nor 0 void FS_ERR amp nor cfg amp err switch err case FS_ERR_NONE APP_TRACE_DBG break case FS_ERR_DEV_INVALID_LOW_FMT APP_TRACE_DBG FSDev_NOR_LowFmt nor 0 amp err if err FS ERR NONE APP_TRACE_DBG return DEF_FAIL break default APP_TRACE_DBG return DEF_FAIL opening device failed w err ES 33 CU es a yE b
112. 7 RETURNED VALUE None 266 LC FS API Reference Manual NOTES WARNINGS Device state change will result from device I O not present or timeout error A 4 DIRECTORY ACCESS FUNCTIONS void FSDir Close FS DIR p dir FS_ERR p err CPU_BOOLEAN FSDir IsOpen CPU_CHAR name_ full FS_ERR p err FS DIR FSDir_ Open CPU_CHAR name full FS_ERR p err void FSDir Rd FS_DIR p dir FS DIR ENTRY p dir entry FS_ERR p err 267 A 4 1 FSDir_Close void FSDir Close FS DIR p dir PG ERR p err File Called from LC FS API Reference Manual Code enabled by fs dir c Application fs_closedir Close and free a directory See fs_closedir for more information FS_CFG DIR EN ARGUMENTS p dir Pointer to a directory p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Directory closed FS_ERR_NULL PTR FS_ERR_INVALID TYPE FS_ERR_DIR DIS FS_ERR_DIR_NOT_OPEN RETURNED VALUE None NOTES WARNINGS None Argument p dir passed a NULL pointer Argument p dirs TYPE is invalid or unknown Directory module disabled Directory NOT open 268 LC FS API Reference Manual A 4 2 FSDir_IsOpen CPU_BOOLEAN FSDir Open CPU_CHAR name full FS_ERR p err File Called from Code enabled by fs dir c Application FS_CFG DIR EN fs_opendir FSEntry_ Test if a directory is already open This function is a
113. A 6 10 FSFile_LockSet void FSFile_ LockSet FS_FILE p file PG ERR p err File Called from Code enabled by fs file c Application fs_funlockfile FS_CFG FILE LOCK EN Release task ownership of a file See fs_funlockfile for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE File lock acquired FS_ERR_NULL PTR Argument p file passed a NULL pointer FS_ERR_INVALID_TYPE Argument p file s type is invalid or unknown FS ERR FILE NOT OPEN File NOT open FG ERR FILE NOT_LOCKED File NOT locked or locked by different task RETURNED VALUE None NOTES WARNINGS None 301 LC FS API Reference Manual A 6 11 FSFile_Open FS FILE FSFile Open CPU_CHAR name full FS FLAGS mode FS_ERR p err File Called from Code enabled by fs file c Application N A fs_fopen Open a file See fs _fopen for more information ARGUMENTS name full Name of the file See section 4 3 uC FS File and Directory Names and Paths on page 62 for information about file names mode File access mode see Notes 1 and 2 p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE File opened FS_ERR_NULL PTR Argument p name full passed a NULL pointer Or entry error see Section B 04 RETURNED VALUE None 302 LC FS API Reference Manual NOT
114. ACAI cccccessecceeeeseneeeeeeeseeneeeseeseeaeeeeeeeeaes 446 FSDev_NAND_BSP_WrCmdi ccccceseeecceeeseceeeeeesaeeeeeneseaeeeeeenseaes 447 FSDev_NAND_BSP_WrDatal cccssssssceeesseeeeeeeeeseeseeenseeeeeeeeneeees 448 FSDev_NAND_BSP_WaitWhileBusy c ccceessseeeeeeeseeeeeeeeneeees 449 NAND Flash SPI BSP REENEN i e 450 NOR Flash Physical Layer Driver ccccssseceseeseeeeeeeeeseeeeeeeeeeeeeeeeeeees 450 COP ONI MEE E A E T A A 453 GloSe aeaii E A E EEA RAA 454 Rd eg ee ee de eege deelen 455 WEILER A A E EA S AE E TAAN ee Ne de 456 TE 457 IO Ctrl e Seer in ete eae er a ee eee a 458 NOR Flash TE 459 FSDev_NOR_BSP_Open cesera 460 FSDev_NOR_BSP_ClOS cccccssecceeeeseeeeeeeeeseeeeeeeeseaeeeeeenneaeeeeenenees 461 F Dev NOR DGb Bd VU ee 462 FSDev_NOR_BSP_RAWoOrd_XX sesseeecceeeseneeeeeeseaeeeeeeeseneeeeeeeeeaes 463 FSDev_NOR_BSP_WrWoOrd_XX ccessseceeeeeseceeeeenssaeeeeeeeeaeeeeeneeaees 464 FSDev_NOR_BSP_WaitWhileBusy ccsssscceeesseeeeeeeeseeeeeeeeneeees 465 NOR Flash SPI EE 466 SD MMC Cardmode BSP cccecesseceeeeessseeeeeeeseeeeeeeeesseeeeeeeeseeeeeees 467 FSDev_SD_Card_BSP_Open seen 470 FSDev_SD_Card_BSP_LOCK 2 ceseesseeeeeeeeeeeeeeeeeeeeseeseeaeeeeeeeeeenees 471 FSDev_SD_Card_BSP_CmdStart c cccessesecceeeeseeeeeeesseeeeeeeenseees 472 C 12 4 C 12 5 C 12 6 C 12 7 C 12 8 C 12 9 C 12 10 C 12 11 C 12 12 C 13 C
115. AM disk driver The RAM disk driver supports using internal or external RAM as a storage medium E SD MMC driver The SD MMC driver supports SD SD high capacity and MMC cards including micro and mini form factors Either cardmode and SPI mode can be used Table 10 1 summarizes the drivers driver names and driver API structure names If you require more information about a driver please consult the listed chapter Driver Driver Name Driver API Structure Name Reference IDE CF ide FSDev_IDE Chapter 11 on page 124 MSC msc FSDev_MSC Chapter 13 on page 134 NAND nand FSDev_NAND Chapter 14 on page 137 NOR nor FSDev_NOR Chapter 15 on page 151 RAM disk rami FSDev_RAM Chapter 16 on page 170 120 Device Drivers Driver Driver Name Driver API Structure Name Reference SD MMC sd sdcard FSDev_SD SPI FSDev_SD Card Chapter 17 on page 174 Table 10 1 Device driver API structures If your medium is not supported by one of these drivers a new driver can be written based on the template driver Appendix C Device Driver on page 394 describes how to do this 10 1 1 DRIVER CHARACTERIZATION Typical ROM requirements are summarized in Table 10 2 The ROM data were collected on IAR EWARM v5 50 with high size optimization iver ROM Thumb ROM ARM Mode Mode IDE CF 3 6 kB 5 2 kB MSC 1 2 kB 1 6 kB NAND 8 7 kB 12 1 kB NOR 10 9 kB 15 2 kB RA
116. ARGUMENTS name_dev Device name partition_size OR Size of partition in sectors 0 if partition will occupy entire device p_err FS ERR NONE FS ERR DEV VOL OPEN FS ERR INVALID SEC MER FS ERR NAME NULL Pointer to variable that will receive the return error code from this function Partition structure initialized Volume open on device Sector start or count invalid Argument name_dev passed a NULL pointer Or device access error see section B 4 Device Error Codes on page 377 RETURNED VALUE None 259 LC FS API Reference Manual NOTES WARNINGS 1 Function blocked if a volume is open on the device All volume and files MUST be closed prior to initializing the partition structure since it will obliterate any existing file system 2 Device state change will result from device I O not present or timeout error 260 A 3 10 FSDev_Query void FSDev_Query CPU_CHAR LC FS API Reference Manual name_dev FS _DEV_INFO p info FS_ERR p err File Called from Code enabled by fs_dev c Application N A Obtain information about a device ARGUMENTS name dev Device name p_info Pointer to structure that will receive device information see Note p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE FS ERR NAME NULL FS ERR NULL PTR FS ERR INVALID SEC NBR Device information obtained Argument name_dev passed a NULL pointer
117. B 0 2 kB 2 2 kB 2 4 kB LFN support 6 5 kB 6 7 kB 9 3 kB 9 6 kB Directories 1 6 kB 2 2 kB 2 4 kB 3 3 kB Volume check 2 9 kB 3 2 kB 4 7 kB 5 3 kB Partitions 2 7 kB 3 0 kB 3 7 kB 4 2 kB Table 4 1 ROM Requirements Includes code and data for ALL file system components and functions except those itemized in the table 65 Miscellaneous RAM requirements are summarized in Table 2 2 The total depends on the number of each object allocated and the maximum sector size set by values passed to FS_Init in the file system configuration structure and various name length configuration parameters see Appendix E FS_CFG_MAX_PATH_NAME_LEN on page 530 Item RAM bytes Core 360 Per device 56 FS _CFG MAX DEV NAME LEN Per volume 166 FS CFG MAX VOL NAME LEN Per file 132 Per directory 48 Per buffer 36 MaxSectorSize Per device driver 20 bytes Working directories FS_CFG MAX PATH NAME LEN 2 TaskCnt Table 4 2 RAM Characteristics The number of tasks that use relative path names See also section 10 1 1 Driver Characterization on page 121 for ROM RAM characteristics of file system suite drivers 66 Chapter Devices and Volumes To begin reading files from a medium or creating files on a medium that medium hereafter called a device and the driver which will be used to access it must be registered with the file system After that a volume must be opened
118. BSP files in a directory named according to the following rubric Micrium Software EvalBoards lt manufacturer gt lt board_name gt lt compiler gt BSP Function Description FSDev_NOR_BSP_Open Open initialize bus for NOR FSDev_NOR_BSP_Close Close uninitialize bus for NOR FSDev_NOR_BSP_Rd_08 16 Read from bus interface FSDev_NOR_BSP_RdWord_08 16 Read word from bus interface FSDev_NOR_BSP_WrWord_08 16 Write word to bus interface FSDev_NOR_BSP_WaitWhileBusy Wait while NOR is busy Table C 6 NOR BSP Functions 459 LUC FS Porting Manual C 10 1 FSDev NOR BSP _Open CPU_BOOLEAN FSDev_NOR_BSP Open FS Om unit_nbr CPU_ADDR adr base CPU_INTO8U bus width CPU_INTO8U phy dev cnt File Called from Code enabled by fs_dev_nor_bsp c NOR physical layer driver N A Open initialize bus for NOR ARGUMENTS unit_nbr Unit number of NOR addr_base Base address of NOR bus_width Bus width in bits phy_dev_cnt Number of devices interleaved RETURNED VALUE DEE OR if interface was opened DEF_FAIL otherwise NOTES WARNINGS This function will be called EVERY time the device is opened 460 LUC FS Porting Manual C 10 2 FSDev_NOR_BSP _Close void FSDev_NOR_BSP Close FS QTY unit_ nbr File Called from Code enabled by fs_dev_nor_bsp c NOR physical layer driver N A Close uninitialize bus for NOR ARGUMENTS unit_nbr Unit number of NO
119. BSP_WaitWhileBusy FS_OTY unit_nbr FS DEV_NAND PHY DATA p addr CPU_BOOLEAN poll_fnct FS_DEV_NAND PHY DATA CPU_INT32U to_us File Called from Code enabled by fs_dev_nand_bsp c NAND physical layer driver N A Wait while NAND is busy ARGUMENTS unit_nbr Unit number of NAND p phy data Pointer to NAND phy data poll fnct Pointer to function to poll if there is no hardware ready busy signal to us Timeout in microseconds RETURNED VALUE DEF_OK if NAND became ready DEF_FAIL otherwise NOTES WARNINGS None 449 LUC FS Porting Manual C 8 NAND Flash SPI BSP The NAND driver must adapt to the specific hardware using a BSP A serial NAND Flash will be interfaced on a SPI bus See Appendix C SPI BSP on page 494 for the details on how to implement the software port for your SPI bus C 9 NOR Flash Physical Layer Driver The NOR driver is divided into three layers The topmost layer the generic driver requires an intermediate physical layer driver to effect flash operations like erasing blocks and writing octets The physical layer driver includes one code header file pair named according to the following rubric FS_DEV_ NOR lt device_name gt C FS_DEV_ NOR lt device_name gt H A non uniform flash a flash with some blocks of one size and some blocks of another will require a custom driver adapted from the generic driver for the most similar medium type Multiple small blocks should
120. C FS API Reference Manual name_dev FS_DEV_SD INFO p info FS ERR void FSDev_SD_SPI_QuerySD CPU_CHAR p err name_dev FS _DEV_SD INFO p info FS_ERR p err File Called from Code enabled by fs_dev_sd_card c Application N A fs_dev_sd_spi c Get low level information abou SD MMC card ARGUMENTS name_dev Device name see Note p_info Pointer to structure that will receive SD MMC card information p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE FS ERR NAME NULL FS ERR NULL PTR FS ERR DEV INVALID FS ERR DEV NOT OPEN FS ERR DEV NOT PRESENT FS ERR DEV IO FS _ERR_DEV_TIMEOUT SD MMC info obtained Argument name_dev passed a NULL pointer Argument p_info passed a NULL pointer Argument name_dev specifies an invalid device Device is not open Device is not present Device I O error Device timeout 365 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS The device MUST be a SD MMC device for FSDev_SD Card QuerySD e g sdcard 0 for FSDev_SD_SPI_QuerySD e g sd 0 366 LC FS API Reference Manual A 11 2 FSDev_SD_xxx_RdCID void FSDev_SD Card _RdCID CPU_CHAR name_dev CPU_INTO8U p info FS_ERR p err void FSDev_SD SPI _RdCID CPU_CHAR name_dev CPU_INTO8U p info FS_ERR p err File Called from Code enabled by fs_dev_sd_card c Application N A fs_dev_sd_s
121. CHAR name dev FS_ERR p err void FSDev_NOR_LowCompact CPU_CHAR name dev FS_ERR p err void FSDev_NOR_LowDefrag CPU_CHAR name dev FS_ERR p err void FSDev_NOR_PhyRd CPU_CHAR name dev void p dest CPU_INT32U start CPU_INT32U cnt FS_ERR p err void FSDev_NOR_PhyWr CPU_CHAR name dev void p src CPU_INT32U start CPU_INT32U cnt FS_ERR p err void FSDev_NOR_PhyEraseBlk CPU_CHAR name _dev CPU_INT32U start CPU_INT32U size FS_ERR p err 350 LC FS API Reference Manual void FSDev_NOR_PhyEraseChip CPU_CHAR name_dev FS_ERR p err 351 A 10 1 FSDev_NOR_LowFmit LC FS API Reference Manual void FSDev NOR LowFmt CPU_CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev_nor c Application N A Low level format a NOR device ARGUMENTS name_dev Device name see Note p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE FS ERR NAME NULL FS ERR DEV INVALID FS ERR DEV NOT OPEN FS ERR DEV NOT PRESENT FS ERR DEV INVALID LOW FMT FS ERR DEV IO FS ERR DEV TIMEOUT RETURNED VALUE None NOTES WARNINGS Device low level formatted successfully Argument name_dev passed a NULL pointer Argument name_dev specifies an invalid device Device is not open Device is not present Device needs to be low level formatted Device I O error Device timeout The device MUST be a NOR device e g
122. CHE Fa The Embedded File System User s Manual V4 04 Micrium For the Way Engineers Work Micrium 1290 Weston Road Suite 306 Weston FL 33326 USA www micrium com Designations used by companies to distinguish their products are often claimed as trademarks In all instances where Micrium Press is aware of a trademark claim the product name appears in initial capital letters in all capital letters or in accordance with the vendor s capatilization preference Readers should contact the appropriate companies for more complete information on trademarks and trademark registrations All trademarks and registerd trademarks in this book are the property of their respective holders Copyright 2010 by Micrium except where noted otherwise All rights reserved Printed in the United States of America No part of this publication may be reproduced or distributed in any form or by any means or stored in a database or retrieval system without the prior written permission of the publisher with the exception that the program listings may be entered stored and executed in a computer system but they may not be reproduced for publication The programs and code examples in this book are presented for instructional value The programs and examples have been carefully tested but are not guaranteed to any particular purpose The publisher does not offer any warranties and does not guarantee the accuracy adequacy or completeness of any info
123. Capacity SD card De SEND_CID 6 gs n SEND_CSD 7 Figure 17 13 Simplified SD MMC SPI mode initialization and state transitions The initialization process reveals that commands can be executed and proper responses are returned The command responses in SPI mode are identical to those in cardmode see Figure 17 5 and Figure 17 6 except each is preceded by a R1 status byte Obvious errors such as improper initialization or failed chip select manipulation will typically be caught here More subtle conditions may appear intermittently during reading or writing 196 SD MMC Drivers 17 3 3 SD MMC SPI BSP OVERVIEW An SPI BSP is required so that the SD MMC SPI driver will work on a particular system For more information about these functions see section C 14 SPI BSP on page 494 Function Description FSDev_SD SPI_BSP_SPI_Open Open initialize SPI FSDev_SD SPI_BSP SPI Close Close uninitialize SPI FSDev_SD SPI_BSP_SPI_Lock Acquire SPI lock FSDev_SD SPI_BSP_SPI_Unlock Release SPI lock FSDev_SD SPI_BSP_SPI_Rd Read from SPI FSDev_SD SPI_BSP SPI Wr Write to SPI FSDev_SD SPI _BSP_SPI_ChipSelEn Enable chip select FSDev_SD SPI _BSP_SPI_ChipSelDis Disable chip select FSDev_SD SPI_BSP SPI SetClkFreq Set SPI clock frequency Table 17 5 SD MMC SPI BSP Functions 197 Appendix UC FS API Reference Manual This chapter provides a
124. D OP Device invalid operation FS_ERR_DEV_IO Device I O error PG ERR DEV_TIMEOUT Device timeout error RETURNED VALUE None 434 LUC FS Porting Manual C 6 5 WrPage void WrPage FS_DEV_NAND PHY DATA p phy data void p src void p src_spare FS_SEC_NBR sec_nbr_ phy FS_ERR p err File Called from Code enabled by NAND physical layer driver FSDev_NAND_PhyWrSecHandler N A Write to a NAND device ARGUMENTS p phy data Pointer to NAND phy data p sre Pointer to source buffer p_src_spare Pointer to source spare buffer sec_nbr phy Physical sector to write p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Octets written successfully FS_ERR_DEV_INVALID OP Device invalid operation FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout error RETURNED VALUE None NOTES WARNINGS None 435 LUC FS Porting Manual C 6 6 WrSpare void WrSpare FS_DEV_NAND PHY DATA p phy data void p src FS_SEC_NBR sec_nbr_ phy CPU_INTO8U offset CPU_INTO8U bytes _nbr FS_ERR p err File Called from Code enabled by NAND physical layer driver FSDev_NAND_PhyWrSpareHandler N A Write data to a NAND device page spare area ARGUMENTS p phy data Pointer to NAND phy data p sre Pointer to source buffer sec_nbr_ phy Sector number for which the spare area will be written offset Offset in the spare area
125. ERR p err void FS_FAT JournalStart CPU_CHAR name vol FS_ERR p err void FS _ FAT JournalStop CPU_CHAR name vol FS_ERR p err void FS_FAT VolChk CPU_CHAR name vol FS_ERR p err 370 LC FS API Reference Manual A 12 1 FS_FAT_JournalOpen File Called from Code enabled by fs_fat_journal c Application FS_CFG FAT JOURNAL EN Open journal on volume ARGUMENTS name vol Volume name p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Journal opened FS_ERR_DEV Device access error RETURNED VALUE None NOTES WARNINGS None 371 LC FS API Reference Manual A 12 2 FS_FAT_JournalClose void FS_FAT JournalClose CPU_CHAR name vol FS_ERR p err File Called from Code enabled by fs_fat_journal c Application FS_CFG FAT JOURNAL EN Close journal on volume ARGUMENTS name vol Volume name p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Journal closed FS_ERR_DEV Device access error RETURNED VALUE None NOTES WARNINGS None 372 LC FS API Reference Manual A 12 3 FS_FAT_JournalStart void FS_FAT JournalStart CPU_CHAR name vol FS_ERR p err File Called from Code enabled by fs_fat_journal c Application FS_CFG FAT JOURNAL EN Start journaling on volume ARGUMENTS name vol Volume name p err Pointer to variable th
126. ES WARNINGS 1 The access mode should be the logical OR of one or more flags FS FILE ACCESS MODE RD File opened for reads FS_FILE ACCESS MODE WR File opened for writes FS_FILE ACCESS MODE CREATE File will be created if necessary FS_FILE ACCESS MODE TRUNC File length will be truncated to 0 FS_FILE ACCESS MODE APPEND All writes will be performed at EOF FG FILE ACCESS MODE EXCL File will be opened if and only if it does not already exist FS_FILE ACCESS MODE CACHED File data will be cached E If FS_ FILE ACCESS MODE TRUNC is set then FS_FILE ACCESS MODE WR must also be set E If FS FILE ACCESS MODE EXCL is set then FS FILE ACCESS MODE CREATE must also be set E FS FILE ACCESS MODE RD and or FS_FILE ACCESS MODE WR must be set 2 The mode string argument of fs_fopen function can specify a subset of the possible valid modes for this function The equivalent modes of fs_fopen mode strings are shown in Table 5 4 303 LC FS API Reference Manual fopen Mode String mode Equivalent vm or rb FS FILE ACCESS MODE RD w or wb FS_FILE ACCESS MODE WR PG FILE ACCESS MODE CREATE PG FILE ACCESS MODE TRUNC a or ab PG FILE ACCESS MODE WR PG FILE ACCESS MODE CREATE PG FILE ACCESS MODE APPEND r or rb or r b FS FILE ACCESS MODE FS FILE ACCESS MODE aS w or wb or w b FS FILE ACCESS MODE RD FS FILE ACCESS MODE WR FS FILE ACCE
127. ETURNED VALUE None NOTES WARNINGS None 445 LUC FS Porting Manual C 7 6 FSDev_NAND_BSP_WrAddr void FSDev_NAND BSP_WrAddr PG Om unit_nbr CPU_INTO8U p addr CPU_SIZE T cnt File Called from Code enabled by Ca dev nand bsp c NAND physical layer driver N A Write address to NAND ARGUMENTS unit_nbr Unit number of NAND p_addr Pointer to buffer that holds address ent Number of octets to write RETURNED VALUE None NOTES WARNINGS None 446 LUC FS Porting Manual C 7 7 FSDev_NAND_BSP_WrCmd void FSDev_NAND BSP_WrCmd FS Om unit_nbr CPU_INTO8U p cmd CPU_SIZE T cnt File Called from Code enabled by fs_dev_nand_bsp c NAND physical layer driver N A Write command to NAND ARGUMENTS unit_nbr Unit number of NAND p_cmd Pointer to buffer that holds command ent Number of octets to write RETURNED VALUE None NOTES WARNINGS None 447 LUC FS Porting Manual C 7 8 FSDev_NAND_BSP_WrData void FSDev_NAND BSP _WrData PG Om unit_nbr CPU_INTO8U p src CPU_SIZE T cnt File Called from Code enabled by fs_dev_nand_bsp c NAND physical layer driver N A Write data to NAND ARGUMENTS unit_nbr Unit number of NAND p srce Pointer to source memory buffer cnt Number of octets to write RETURNED VALUE None NOTES WARNINGS None 448 LUC FS Porting Manual C 7 9 FSDev_NAND_BSP_WaitWhileBusy CPU_BOOLEAN FSDev_NAND
128. FSDev_Refresh FSDev_QueryLocked The device driver Query function gets information about a device ARGUMENTS p_dev Pointer to device to query p_info Pointer to structure that will receive device information p_err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Device information obtained FS_ERR_DEV_INVALID UNIT NR Device unit number is invalid PG ERR DEV MO ODEN Device is not open PG ERR DEV MO PRESENT Device is not present RETURNED VALUE None NOTES WARNINGS 1 Tracking whether a device is open is not necessary because this should ONLY be called when a device is open 2 The device driver Query function is called while the caller holds the device lock 404 LUC FS Porting Manual For more information about the FS_DEV_INFO structure see section D 2 FS_DEV_INFO on page 510 405 LUC FS Porting Manual C 4 8 IO Gi static void FSDev_ IO Ctrl PSG DEV p dev FS IO CTRL CMD cmd Void p buf FS_ERR p err File Called from Code enabled by fs_dev_ H f c various N A The device driver IO_Ctr1 function performs an I O control operation ARGUMENTS p_dev Pointer to device to query p_buf Buffer which holds data to be used for operations OR Buffer in which data will be stored as a result of operation p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Control operation performed suc
129. FSVOIR E 332 FSVOLSW gegen e 334 Volume Cache Functions ccccccceeeeeeeeseeeeeeeeeeeeeeeeeeeeeseesaneeeeeeeenees 335 FSVol CacheAssign lt iiiececesiciceceeescetenceetecie cdeesecsi Ceneeestetententecteedenvenet 336 FSVol_Cachelnvalidate ccccssssccecsseeeceeeesseeeeeeessaeeeeeesaaeeeeeneeaes 338 FSVol_CacheFIUush D cecsescceeeesseeeceeeeseeeeeeeneseaeeeeeeseaeeeeseseaaeeeeeneneas 339 A 9 A 9 1 A 9 2 A 9 3 A 9 4 A 9 5 A 9 6 A 10 A 10 1 A 10 2 A 10 3 A 10 4 A 10 5 A 10 6 A 10 7 A 10 8 A 10 9 A 11 A 11 1 A 11 2 A 11 3 A 12 A 12 1 A 12 2 A 12 3 A 12 4 A 12 5 Appendix B B 1 B 2 B 3 B 4 B 5 B 6 B 7 B 8 B 9 NAND Driver FUNCTIONS ee oirne aiaa aaaea e aaae aa taeae asiana 340 FSDev_NAND_LowFmt cccceseeccceeeeseeeceeeeeeeeeeeeseseeaeeeeenseaeeeeeneeaes 341 FSDev_NAND_LOWMOUNM eccseceeeeeseeeceeeeeeaeeeeeeseneeeeeenseaeeeeeneneas 342 FSDev_NAND_LOWUNMOUMNK cccceeesseeeeeeeeseeeeeeeeeseaeeeeeneseaeeeeeneees 343 FSDev_NAND_PhyRdSec cceecccecesseeeeeeesseeeeeeeesseaeeeeenseaaeeeeeneeaes 344 FSDev_NAND_PhyWrSec eseeccceeesseeeceeeeeseeeeeeeeseaeeeeenseaaeeeeenneaes 346 FSDev_NAND_PhyEraseBIk cceseccesseeeeeeeeeeeseeeeeeeeeeesseeeeeneeeeeenees 348 NOR Driver FUNCTIONS lt x deccescsccceetenceecceceesansecetieae ae A Aaaa deo aae 350 FSDev_NOR_LOWFt c ccccceesseeceeeeeseeeeeeeeeseaeeeeeeseaeeeeseseaaeeeeeneeees 3
130. FS_FAT_SYS_CFG on page 520 78 Devices and Volumes 5 7 USING VOLUME CACHE File accesses often incur repeated reading of the same volume sectors On a FAT volume these may be sectors in the root directory the area of the file allocation table FAT from which clusters are being allocated or data from important often read files A cache wedged between the system driver and volume layers as shown in Figure 5 8 will eliminate many unnecessary device accesses Sector data is stored upon first read or write Further reads return the cached data further writes update the cache entry and possibly the data on the volume depending on the cache mode FAT System Driver fs_sys fs_fat Figure 5 8 Volume cache architecture A cache is defined by three parameters size sector type allocation and mode The size of the cache is the number of sectors that will fit into it at any time Every sector is classified according to its type either management directory or file the sector type allocation determines the percentage of the cache that will be devoted to each type The mode determines when cache entries are created i e when sectors are cached and what happens upon write 79 Cache Mode Description Devices and Volumes Cache Mode define Read cache Sectors cached upon read never cached upon write FS_VOL_CACHE_MODE_RD Write through cache Sectors cached upon read and write data on volume always
131. Figure 6 2 Example directory listing The second argument fs_readdir_r is a pointer to a struct fs_dirent which has two members The first is Name which holds the name of the entry the second is Info which has file information For more information about the struct fs_dirent structure see section D 6 FS_DIR_ENTRY struct fs_dirent on page 517 6 5 ENTRY ACCESS FUNCTIONS The entry access functions provide an API for performing single operations on file system entries files and directories such as renaming or deleting a file Each of these operations is atomic consequently in the absence of device access errors either the operation will have completed or no change to the storage device will have been made upon function return A new directory can be created with fs_mkdir or an existing file or directory deleted or renamed with fs _remove or fs_rename 96 Chapter Files An application stores information in a file system by creating a file or appending new information to an existing file At a later time this information may be retrieved by reading the file Other functions support these capabilities for example the application can move to a specified location in the file or query the file system to get information about the file These functions which operate on file structures FS_FILEs are grouped under file access or simply file functions The available file functions are listed in Table 7 1 A separat
132. ILE NOT OPEN FS ERR FILE NOT LOCKED FS ERR FILE OVF FS ERR FILE OVF_OFFSET B 10 NAME ERROR CODES FS ERR NAME BASE TOO LONG FS ERR NAME EMPTY FS ERR NAME EXT TOO LONG FS ERR NAME INVALID FS ERR NAME MIXED CASE FS ERR NAME NULL FS ERR NAME PATH TOO LONG LIC FS Error Codes Operation not allowed on entry corresponding to an open file dir File already open Buf already assigned Error indicator set on file Access mode is specified invalid Attributes are specified invalid Buf mode is specified invalid or unknown Buf size is specified invalid Date time is specified invalid Date time flag is specified invalid Name is specified invalid Origin is specified invalid or unknown Offset is specified invalid Invalid file arguments File operation invalid File operation sequence invalid File position invalid File locked No file available File NOT open File NOT locked File size overflowed max file size File offset overflowed max file offset Base name too long Name empty Extension too long Invalid file name or path Name is mixed case Name ptr arg s passed NULL ptr s Entry path is too long 379 FS ERR NAME BUF_TOO SHORT FS ERR NAME TOO LONG LIC FS Error Codes Buffer for name is too short Full name is too long B 11 PARTITION ERROR CODES FS ERR PARTITION INVALID FS ERR PARTITION INVALID NBR FS ERR PARTITION INVALID SIG FS ERR PARTITION INVALID SIZE FS ERR PARTIT
133. INGS DMA setup occurs before the command is executed in FSDev_IDE_BSP_CmdWr Afterwards data transmission completion must be confirmed Gn FSDev_IDE Dep DS End before the driver checks the command status If the return value of FSDev_IDE BSP GetModesSupported does not include FS_DEV_IDE MODE TYPE DMA or FS DEV IDE MODE TYPE UDMA this function need not be implemented it will never be called C 5 11 FSDev_IDE_ BSP_DMA _End void FSDev_IDE BSP_DMA End PG QTY unit_nbr void p data CPU_SIZE T cnt CPU_BOOLEAN rd File Called from Code enabled by fs_dev_ide bsp c FSDev_IDE_RdData N A FSDev_IDE_WrData Setup DMA for command initialize channel ARGUMENTS unit_nbr Unit number of IDE CF device p data Pointer to memory buffer cnt Number of octets to transfer rd Indicates whether transfer was read or write DEF_YES Transfer was read DEF_NO Transfer was write 420 LUC FS Porting Manual RETURNED VALUE None NOTES WARNINGS DMA setup occurs before the command is executed in FSDev_IDE BSP_CmdWr Afterwards data transmission completion must be confirmed Gn FSDev_IDE BSP DMA End before the driver checks the command status When this function returns the host controller should be setup to transmit commands in PIO mode If the return value of FSDev_IDE BSP GetModesSupported does not include FS _DEV_IDE MODE TYPE DMA or FS DEV IDE MODE TYPE UDMA this function need not be implemen
134. ION MAX FS ERR PARTITION NOT FINAL FS ERR PARTITION NOT FOUND FS ERR PARTITION ZERO B 12 POOLS ERROR CODES FS ERR POOL EMPTY FS ERR POOL FULL FS ERR POOL INVALID BLK ADDR FS ERR POOL INVALID BLK IN POOL FS ERR POOL INVALID BLK IX FS ERR POOL INVALID BLK NBR FS ERR POOL INVALID BLK SIZE Partition invalid Partition nbr specified invalid Partition sig invalid Partition size invalid Max nbr partitions have been created in MBR Prev partition is not final partition Partition NOT found Partition zero Pool is empty Pool is full Block not found in used pool pointers Block found in free pool pointers Block index invalid Number blocks specified invalid Block size specified invalid B 13 FILE SYSTEM ERROR CODES FS ERR SYS TYPE NOT SUPPORTED FS ERR SYS INVALID SIG FS ERR SYS DIR ENTRY PLACE FS ERR SYS DIR ENTRY NOT FOUND FS ERR SYS DIR ENTRY NOT FOUND YET FS ERR SYS SEC NOT FOUND FS ERR SYS CLUS CHAIN END FS ERR SYS CLUS CHAIN END EARLY FS ERR SYS CLUS INVALID FS ERR SYS CLUS NOT AVAIL File sys type not supported Sec has invalid OR illegal sig Dir entry could not be placed Dir entry not found Dir entry not found yet Sec not found Cluster chain ended Cluster chain ended before number clusters traversed Cluster invalid Cluster not avail 380 FS ERR SYS SFN HOT AVAIL FS ERR SYS LFN ORPHANED B 14 VOLUME ERROR CODES FS ERR VOL INVALID NAME FS ERR VOL INVALID SIZE
135. IR FS ERR ENTRY TYPE INVALID LIC FS Error Codes B 5 DEVICE DRIVER ERROR CODES Device driver already added Invalid device driver name No pos available in device driver table B 6 DIRECTORY ERROR CODES Directory already open Directory module disabled Directory is full No directory avail Directory not open Correctable ECC error Uncorrectable ECC error Paths specify same file system entry Paths do not both specify files OR directories Paths specify file system entries on different vols File system entry is corrupt File system entry exists File system entry invalid File system entry NOT a directory File system entry NOT empty File system entry NOT a file File system entry NOT found Entry parent NOT found Entry parent NOT a directory File system entry marked read only File system entry is a root directory File system entry type is invalid 378 FS ERR ENTRY OPEN B 9 FILE ERROR CODES FS ERR FILE ALREADY OPEN FS ERR FILE BUF ALREADY ASSIGNED FS ERR FILE ERR FS ERR FILE INVALID ACCESS MODE FS ERR FILE INVALID ATTRIB FS ERR FILE INVALID BUF MODE FS ERR FILE INVALID BUF SIZE FS ERR FILE INVALID DATE TIME FS ERR FILE INVALID DATE TIME FLAG FS ERR FILE INVALID NAME FS ERR FILE INVALID ORIGIN FS ERR FILE INVALID OFFSET FS ERR FILE INVALID FILES FS ERR FILE INVALID OP FS ERR FILE INVALID OP SEQ FS ERR FILE INVALID POS FS ERR FILE LOCKED FS ERR FILE NONE AVAIL FS ERR F
136. Listing 13 2 uC USB MSC notification function If the file system and USB stack initialization succeed the file system will produce the trace output as shown in Figure 13 1 Gf a sufficiently high trace level is configured when the a MSC device is connected See section E 9 Trace Configuration on page 534 about configuring the trace level Figure 13 1 MSC Detection Trace Output 136 Chapter 14 NAND Flash Driver NAND flash is a low cost on board storage solution Typically NAND flash have a multiplexed bus for address and data resulting in a much lower pin count than parallel NOR devices Their low price per bit and relatively high capacities often makes these preferable to NOR though the higher absolute cost because the lowest capacity devices are at least 128 Mb reverses the logic for applications requiring very little storage Standard storage media like hard drives or managed flash based devices like SD MMC and CF cards require relatively simple drivers that convert the file system s request to read or write a sector into a hardware transaction The driver for a raw NAND flash or raw NOR flash for that matter is more complicated Flash is divided into large blocks often 16 kB to 512 kB however the high level software expects to read or write small sectors 512 bytes to 4096 bytes atomically The driver implements a small block abstraction SBA to conceal the device geometry from the file system To aggravate
137. Lock Acquire SD MMC card bus lock FSDev_S D Card _BSP_Unlock Release SD MMC card bus lock FSDev_S D Card BSP CmdStart Start a command FSDev_S D Card _BSP_CmdWaitEnd Wait for a command to end and get response FSDev_S D Card BSP _CmdDataRd Read data following command FSDev_S D Card _BSP_CmdDataWr Write data following command FSDev_S D Card _BSP_GetB1kCntMax Get max block count FSDev_S D Card _BSP_GetBusWidthMax Get maximum bus width in bits 187 SD MMC Drivers Function Description FSDev_SD Card BSP _SetBusWidth Set bus width FSDev_SD Card BSP SetClkFreq Set clock frequency FSDev_SD Card BSP _SetTimeoutData Set data timeout FSDev_SD Card BSP_SetTimeoutResp Set response timeout Table 17 3 SD MMC cardmode BSP functions The Open Close functions are called upon open close or medium change these calls are always matched The status and information functions GetBlkCntMax GetBusWidthMax SetBusWidth SetClkFreq SetTimeoutData SetTimeoutResp help configure the new card upon insertion Lock and Unlock surround all card accesses The remaining functions CmdStart CmdWaitEnd CmdDataRd CmdDataWr constitute the command execution state machine see Figure 17 9 A return error from one of the functions will abort the state machine so the requisite considerations such as pre
138. M disk 0 9 kB 1 2 kB SD MMC CardMode 5 9 kB 8 6 kB SD MMC SPI 5 5 kB 7 9 kB Table 10 2 Driver ROM requirements Not including BSP Not including pC USB Not including physical level driver or BSP Typical RAM requirements are summarized in Table 10 3 121 Device Drivers Driver RAM Overhead RAM Per Device IDE CF 8 bytes 24 bytes MSC 12 bytes 32 bytes NAND 8 bytes bytes NOR 8 bytes bytes RAM disk 8 bytes 24 bytes SD MMC CardMode 8 bytes 54 bytes SD MMC SPI 8 bytes 54 bytes Table 10 3 Driver RAM requirements Not including pC USB See section 15 2 Driver amp Device Characteristics on page 154 Performance can vary significantly as a result of CPU and hardware differences both as well as file system format Table 10 4 lists results for three general performance tests P Read file test Read a file in 4 kB chunks The time to open the file is NOT included in the time P Write file test Write a file in 4 kB chunks The time to open create the file is NOT included in the time 122 Device Drivers Performance kB s Driver CPU Configuration Read file Write file IDE CF Freescale iMX27 200 MHz 7930 kB s 1140 kB s MSC NXP LPC2468 48 MHz 309 kB s 142 kB s NOR parallel ST STM32F103VE 72 MHz 1820 kB s 213 kB s NOR serial ST STM32F103VE 72 MHz 691 kB s 55 kB s RAM disk NXP LPC2468 48 MHz 8260 kB s 4530 kB s SD MMC Card
139. MENTS name dey Pointer to the device name p err Pointer to variable that will receive return error code from this function FS_ERR_NONE Number of partitions obtained FS ERR DEV _VOL_ OPEN Volume open on device FS_ERR_INVALID SIG Invalid MBR signature FS ERR NAME NULL Argument name deyv passed a NULL pointer Or device access error see section B 4 Device Error Codes on page 377 RETURNED VALUE Number of partitions on the device if no error was encountered Zero otherwise NOTES WARNINGS Device state change will result from device I O not present or timeout error 253 A 3 6 FSDev_Open void FSDev_Open CPU_CHAR name_dev LC FS API Reference Manual void p dev_cfg FS_ERR p err File Called from Code enabled by fs deu Application Open a device ARGUMENTS name_dev p_dev_cfg p_err N A Device name See section 4 3 uC FS File and Directory Names and Paths on page 62 for information about device names Pointer to device configuration Pointer to variable that will receive the return error code from this function see Note 2 FS_ERR_NONE FS ERR DEV ALREADY OPEN FS ERR DEV INVALID LOW FMT FS ERR DEV INVALID NAME FS ERR DEV INVALID SEC SIZE FS ERR DEV INVALID SIZE FS ERR DEV INVALID UNIT NBR FS ERR DEV IO FS ERR DEV NONE AVAIL FS ERR DEV NOT PRESENT FS ERR DEV TIMEOUT FS ERR DEV UNKNOWN FS ERR NAME NULL Device opened successfully D
140. MENTS name full old Old path of the entry See section 4 3 uC FS File and Directory Names and Paths on page 62 name full new New path of the entry excl Indicates whether the creation of the new entry shall be exclusive see Note 1 DEF YES if the entry shall be renamed only if name_full_new does not exist DEF_NO if the entry shall be renamed even if name_full_new does exist p_err Pointer to variable that will the receive return error code from this function FS_ERR_NONE File copied successfully PG ERR NULL PTR Argument name full old or name_full_new passed a NULL pointer FS_ERR_NAME INVALID Entry name specified invalid OR volume could not be found FG ERR NAME PATH TOO LONG Entry name specified too long FS_ERR_VOL_NOT_OPEN Volume was not open FS_ ERR VOL NOT MOUNTED Volume was not mounted 284 LC FS API Reference Manual PG ERR DUE NONE AVAIL Buffer not available FS_ERR_DEV Device access error PG ERR NAME INVALID Invalid file name or path Or entry error RETURNED VALUE None NOTES WARNINGS 1 If name_full_old and name full_new specify entries on different volumes then name_full_old MUST specify a file If name_full_old specifies a directory an error will be returned If name_full_old and name_full_new specify the same entry the volume will not be modified and no error will be returned If name_full_old specifies a file a name_full_new must NOT specify a directory b if excl is DEF_NO
141. Mode NXP LPC2468 48 MHz 1 bit mode 1010 kB s 387 kB s SD MMC CardMode NXP LPC2468 48 MHz 4 bit mode 2310 kB s 557 kB s SD MMC SPI NXP LPC2468 48 MHz 405 kB s 212 kB s SD MMC SPI NXP LPC2468 48 MHz w CRC 356 kB s 197 kB s Using 4 GB SanDisk Ultra II CF card Using 1 GB SanDisk Cruzer Micro it ong ST M29W128GL NOR SU ang ST M25P64 serial flash Using 2 GB SanDisk Ultra II SD card Table 10 4 Driver performance file test 123 Chapter 17 IDE CF Driver Compact flash CF cards are portable low cost media often used for storage in consumer devices Several variants in different media widths are widely available all supported by the IDE driver ATA IDE hard drives are also supported by this driver 11 1 FILES AND DIRECTORIES The files inside the IDE driver directory are outlined in this section the generic file system files outlined in Chapter 3 Directories and Files on page 28 are also required Micrium Software uC FS Dev This directory contains device specific files Micrium Software uC FS Dev IDE This directory contains the IDE driver files fs dev_ide are device driver for IDE devices This file requires a set of BSP functions be defined in a file named fs_dev_ide_bsp c to work with a certain hardware setup BSP Template fs_dev_ide_bsp c is a template BSP See section C 5 IDE CF Device BSP on page 408 for more information Micrium Software uC FS Examples BSP
142. N DEF_DISABLED FSDev_ _Wr endif FSDev_ _Query FSDev_ IO Ctrl H The functions which must be implemented are listed and described in Table C 1 The first two functions NameGet and Init act upon the driver as a whole neither should interact with any physical devices The remaining functions act upon individual devices and the first argument of each is a pointer to a FS_DEV structure which holds device information including the unit number which uniquely identifies the device unit member UnitNbr Function Description NameGet Get driver name Init Initialize driver Open Open a device Close Close a device Rd Read from a device Wr Write to a device Query Get information about a device 394 LUC FS Porting Manual Function Description IO Ctrl Execute device I O control operation Table C 1 Device Driver API Functions 395 LUC FS Porting Manual C 4 1 NameGet static const CPU CHAR FSDev_ 4 NameGet void File Called from Code enabled by fs_dev_ H c various N A Device drivers are identified by unique names on which device names are based For example the unique name for the NAND flash driver is nand the NAND devices will be named nand 0 nand 1 etc ARGUMENTS None RETURNED VALUE Pointer to the device driver name NOTES WARNINGS 1 The name MUST NOT include the 7 character
143. NICATION SPI is a simple protocol supported by peripherals commonly built in on CPUs Moreover since the communication can easily be accomplished by software control of GPIO pins software SPI or bit banging a SD MMC card can be connected to almost any platform In SPI mode seven pins on the SD MMC device are used with the functions listed in Table 17 4 As with any SPI device four signals are used to communicate with the host CS DataIn CLK and DataOut Some card holders contain circuitry for card detect and write protect indicators which the MCU MPU may also monitor Pin Name Type Description 1 cs l Chip Select 2 Dataln l Host to card commands and data 3 Vss1 S Supply voltage ground 4 VDD S Supply voltage 5 CLK l Clock 6 VSS2 S Supply voltage ground 7 DataOut O Card to host data and status Table 17 4 SD MMC Pinout SPI Mode The four signals connecting the host or master and card also known as the slave are named variously in different manuals and documents The DataIn pin of the card is also known as MOSI Master Out Slave In it is the data output of the host CPU Similarly the DataOut pin of the card is also known as MISO Master In Slave Out it is the data input of the host CPU The CS and CLK pins also known as SSEL and SCK are the chip select and clock pins The host selects the slave by asserting CS potentially allowing it to choose a single peripheral among several th
144. NINGS FSDev_IDE BSP _Lock will be called before the IDE CF driver begins to access the IDE CF bus The application should NOT use the same bus to access another device until the matching call to FSDev_IDE_BSP_Unlock has been made 412 LUC FS Porting Manual C 5 4 FSDev_IDE_BSP_Reset void FSDev_IDE BSP Reset FS Om unit_nbr File Called from Code enabled by fs_dev_ide_bsp c FSDev_IDE_Refresh N A Hardware reset the IDE CF device ARGUMENTS unit_nbr Unit number of IDE CF device RETURNED VALUE None NOTES WARNINGS None 413 C 5 5 FSDev_IDE_BSP_RegRd CPU_INTO8U FSDev_ IDE BSP RegRd FS QTY LUC FS Porting Manual unit_nbr CPU_INTO8U_ reg File Called from Code enabled by fs_dev_ide_bsp c various Read from IDE CF device register ARGUMENTS unit_nbr Unit number of IDE CF device reg Register to read FS DEV_IDE REG ERR FS DEV IDE REG SC FS DEV_IDE REG SN FS DEV_IDE REG CYL FS DEV_IDE REG CYH FS DEV_IDE REG DH FS DEV_IDE REG CMD FS DEV_IDE REG ALTSTATUS RETURNED VALUE Register value NOTES WARNINGS None N A Error Register Sector Count Register Sector Number Register Cylinder Low Register Cylinder High Register Card Drive Head Register Command Register Alternate Status Register 414 C 5 6 FSDev_IDE_BSP_RegWr void FSDev_IDE BSP RegWr FS Om CPU_INTO8U CPU_INTO8U File Called from LUC FS Port
145. NONE Device opened successfully FS_ERR_DEV_ALREADY_OPEN Device unit is already opened FS_ERR_DEV_INVALID CFG Device configuration specified invalid FS_ERR_DEV_INVALID_LOW_FMT Device needs to be low level formatted FS_ERR_DEV_INVALID_LOW_PARAMS Device low level device parameters invalid FS_ERR_DEV_INVALID UNIT NBR Device unit number is invalid FS_ERR_DEV_IO Device I O error FS_ERR_DEV_ NOT PRESENT Device unit is not present FS_ERR_DEV_TIMEOUT Device timeout FS ERR MEM ALLOC Memory could not be allocated RETURNED VALUE None 398 LUC FS Porting Manual NOTES WARNINGS 1 Tracking whether a device is open is not necessary because this should NEVER be called when a device is already open 2 Some drivers may need to track whether a device has been previously opened indicating that the hardware has previously been initialized 3 This will be called EVERY time the device is opened 4 The driver should identify the device instance to be opened by checking p_dev gt UnitNbr For example if template 2 is to be opened then p_dev gt UnitNbr will hold the integer 2 5 The device driver Open function is called while the caller holds the device lock 399 LUC FS Porting Manual C 4 4 Close static void FSDev_ HH Close FS_DEV p dev File Called from Code enabled by fs_dev_ Hf f c FSDev_Close N A The device driver Close function should uninitialize the hardware and release or free an
146. NOR_LowFmt low level formats a NOR If the NOR has never been used with uC FS it must be low level formatted before being used Low level formatting will associate logical sectors with physical areas of the device 158 NOR Flash Driver FSVol_Open opens mounts a volume The parameters are the volume name 5a the device name 5b and the partition that will be opened 5c There is no restriction on the volume name 5a however it is typical to give the volume the same name as the underlying device If the default partition is to be opened or if the device is not partition then the partition number 5c should be zero FSVol_Fmt formats a file system device If the NOR has just been low level format it will have no file system on it after it is opened Ct will be unformatted and must be formatted before files can be created or accessed If the NOR initialization succeeds the file system will produce the trace output as shown in Figure 15 1 Gf a sufficiently high trace level is configured See section E 9 Trace Configuration on page 534 about configuring the trace level COM1 PuTTY EIS Figure 15 1 NOR detection trace output 159 NOR Flash Driver 15 3 1 DRIVER ARCHITECTURE When used with a parallel NOR device the NOR driver is three layered as depicted in the figure below The generic NOR driver as always provides sector abstraction and performs wear leveling to make certain all blocks are used equally
147. NOTES WARNINGS 1 Entries for dot current directory and dot dot parent directory shall be returned if present No entry with an empty name shall be returned 2 Ifan entry is removed from or added to the directory after the directory has been opened information may or may not be returned for that entry 236 LC FS API Reference Manual A 2 27 fs_remove int fs _remove const char name full File Called from Code enabled by fs_api c Application FS_CFG_API_EN and not FS_CFG RD ONLY EN Delete a file or directory ARGUMENTS name_full Name of the entry RETURNED VALUE 0 if the file is NOT removed 1 if the file is NOT removed NOTES WARNINGS 1 When a file is removed the space occupied by the file is freed and shall no longer be accessible 2 A directory can be removed only if it is an empty directory 3 The root directory cannot be removed 237 LIC FS API Reference Manual EXAMPLE 238 A 2 28 fs_rename int fs_rename const char const char File Called from LC FS API Reference Manual name full old name_full new Code enabled by fs_api c Application Rename a file or directory ARGUMENTS name_full old Old name of the entry name_full new New name of the entry RETURNED VALUE 0 if the entry is NOT renamed 1 if the entry is NOT renamed NOTES WARNINGS FS_CFG_API_EN and not FS_CFG_RD ONLY EN 1 name foll old and nam
148. NS void FS_DevDrvAdd FS_DEV API p dev api FS_ERR p err FS_ERR PG Init FS_CFG p fs cfg CPU_INTO8U FS_VersionGet void void FS WorkingDirGet CPU_CHAR path_ dir CPU_SIZE T len max FS_ERR p err void FS WorkingDirSet CPU_CHAR xpath dir FS_ERR p err FS_DevDrvAdd void FS DevDrvAdd FS_DEV_ API FS ERR p dev_drv p err 200 LC FS API Reference Manual A 1 1 FS _DevDrvAdd void FS DevDrvAdd FS DEV API p dev drv FS_ERR p err File Called from Code enabled by fs c Application N A Adds a device driver to the file system ARGUMENTS p_dev_drv Pointer to device driver see Section C 08 p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Device driver added FS ERR NULL PTR Argument p dev dru passed a NULL pointer FS_ERR_DEV_DRV_ALREADY ADDED Device driver already added FS_ERR_DEV_DRV_INVALID_NAME Device driver name invalid FG ERR DEV DRV_NO TBL POS AVAIL No device driver table position available RETURNED VALUE None 201 LC FS API Reference Manual NOTES WARNINGS 1 The NameGet device driver interface function MUST return a valid name E The name must be unique e g a name that is not returned by any other device driver E The name must NOT include any of the characters V or 7 E The name must contain fewer than FS_CFG MAX DEV_DRV_NAME LEN characters E The name
149. OPEN Device has changed Argument name_vol passed a NULL pointer Argument label passed a NULL pointer Device access error Directory is full space could not be allocated Device is full space could not be allocated Volume label is invalid Volume label is too long Volume is not mounted Volume is not open 327 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS The label on a FAT volume must be no longer than 11 characters each belonging to the set of valid short file name SFN characters Before it is committed to the volume the label will be converted to upper case and will be padded with spaces until it is an 11 character string 328 A 7 11 FSVol_Open LC FS API Reference Manual void FSVol_ Open CPU_CHAR name vol CPU_CHAR name_dev FS PARTITION MER partition_nbr FS_ERR p err File Called from Code enabled by fs vol c Application Open a volume ARGUMENTS N A name vol Volume name See Section 2 04 for information about device names name_dev Device name partition_nbr Partition number If 0 the default partition will be mounted p err Pointer to variable that will receive the return error code from this function See Note 2 FS_ERR_NONE FS_ERR_DEV_VOL_OPEN FS_ERR_INVALID SIG FS ERR NAME NULL FS ERR PARTITION INVALID NBR FS ERR PARTITION NOT FOUND FS ERR VOL ALREADY OPEN FS ERR VOL INVALID NAME FS ERR VOL NONE AVAIL Volume opened Vol
150. Open file if p file FS FILE 0 APP_TRACE_INFO Could not open file return x read from file err fs_fgetpos p_file amp pos Save file position if err 0 APP_TRACE_INFO Could not get file position return read some more from file err fs_fsetpos p file amp pos Set file to saved position if err 0 APP_TRACE INFO Could not set file position return e read some more from file FS_fclose p file When finished close file EN ay GE ay E 20 ay Listing 6 2 Example file position set get 90 POSIX API 6 3 3 CONFIGURING A FILE BUFFER In order to increase the efficiency of file reads and writes input output buffering capabilities are provided Without an assigned buffer reads and writes will be immediately performed within fs fread and fs_fwrite Once a buffer has been assigned data will always be read from or written to the buffer device access will only occur once the file position moves beyond the window represented by the buffer fs_setbuf and fs _setvbuf assign the buffer to a file The contents of the buffer can be flushed to the storage device with fs_fflush If a buffer is assigned to a file that was opened in update read write mode then a write may only be followed by a read if the buffer has been flushed by calling s_fflush or a file positioning function A read may be follow
151. PG FILE p file char fs_getcwd char path dir Ze size_t size struct fs tm fs_localtime_r const fs time t p ts struct fs tm p time 208 LC FS API Reference Manual int fs_mkdir const char name full fs time t fs_mktime struct fs _ tm p time FS DIR fs_opendir int fs_readdir const char FS_DIR struct fs dirent struct fs _ dirent name_ full p dir p dir entry pp result int fs_remove const char name_full int fs_rename const char name_full_ old const char name_full_new void fs_rewind FS_FILE p file int fs_setbuf FS_FILE p file fs_ size_t size int fs_setvbuf FS_FILE p file char p buf int mode fs_ size_t size 209 LC FS API Reference Manual A 2 1 fs_asctime_r char fs_asctime_r const struct fs_tm p time char str_time File Called from Code enabled by FS_CFG API EN fs_api c Application Converts date time to string in the form Sun Sep 16 01 03 52 1973 n 0 ARGUMENTS p_time Pointer to date time to format str_time String buffer that will receive date time string see Note RETURNED VALUE Pointer to str_time if NO errors Pointer to NULL otherwise NOTES WARNINGS str_time MUST be at least 26 characters long Buffer overruns MUST be prevented by caller 210 LC FS API Reference Manual A 2 2 fs_chdir int fs chdir const char path dir File Called from Code
152. PTR Argument path dir passed a NULL pointer FS_ERR_VOL NONE _ EXIST No volumes exist FS_ERR_WORKING DIR NONE AVAIL No working directories available FS_ERR_WORKING DIR _ INVALID Argument path dir passed an invalid directory RETURNED VALUE None NOTES WARNINGS None 206 A 2 POSIX API FUNCTIONS char LC FS API Reference Manual fs_asctime_r const struct fs tm p time char str_time int fs_chdir const char path_ dir void fs_clearerr FS_FILE p file int fs_closedir FS_DIR p dir char fs_ctime r const fs time t p ts char str time int fs_fclose FS_FILE p file int fs_feof FS_FILE p file int fs_ferror FS_FILE p file int fs_fflush FS_FILE p file int fs_fgetpos FS_FILE p file fs_fpos t p pos void fs_flockfile FS_FILE p file FS FILE fs_fopen const char const char name full str_mode 207 LC FS API Reference Manual Ze size_t fs_ fread void p dest fs_ size_t size fs_ size_t nitems PG FILE p file int fs_fseek FS_FILE p file long int offset int origin int fs_fsetpos FS_FILE p file fs fpos t p pos long int fe ftell FS_FILE p file int fs_ftruncate FS_FILE p file fs off t size int fs_ftrylockfile FS_FILE p file void fs_funlockfile FS FILE p file Ze size t fs_fwrite void p src Ze size_t size fs_ size_t nitems
153. PhyEraseBlk void FSDev_NOR_PhyEraseBlk CPU_CHAR name_ dev CPU_INT32U start CPU_INT32U size FS_ERR p err File Called from Code enabled by fs_dev_nor c Application N A Erase block of NOR device ARGUMENTS name dey Device name see Note start Start address of block relative to start of device size Size of block in octets p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Block erased successfully FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_DEV_INVALID Argument name dev specifies an invalid device FS_ERR_DEV_NOT_OPEN Device is not open FS_ERR_DEV_NOT_PRESENT Device is not present FS_ ERR DEV_INVALID LOW FMT Device needs to be low level formatted FS_ERR_DEV_IO Device I O error FS_ERR_DEV_ TIMEOUT Device timeout RETURNED VALUE None 361 LC FS API Reference Manual NOTES WARNINGS The device MUST be a NOR device e g nor 0 Care should be taken if this function is used while a file system exists on the device or if the device is low level formatted The erased block is NOT validated as being outside any existing file system or low level format information 362 LC FS API Reference Manual A 10 9 FSDev_NOR_PhyEraseChip void FSDev_NOR PhyEraseChip CPU_CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev_nor c Application N A Erase entire NOR device ARGUMENTS name_
154. R RETURNED VALUE None NOTES WARNINGS This function will be called EVERY time the device is closed 461 LUC FS Porting Manual C 10 3 FSDev_NOR_BSP_Rd_XX void FSDev_NAND BSP Rd 08 PG Org unit_nbr void p dest CPU_ADDR addr_src CPU_SIZE T cnt void FSDev_NAND BSP Bd 16 PG Org unit_nbr void p dest CPU_ADDR addr_src CPU_SIZE T cnt File Called from Code enabled by fs_dev_nor_bsp c NOR physical layer driver N A Read data from bus interface ARGUMENTS unit_nbr Unit number of NOR p_dest Pointer to destination memory buffer addr_srce Source address ent Number of words to read RETURNED VALUE None NOTES WARNINGS Data should be read from the bus in words sized to the data bus for any unit only the function with its access width will be called 462 LUC FS Porting Manual C 10 4 FSDev_NOR_BSP_RdWord_XX CPU_INTO8U FSDev_NAND BSP RdWord_08 PG Omg unit_nbr CPU_ADDR addr src CPU_INT16U FSDev_NAND BSP RdWord_16 FS Om unit_nbr CPU_ADDR addr src File Called from Code enabled by fs_dev_nor_bsp c NOR physical layer driver N A Read data from bus interface ARGUMENTS unit_nbr Unit number of NOR addr_srce Source address RETURNED VALUE Word read NOTES WARNINGS Data should be read from the bus in words sized to the data bus for any unit only the function with its access width will be called 463 C 10 5 FSDev_NOR_BSP_WrWord_XX LUC
155. R RESP REG_ERROR_STATUS error_status REG_INTERRUPT_STATUS interrupt_status return 479 LUC FS Porting Manual Read response Si Gi REG INTERRUPT_STATUS BIT_INTERRUPT_STATUS COMMAND COMPLETE if DEF_BIT_IS SET p cmd gt Flags FS_DEV_SD CARD CMD FLAG RESP DEF YES if DEF_BIT_IS SET p_cmd gt Flags FS DEV_SD CARD CMD FLAG RESP LONG DEF_YES p resp 3 REG RESPONSE _00 p resp 2 REG RESPONSE_01 p resp 1 REG RESPONSE_02 p_resp 0 REG RESPONSE _03 else p_resp 0 REG_RESPONSE_00 p err FS DEV_SD CARD ERR NONE Listing C 9 FSDev_SD_Card_BSP_CmdWaitEnd LC 9 1 Wait until command execution completes or an error occurs The wait loop or wait on semaphore SHOULD always have a timeout to avoid blocking the task in the case of an unforeseen hardware malfunction or a software flaw LC 9 2 Check if an error occurred The error status register is decoded to produce the actual error condition That is not necessary strictly but error counters that accumulate within the generic driver based upon returned error values may be useful while debugging a port LC 9 3 Read the response if any Note that the order in which a long response is stored in the buffer may oppose its storage in the controller s register or FIFO 480 LUC FS Porting Manual C 12 5 FSDev_SD_Card_BSP_CmdDataRd void FSDev_SD Card BSP CmdDataRd FS OI unit_nbr FS DEV GD CARD CMD
156. R_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout error RETURNED VALUE None NOTES WARNINGS None 455 LUC FS Porting Manual C 9 4 Wr void Wr FS _DEV_NOR_PHY DATA p phy data void p src CPU_INT32U start CPU_INT32U cnt FS_ERR p err File Called from Code enabled by NOR physical layer driver FSDev_NOR_PhyWrHandler N A Write to a NOR device from a buffer ARGUMENTS p phy data Pointer to NOR phy data p src Pointer to source buffer start Start address of write relative to start of device cnt Number of octets to write p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Octets written successfully FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout error RETURNED VALUE None NOTES WARNINGS None 456 LUC FS Porting Manual C 9 5 EraseBlk void EraseBlk FS_DEV_NOR_PHY DATA p phy data CPU_INT32U start CPU_INT32U size FS_ERR p err File Called from Code enabled by NOR physical layer driver FSDev_NOR_PhyEraseBlkHandler N A Erase block of NOR device ARGUMENTS p phy data Pointer to NOR phy data start Start address of block relative to start of device size Size of block in octets p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Block erased successfully FS_ERR_DEV_INVALID_OP Invalid operation for device
157. S API Reference Manual A 6 8 FSFile_LockAccept void FSFile LockAccept FS FILE p file FS ERR p err File Called from Code enabled by fs file c Application Ce ftrylockfile FS_CFG FILE LOCK EN Acquire task ownership of a file Gf available See fs_flockfile for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE File lock acquired FS_ERR_NULL PTR Argument p file passed a NULL pointer FS_ERR_INVALID TYPE Argument p file s type is invalid or unknown FS ERR FILE NOT OPEN File NOT open FS ERR FILE LOCKED File owned by another task RETURNED VALUE None NOTES WARNINGS None 299 A 6 9 FSFile LockGet void FSFile_ LockGet FS_ FILE p file LC FS API Reference Manual PG ERR p err File Called from Code enabled by fs file c Application FS_CFG FILE LOCK EN fs_flockfile Acquire task ownership of a file See fs_flockfile for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE File lock acquired FS ERR NULL PTR FS ERR INVALID TYPE FS ERR FILE NOT OPEN RETURNED VALUE None NOTES WARNINGS None Argument p_file passed a NULL pointer Argument p file s type is invalid or unknown File NOT open 300 LC FS API Reference Manual
158. SD MMC driver can be found in section 10 1 1 Driver Characterization on page 121 The SD MMC driver also provides interface functions to get low level card information and read the Card ID and Card Specific Data registers see section A 11 SD MMC Driver Functions on page 364 CPU_BOOLEAN App FS AddSD Card void FS_ERR erri FS_DevDrvAdd FS_DEV_API amp FSDev_SD Card 1 FS_ERR amp err if err FS_ERR_NONE amp amp err FS ERR_DEV_DRV ALREADY ADDED return DEF_FAIL EST S FSDev_Open CPU_CHAR sdcard 0 a void 0 b PS ERR amp err switch err case FS_ERR_NONE break case FS_ERR_DEV case FS_ERR_DEV_IO case FS_ERR_DEV_TIMEOUT case PS ERR DEV MOT PRESENT return DEF_FAIL default return DEF_FAIL A7 NEN SA FSVol_Open CPU_CHAR sdcard 0 a CPU_CHAR sdcard 0 b FS_PARTITION NBR 0 c FS_ERR amp err 178 SD MMC Drivers switch err case FS_ERR_NONE APP_TRACE_DBG Opened volume mounted r n break case FS_ERR_DEV case FS_ERR_DEV_IO case PS ERR DE TIMEOUT case PS ERR DEV HOT PRESENT case FS_ERR PARTITION NOT FOUND APP_TRACE_DBG opened device unmounted r n return DEF FAIL default APP_TRACE_DBG opening volume failed w err d r n r n err return DEF_FAIL return DEF OK 117 101 L17 1 2 L17 1 Listing
159. SS MODE CREATE FS FILE ACCESS MODE TRUNC a or ab or a b FS_ FILE ACCESS MODE RD FS_FILE ACCESS MODE WR FS FILE ACCESS MODE CREATE PG FILE ACCESS MODE APPEND Table A 1 fs_fopen mode strings and mode equivalents 304 LC FS API Reference Manual A 6 12 FSFile_PosGet FS FILE SIZE FSFile PosGet FS FILE p file PG ERR p err File Called from Code enabled by fs file c Application N A fs_ftell fs_fgetpos Set file position indicator See fs_ftell for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will the receive return error code from the function FS_ERR_NONE File position gotten successfully FS_ERR_NULL PTR Argument p file passed a NULL pointer FS_ERR_INVALID TYPE Argument p file s type is invalid or unknown PG ERR FILE NOT OPEN File NOT open FS_ERR_FILE INVALID POS Invalid file position RETURNED VALUE The current file position if no errors see Note 0 otherwise NOTES WARNINGS The file position returned is the number of bytes from the beginning of the file up to the current file position 305 LC FS API Reference Manual A 6 13 FSFile_PosSet void FSFile PosSet FS FILE p file FS FILE OFFSET offset FS_FLAGS origin FS_ERR p err File Called from Code enabled by fs file c Application N A fs_fseek fs_fsetpos Get file position indicator See fs_fseek for more inf
160. Set transfer mode timings ARGUMENTS unit_nbr Unit number of IDE CF device mode type Transfer mode type FS DEV_IDE MODE TYPE PIO PIO mode FS DEV_IDE MODE TYPE DMA Multiword DMA mode FS DEV_IDE MODE TYPE UDMA Ultra DMA mode mode Transfer mode between 0 and maximum mode supported for mode type by device Cinclusive RETURNED VALUE Mode selected should be between 0 and mode inclusive NOTES WARNINGS If DMA is supported two transfer modes will be setup The first will be a PIO mode the second will be a Multiword DMA or Ultra DMA mode Thereafter the host controller or bus interface must be capable of both PIO and DMA transfers 424 LUC FS Porting Manual C 5 15 FSDev_IDE_BSP_Dly400_ns CPU_INTO8U_ FSDev_IDE_BSP_Dly400_ns FS_QTY unit_nbr File Called from Code enabled by fs_dev_ide_bsp c various N A Delay 400 ns ARGUMENTS unit_nbr Unit number of IDE CF device RETURNED VALUE None NOTES WARNINGS None 425 LUC FS Porting Manual C 6 NAND Flash Physical Layer Driver The NAND driver is divided into three layers The topmost layer the generic driver requires an intermediate physical layer driver to effect flash operations like erasing blocks and writing octets depending on the memory type and organization The physical layer driver is already available for different architectures and includes one code header file pair named according to the following rubric
161. T PRESENT FS ERR DEV TIMEOUT FS ERR DEV UNIT NONE AVAIL FS ERR DEV UNIT ALREADY EXIST FS ERR DEV UNKNOWN FS ERR DEV VOL OPEN LIC FS Error Codes Mode specified invalid Device already open Device has changed Device access error Device already open Device has changed Device is fixed cannot be closed Device is full no space could be allocated Invalid device Invalid dev cfg Invalid ECC I O control invalid Low format invalid Invalid low level device parameters Invalid mark Invalid device name Invalid operation Invalid device sec nbr Invalid device sec size Invalid device size Invalid device unit nbr Device I O error No device avail Device not open Device not present Device timeout No unit avail Unit already exists Unknown Vol open on dev 377 FS ERR DEV Du ALREADY ADDED FS ERR DEV DRV_ INVALID NAME FS ERR DEV DRV_NO TBL POS AVAIL FS ERR DIR ALREADY OPEN FS ERR DIR DIS FS ERR DIR FULL FS ERR DIR NONE AVAIL FS ERR DIR NOT OPEN B 7 ECC ERROR CODES FS _ERR_ECC_CORRECTABLE FS _ERR_ECC_UNCORRECTABLE B 8 ENTRY ERROR CODES FS ERR ENTRIES SAME FS ERR ENTRIES TYPE DIFF FS ERR ENTRIES VOLS DIFF FS ERR ENTRY CORRUPT FS ERR ENTRY EXISTS FS ERR ENTRY INVALID FS ERR ENTRY NOT DIR FS ERR ENTRY NOT EMPTY FS ERR ENTRY NOT FILE FS ERR ENTRY NOT FOUND FS ERR ENTRY PARENT NOT FOUND FS ERR ENTRY PARENT NOT DIR FS ERR ENTRY RD ONLY FS ERR ENTRY ROOT D
162. TURNED VALUE None NOTES WARNINGS None C 13 SD MMC SPI mode BSP SD MMC card can also be accessed through an SPI bus also described as the one wire mode Please refer to section C 14 SPI BSP on page 494 for the details on how to implement the software port for your SPI bus 493 LUC FS Porting Manual C 14 SPI BSP Among the most common and simplest serial interfaces supported by built in CPU peripherals is Serial Peripheral Interface SPI Four hardware signals connect a defined master or host to each slave or device a slave select a clock a slave input and a slave output Three of these all except the slave select may be shared among all slaves though hosts often have several SPI controllers to simplify integration and allow simultaneous access to multiple slaves Serial flash serial EEPROM and SD MMC cards are among the many devices which use SPI Signal Description SSEL CS Slave select SCLK Clock SO MISO Slave output master input SI MOSI Slave input master output Table C 8 SPI signals No specification exists for SPI a condition which invites technological divergence So though the simplicity of the interface limits variations between implementations the required transfer unit length shift direction clock frequency and clock polarity and phase do vary from device to device Take as an example Figure C 6 which gives the bit form of a basic command response exchange on a
163. U FS_ERR p err File Called from Code enabled by fs_dev_nor c Application N A Write to a NOR device from a buffer ARGUMENTS name_dev Device name see Note p sre Pointer to source buffer start Start address of write relative to start of device cnt Number of octets to write p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Octets written successfully FS ERR NAME NULL FS ERR NULL PTR FS ERR DEV INVALID FS ERR DEV MOT OPEN FS ERR DEV MOT PRESENT FS ERR DEV INVALID LOW FMT FS ERR DEV IO FS ERR DEV TIMEOUT Argument name_dev passed a NULL pointer Argument p_ sre passed a NULL pointer Argument name_dev specifies an invalid device Device is not open Device is not present Device needs to be low level formatted Device I O error Device timeout 359 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS The device MUST be a NOR device e g nor 0 Care should be taken if this function is used while a file system exists on the device or if the device is low level formatted The octet location s modified are NOT validated as being outside any existing file system or low level format information During a program operation only 1 bits can be changed a 0 bit cannot be changed to a 1 The application MUST know that the octets being programmed have not already been programmed 360 LC FS API Reference Manual A 10 8 FSDev_NOR_
164. UC FS Porting Manual Code enabled by fs_dev_ lt dev_name gt _bsp c Device driver Enable disable device chip select ARGUMENTS unit_nbr Unit number of device RETURNED VALUE None NOTES WARNINGS N A The chip select is typically active low To enable the device the chip select pin should be cleared to disable the device the chip select pin should be set 505 LUC FS Porting Manual C 14 7 SetCikFreq void FSDev_BSP SPI SetClkFreq FS QTY unit_nbr CPU_INT32U freq File Called from Code enabled by fs_dev_ lt dev_name gt _bsp c Device driver N A Set SPI clock frequency ARGUMENTS unit_nbr Unit number of device RETURNED VALUE None NOTES WARNINGS The effective clock frequency MUST be no more than freq If the frequency cannot be configured equal to freq it should be configured less than freq 506 Appendix UC FS Types and Structures Your application may need to access or populate the types and structures described in this appendix Each of the user accessible structures is presented in alphabetical order The following information is provided for each entry E A brief description of the type or structure E The definition of the type or structure E The filename of the source code E A description of the meaning of the type or the members of the structure E Specific notes and warnings regarding use of the type 507 LIC FS Types and Structures D
165. _ QTY FSDev_GetDevCnt void FS_ QTY FSDev_GetDevCntMax void void FSDev_Open CPU_CHAR name_dev void p dev Go FS_ERR p err 247 FS PARTITION NBR LC FS API Reference Manual FSDev_PartitionAdd CPU_CHAR name_dev FS_SEC_OTY partition_size FS_ERR p err void FSDev_PartitionFind CPU_CHAR name_dev FS PARTITION NBR FS PARTITION ENTRY partition_nbr p partition entry FS_ERR p err void FSDev_PartitionInit CPU_CHAR name_ dev FS_SEC_OTY partition_size FS_ERR p err void FSDev_Query CPU_CHAR name_dev FS_DEV_INFO p info FS_ERR p err void FSDev_Rd CPU_CHAR name_dev void p dest FS_SEC_NBR start FS SEC QTY cnt FS_ERR p err CPU_BOOLEAN FSDev_Refresh CPU_CHAR name_dev FS_ERR p err void FSDev_Wr CPU_CHAR name_dev void p src FS _SEC_NBR start FS_SEC_OQTY cnt FS_ERR p err 248 LC FS API Reference Manual A 3 1 FSDev_Close void FSDev_Close CPU_CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev c Application N A Close and free a device ARGUMENTS name dev Device name p err Pointer to variable that will receive return error code from this function FS_ERR_NONE Device removed successfully FS_ERR_DEV_NOT_OPEN Device is not open FS ERR NAME NULL Argument name_dev passed a NULL pointer RETURNED VALUE None NOTES WARNINGS None 249 LC FS API Reference Manual A 3 2 FSDev_G
166. _IDE_BSP_DMA_Start Write command Wait for data request FSDev_IDE_BSP_CmdWr Read or write data End DMA FSDev_IDE_BSP_DataRd Wr FSDev_IDE_BSP_DMA_End More data Check for error Figure C 2 Command Execution 409 LUC FS Porting Manual C 5 1 FSDev_IDE_BSP_Open CPU_BOOLEAN FSDev_IDE BSP Open FS QTY unit _nbr File Called from Code enabled by fs_dev_ide_bsp c FSDev_IDE_Refresh N A Initialize IDE CF hardware ARGUMENTS unit_nbr Unit number of IDE CF device RETURNED VALUE DEF OR if interface was opened DEF_FAIL otherwise NOTES WARNINGS This function will be called every time the IDE CF device is opened 410 LUC FS Porting Manual C 5 2 FSDev_IDE_BSP_Close void FSDev_IDE BSP Close FS QTY unit_nbr File Called from Code enabled by fs_dev_ide_bsp c FSDev_IDE_Close N A Uninitialize IDE CF hardware ARGUMENTS unit_nbr Unit number of IDE CF device RETURNED VALUE None NOTES WARNINGS This function will be called every time the IDE CF device is closed 411 LUC FS Porting Manual C 5 3 FSDev_IDE_BSP_Lock FSDev_IDE_BSP_Unlock void FSDev_IDE BSP Lock FS QTY unit_nbr void FSDev_IDE BSP Unlock FS_QTY unit_nbr File Called from Code enabled by fs_dev_ide_bsp c various N A Acquire release IDE CF bus lock ARGUMENTS unit_nbr Unit number of IDE CF device RETURNED VALUE None NOTES WAR
167. _err h for both their numerical value and usage B 1 SYSTEM ERROR CODES FS_ERR_NONE FS ERR INVALID ARG FS ERR INVALID CFG FS ERR INVALID CHKSUM FS ERR INVALID LEN FS ERR INVALID TIME FS ERR INVALID TIMESTAMP FS ERR INVALID TYPE FS ERR MEM ALLOC FS ERR NULL ARG FS ERR NULL PTR FS ERR OS FS ERR OVF FS ERR EOF FS ERR WORKING DIR NONE AVAIL FS ERR WORKING DIR INVALID B 2 BUFFER ERROR CODES FS ERR BUF_NONE AVAIL No error Invalid argument Invalid configuration Invalid checksum Invalid length Invalid date time Invalid timestamp Invalid object type Mem could not be alloc d Arg s passed NULL val s Ptr arg s passed NULL ptr s OS err Value too large to be stored in type EOF reached No working dir avail Working dir invalid No buffer available 376 B 3 CACHE ERROR CODES FS ERR CACHE INVALID MODE FS ERR CACHE INVALID SEC TYPE FS ERR CACHE TOO SMALL B 4 DEVICE ERROR CODES FS ERR DEV FS ERR DEV ALREADY OPEN FS ERR DEV CHNGD FS ERR DEV FIXED FS ERR DEV FULL FS ERR DEV INVALID FS ERR DEV INVALID CFG FS ERR DEV INVALID ECC FS ERR DEV INVALID IO CTRL FS ERR DEV INVALID LOW FMT FS ERR DEV INVALID LOW PARAMS FS ERR DEV INVALID MARK FS ERR DEV INVALID NAME FS ERR DEV INVALID OP FS ERR DEV INVALID SEC NBR FS ERR DEV INVALID SEC SIZE FS ERR DEV INVALID SIZE FS ERR DEV INVALID UNIT NBR FS ERR DEV IO FS ERR DEV NONE AVAIL FS ERR DEV NOT OPEN FS ERR DEV NO
168. _fat_journal c h FS_FAT_JournalClose fs_fat_journal c h FS_FAT_JournalStart fs_fat_journal c h FS_FAT JournalEnd fs_fat_journal c h Table E 8 Journaling function exclusion These functions are NOT included if FS_FAT_CFG_JOURNAL_EN is DEF_DISABLED FS Pat CFG VOL_CHK EN FS FAT CFG VOL CHK EN selects whether volume check is supported When DEF_ENABLED volume check is supported when DEF_DISABLED the function FS FAT VolChk will not be available FS Pat CFG _VOL_CHK MAX LEVELS FG FAT CFG VOL CHK MAX LEVELS specifies the maximum number of directory levels that will be checked by the volume check function Each level requires an additional 12 bytes stack space E 8 SD MMC SPI CONFIGURATION FS_DEV_SD_SPI_CFG_CRC_EN Data blocks received from the card are accompanied by CRCs as are the blocks transmitted to the card FS _DEV_SD SPI_CFG_CRC_EN enables CRC validation by the card as well as the generation and checking of CRCs If DEF_ENABLED CRC generation and checking will be performed 533 UC FS Configuration E 9 TRACE CONFIGURATION The file system debug trace is enabled by define ing FS_TRACE LEVEL in your application s app_cfg h define FS TRACE LEVEL TRACE LEVEL DG The valid trace levels are described in the table below A trace functions should also be defined define FS TRACE printf This should be a printf type function that redirects the trace output to some accessible terminal for example the t
169. _hamming h ecc_hamming c ecc_bch_ 8bit h ecc_bch_ 8bit c ecc_bch 4bit h ecc_bch 4bit c ecc_bch h ecc_bch c ecc h Micrium This directory contains all software components and projects provided by Micrium Software This sub directory contains all the software components and projects 40 Directories and Files uC CRC This is the main pC CRC directory Cfg Template This directory contains a configuration template file crc_cfg h that must be copied to the application directory to configure the pC CRC module based on application requirements cerc_cfg h determines whether to enable assembly language optimization assuming there is an assembly language file for the processor and a few other defines lt architecture gt The name of the CPU architecture that uC CRC was ported to The lt and gt are not part of the actual name lt compiler gt The name of the compiler or compiler manufacturer used to build code for the pC CRC port The lt and gt are not part of the actual name ecc_bch 4bit_a asm contains the assembly language functions to optimize the calculation speed of 4 bit correction BCH Bos Ray Chaudhuri Hocquenghem code ecc_bch 8bit_a asm contains the assembly language functions to optimize the calculation speed of 8 bit correction BCH Bos Ray Chaudhuri Hocquenghem code ecc_hamming_a asm contains the assembly language functions to optimize the calculation speed
170. a 1 The application MUST know that the page being programmed have not already been programmed 347 LC FS API Reference Manual A 9 6 FSDev_NAND PhyEraseBIik void FSDev_NAND PhyEraseBlk CPU_CHAR name_dev CPU_INT32U blk nbr phy FS_ERR p err File Called from Code enabled by fs_dev_nand c Application N A Erase block of NAND device ARGUMENTS name_dev Device name see Note blk_nbr_phy Block to erase p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Block erased successfully FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_DEV_INVALID Argument name_dev specifies an invalid device PG ERR DEV_NOT_OPEN Device is not open PG ERR DEV MO PRESENT Device is not present FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NAND device e g nand 0 348 LC FS API Reference Manual Care should be taken if this function is used while a file system exists on the device or if the device is low level formatted The erased block is NOT verified as being outside any existing file system or low level format information 349 A 10 NOR DRIVER FUNCTIONS LC FS API Reference Manual void FSDev_NOR_LowFmt CPU_CHAR name dev FS_ERR p err void FSDev_NOR_LowMount CPU_CHAR name dev FS_ERR p err void FSDev_NOR_LowUnmount CPU_
171. a FS_FAT SYS _CFG 318 LC FS API Reference Manual A 7 3 FSVol_GetDfitVoIName void FSVol_GetDfltVolName CPU_CHAR name vol File Called from Code enabled by fs_vol c Application N A Get name of the default volume ARGUMENTS name vol String buffer that will receive the volume name see Note 2 RETURNED VALUE None NOTES WARNINGS 1 name vol MUST point to a character array of FS_CFG MAX VOL NAME LEN characters 2 If the volume does not exist name_vol will receive an empty string 319 LC FS API Reference Manual A 7 4 FSVol_GetVolCnt FS OI FSVol_GetVolCnt void File Called from Code enabled by fs _vol c Application N A Get the number of open volumes ARGUMENTS None RETURNED VALUE Number of volumes currently open NOTES WARNINGS None 320 LC FS API Reference Manual A 7 5 FSVol_GetVolCntMax FS OI FSVol_GetVolCntMax void File Called from Code enabled by fs _vol c Application N A Get the maximum possible number of open volumes ARGUMENTS None RETURNED VALUE The maximum number of open volumes NOTES WARNINGS None 321 LC FS API Reference Manual A 7 6 FSVol_GetVolIName void FSVol_ GetVolName FS_QTY vol_nbr CPU_CHAR name vol File Called from Code enabled by fs_vol c Application N A Get name of the nth open volume n should be between 0 and the return value of FSVol_GetNbrVols inclusive ARGUMENTS vol n
172. aaeeeeeneeaes 259 FSDev Qu eryl ssccccccessscccvcvvesc cctveesectctteedveccciveveenes ENEE EENS ENEE 261 FSDe V Hegle eedere eege deeg 262 FSDev Rethesthy in e save sted ee EE EEEEEEE 264 FSD VE WI ee EE ee ie eis 266 Directory ACCESS FUNCTIONS EEN 267 Fab Close csctececececctsesnsseccthscccevetves eege aaraa aaaeaii iaa iaaa aiaiai 268 FSDir ISOPe n a dace sess chettecce acct eeu EEN eege Seege dee 269 FSDirOpen raana aiana aaa Eege 270 FSD Rd aaa are iv ts ee SaNa estas ATA AA ASAF 272 Entry Access Functions cccccesseeeceeseseeeeeesessneeeeesnssneeeeeensneeseeeessnes 273 FSEMA ANHDSG iania A aE EEE L AA KAAR AA EA 274 FSEntry Copa deeg ege 276 FSEntry Greate g ss cts deste oc eesti A egene dedi DEEN Ed 278 FSEntry Del reunie dee ENEE d 280 FSEntry Query 2 Segel ed deed Aaa dell ied deet 282 FSEntry_ Rename sccececcceseeceeeeeeeeeeeeeeneeeeeseeeessaeseneeeeeseeeeeaneeeeesenees 284 A 5 7 A 6 A 6 1 A 6 2 A 6 3 A 6 4 A 6 5 A 6 6 A 6 7 A 6 8 A 6 9 A 6 10 A 6 11 A 6 12 A 6 13 A 6 14 A 6 15 A 6 16 A 6 17 A 7 A 7 1 A 7 2 A 7 3 A 7 4 A 7 5 A 7 6 A 7 7 A 7 8 A 7 9 A 7 10 A 7 11 A 7 12 A 7 13 A 7 14 A 8 1 A 8 2 A 8 3 FSEntryTimeSet ET 286 File FUNGTIONS sie 224s ce vend Seege EEN dee EEN ege 288 FSFileButASSignn si exces sccid cdeetecceedesesecces cece ceil ceeedaced cdenectdeeteedeccees 290 FSFile ButFlush 2 iesst Seegen Zeen gege d dei dg d e eg 292 FSFile GloSe
173. access error Entry name specified invalid or volume could not be found Entry name is too long Volume not opened Volume not mounted Buffer not available Or entry error see section B 8 Entry Error Codes on page 378 RETURNED VALUE Pointer to a directory if NO errors Pointer to NULL otherwise 270 LC FS API Reference Manual NOTES WARNINGS None 271 A 4 4 FSDir Rd LC FS API Reference Manual void FSDir Rd FS DIR p dir FS DIR ENTRY p dir entry FS_ERR p err File Called from Code enabled by fs dir c Application FS_CFG DIR EN fs readdir_r Read a directory entry from a directory See fs_readdir_r for more information ARGUMENTS p dir Pointer to a directory p dir entry Pointer to variable that will receive directory entry information p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE FS ERR NULL PTR FS ERR INVALID TYPE FS_ERR DIR DIS FS ERR DIR NOT OPEN FS_ERR EOF FS_ERR DEV FS ERR BUF NONE AVAIL RETURNED VALUE None NOTES WARNINGS None Directory read successfully Argument p dir p dir entry passed a NULL pointer Argument p dir s TYPE is invalid or unknown Directory module disabled Directory NOT open End of directory reached Device access error Buffer not available 272 LC FS API Reference Manual A 5 ENTRY ACCESS FUNCTIONS void FSEntry AttribSet CPU_CHAR name
174. ache API to use OR b NULL if default cache API should e used p cache data Pointer to cache data size Size in bytes of cache buffer pct mgmt Percent of cache buffer dedicated to management sectors pet_dir Percent of cache buffer dedicated to directory sectors mode Cache mode FS VOL CACHE MODE WR THROUGH FS VOL CACHE MODE WR BACK FS VOL CACHE MODE RD 336 LC FS API Reference Manual p err Pointer to variable that will receive return error code from this function FS_ERR_NONE Cache created FS_ERR_NAME NULL name vol passed a NULL pointer PG ERR VOL NOT OPEN Volume not open PG ERR NULL PTR p cache data passed a NULL pointer FS ERR CACHE INVALID MODE Mode specified invalid FS ERR CACHE INVALID SEC TYPE Sector type sepecified invalid FS_ ERR CACHE TOO SMALL Size specified too small for cache RETURNED VALUE None NOTES WARNINGS None 337 LC FS API Reference Manual A 8 2 FSVol_Cachelnvalidate void FSVol_CacheInvalidate CPU_CHAR name_vol FS_ERR p err File Called from Code enabled by fs_vol c Application FS_CFG_CACHE EN Invalidate cache on a volume ARGUMENTS name_vol Volume name p err Pointer to variable that will receive return error code from this function FS_ERR_NONE Cache created FS_ERR_NAME_NULL name vol passed a NULL pointer FS_ERR_DEV_CHNGD Device has changed FS ERR VOL NO CACHE No cache assigned to volume FS_ERR_VOL_NOT_OPEN Volume not op
175. act equivalents to POSIX API functions the primary difference is the advantage of valuable return error codes to the application File Module Function void FSFile_LockGet FS_FILE p file FS ERR p_err void FSFile LockAccept FS_FILE sp file PS ERR p_err void FSFile_LockSet FS_FILE p file PS ERR p err POSIX API Equivalent void fs_flockfile FS_FILE file int fs_ftrylockfile FS_FILE file void fs funlockfile FS_FILE file For more information about and an example of using file locking see section 6 3 5 Atomic File Operations Using File Lock on page 93 102 Files 7 2 ENTRY ACCESS FUNCTIONS The entry access functions provide an API for performing single operations on file system entries files and directories such as copying renaming or deleting Each of these operations is atomic consequently in the absence of device access errors either the operation will have completed or no change to the storage device will have been made upon function return One of these functions FSEntry_Query obtains information about an entry including the attributes date time stamp and file size Two functions set entry properties FSEntry AttribSet and FSEntry_TimeSet which set a file s attributes and date time stamp A new file entry can be created with FSEntry Create or an existing entry deleted copied or renamed with FSEntry_Del FSEntry Copy or FSEntry_Rename
176. ailable only if FS SHELL CFG MKFS EN is DEF ENABLED and FS CFG RD ONLY EN is DEF DISABLED NOTES WARNINGS None 549 F 3 9 fs mount Mount volume USAGES fs_ mount dev vol ARGUMENTS dev Device to mount vol Name which will be given to volume OUTPUT None REQUIRED CONFIGURATION Available only if FS_SHELL CFG MOUNT EN is DEF ENABLED NOTES WARNINGS None Shell Commands 550 Shell Commands F 3 10 fs mv Move files USAGES fs mv source_entry dest_entry fs mv source entry dest dir ARGUMENTS source_entry Source entry path dest_entry Destination entry path dest_dir Destination directory path OUTPUT None REQUIRED CONFIGURATION Available only if FS_SHELL CFG WEN is DEF ENABLED and FS CFG RD ONLY EN is DEF DISABLED NOTES WARNINGS In the first form of this command the second argument must not be an existing directory The file source_entry will be renamed dest_entry In the second form of this command the second argument must be an existing directory source entry will be renamed to an entry with name formed by concatenating dest dir a path separator character and the final component of source_entry In both forms if source_entry is a directory the entire directory tree rooted at source _entry will be copied and then deleted Additionally both source_entry and dest_entry or dest_dir must specify locations on the same volume 551 Shell Commands F 3 11 fs
177. alid device FS_ERR_DEV_NOT_OPEN Device is not open FS_ERR_DEV_NOT_PRESENT Device is not present FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NAND device e g nand 0 Low level unmounting clears software knowledge of the on disk structures forcing the device to again be low level mounted or formatted prior to further use 343 LC FS API Reference Manual A 9 4 FSDev_NAND PhyRdSec void FSDev_NAND PhyRdSec CPU_CHAR name_dev void p dest void p spare PG SEC NBR sec_nbr phy FS_ERR p err File Called from Code enabled by fs_dev_nand c Application N A Read sector from a NAND device and store data in buffer ARGUMENTS name dev Device name see Note p_dest Pointer to destination buffer p spare Pointer to buffer that will receive spare data sec_nbr_ phy Sector to read p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Octets read successfully FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_NULL PTR Argument p dest passed a NULL pointer FS_ERR_DEV_INVALID Argument name_dev specifies an invalid device FS_ERR_DEV NOT OPEN Device is not open PG ERR DEV MO PRESENT Device is not present FS_ERR_DEV_IO Device I O error FS_ERR_DEV_ TIMEOUT Device timeout 344 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS The
178. all unwritten data is written to the file 2 Ifthe most recent operation is input read all buffered data is cleared 218 LC FS API Reference Manual A 2 10 fs_fgetpos int fs _fgetpos FS FILE p file fs fpos t p pos File Called from Code enabled by fs_api c Application FS_CFG API_EN Get file position indicator ARGUMENTS p_file Pointer to a file D Dos Pointer to variable that will receive the file position indicator RETURNED VALUE 0 if no error occurs Non zero value otherwise NOTES WARNINGS 1 The return value should be tested against 0 rtn fs fgetpos p file amp pos if rtn 0 No error occurred else Handle error 2 The value placed in pos should be passed to FS_fsetpos to reposition the file to its position at the time when this function was called 219 LC FS API Reference Manual A 2 11 fs_flockfile void fs flockfile FS_FILE p file File Called from Code enabled by fs_api c Application FS_CFG AGT EN and FS_CFG FILE LOCK EN Acquire task ownership of a file ARGUMENTS p file Pointer to a file RETURNED VALUE None NOTES WARNINGS A lock count is associated with each file 1 The file is unlocked when the lock count is zero 2 If the lock count is positive a task owns the file 3 When fs_flockfile is called if a the lock count is zero OR b the lock count is positive and the caller owns the file the l
179. amp O cmd amp cre Template D CH Dev B Doc O Examples Fat os Source uc S uc shell a crc Template Source Figure F 2 Directory Structure Micrium Software uC FS Cmd fs_shell contain the shell commands for pC FS Micrium Software uC FS Cmd Template Cfg fs_shell_cfg h is the template configuration file for the uC FS shell commands This file should be copied to your application directory and modified Micrium Software uC Shell This directory contains pC Shell which is used to process the commands See the pC Shell user manual for more information 536 Shell Commands F 2 USING THE SHELL COMMANDS To use shell commands four files in addition to the generic file system files must be included in the build E fs shell c E LG shell h E shell c located in Micrium Software uC Shell1 Source E shell h located in Micrium Software uC Shell1 Source The file fs_shell h and shell h must also be included in any application or header files initialize pC Shell or handle shell commands The shell command configuration file fs_shell_cfg h should be copied to your application directory and modified The following directories must be on the project include path E Micrium Software uC FS Cmd E Micrium Software uC Shell Source uC Shell with the uC FS shell commands is initialized in Listing F 1 The file system initialization FS_Init function should have previously been call
180. and name_full_new is a file it will be removed If name_full_old specifies a directory a name_full_new must NOT specify a file b if excl is DEE MO and name_full_new is a directory name_full_new MUST be empty if so it will be removed If excl is DEF_NO name_full_new must not exist The root directory may NOT be renamed 285 LC FS API Reference Manual A 5 7 FSEntry_TimeSet void FSEntry TimeSet CPU_CHAR name_full FS DATE TIME p time CPU_INTO8U flag FS_ERR p err File Called from Code enabled by fs_entry c Application not FS_CFG_RD_ONLY_EN Set a file or directory s date time ARGUMENTS name full Name of the entry See section 4 3 uC FS File and Directory Names and Paths on page 62 p_time Pointer to date time flag Flag to indicate which Date Time should be set FS_ DATE TIME CREATE Entry Created Date Time will be set FS_ DATE TIME MODIFY Entry Modified Date Time will be set FS DATE TIME ACCESS Entry Accessed Date will be set FS_ DATE TIME ALL All the above will be set p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Entry date time set successfully FS_ERR_NULL PTR Argument name _full or p time passed a NULL pointer FS_ERR FILE INVALID DATE TIME Date time specified invalid FS_ERR_NAME INVALID Entry name specified invalid OR volume could not be found FS_ERR_NAME PATH TOO LONG Entry name specified too long FS_ERR_VOL_NOT_OPEN Volume
181. andard NAND From perspective of CPU 147 14 3 3 NAND BSP OVERVIEW NAND Flash Driver A BSP is required so that a physical layer driver for a parallel flash will work on a particular system The functions shown in the table below must be implemented Pleaser refer to section C 7 NAND Flash BSP on page 440 for the details about implementing your own BSP Function Description FSDev_NAND BSP Open Open initialize NAND bus interface FSDev_NAND_BSP_Close Close uninitialize NAND bus interface FSDev_NAND_BSP_ChipSelEn Enable NAND chip select FSDev_NAND_BSP_ChipSecDis Disable NAND chip select FSDev_NAND BSP RdData Read data from NAND FSDev_NAND BSP WrAddr Write address to NAND FSDev_NAND BSP WrCmd Write command to NAND FSDev_NAND_BSP_WrData Write data to NAND FSDev_NAND_BSP_WaitWhileBusy Wait while NAND is busy Table 14 3 NAND BSP functions The Open Close functions are called upon open close these calls are always matched The remaining functions RdData WrAddr WrCmd WrData read data from or write data to the NAND 14 4 PHYSICAL LAYER DRIVERS The physical layer drivers distributed with the NAND driver see the table below support a wide variety of flash devices from major vendors 148 NAND Flash Driver Driver API Files Description FSDev_NAND_0512x08 fs_dev_nand_0512x08 Supports 51
182. are components and projects provided by Micrium Software This sub directory contains all the software components and projects 50 Directories and Files uc FS This is the main pC FS directory Examples This is where you will find the device driver BSP example files Dev lt memory type gt This is where you will find the examples BSP for one memory type The lt and gt are not part of the actual name The memory types supported by uC FS are the following IDE NAND NOR SD CARD SD SPI lt manufacturer gt The name of the manufacturer of the evaluation board The lt and gt are not part of the actual name 3 12 pC FS OS ABSTRACTION LAYER This directory contains the RTOS abstraction layer which allows the use of uC FS with nearly any commercial of in house RTOS or without any RTOS at all The abstraction layer for the selected RTOS is placed in a sub directory under OS as follows Micrium Software uC FS VOS lt rtos_name gt fs_os c fs_os h Micrium This directory contains all software components and projects provided by Micrium Software This sub directory contains all the software components and projects uC FS This is the main pC FS directory 51 Directories and Files os This is the main OS directory lt rtos_name gt This is the directory that contains the files to perform RTOS abstraction Note that files for the selected RTOS abstraction layer must
183. as few blocks as possible in order of logical sector A defragmented file system should have near optimal access speeds in a read only environment 356 A 10 6 FSDev_NOR_PhyRd LC FS API Reference Manual void FSDev_NOR PhyRd CPU_CHAR name_dev void p dest CPU_INT32U start CPU_INT32U cnt FS ERR p err File Called from Code enabled by fs_dev_nor c Application N A Read from a NOR device and store data in buffer ARGUMENTS name dev Device name see Note p dest Pointer to destination buffer start Start address of read relative to start of device cnt Number of octets to read p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Octets read successfully FS ERR NAME NULL FS ERR NULL PTR FS ERR DEV INVALID FS ERR DEV MOT OPEN FS ERR DEV MOT PRESENT FS ERR DEV INVALID LOW FMT FS ERR DEV IO FS ERR DEV TIMEOUT Argument name_dev passed a NULL pointer Argument p_dest passed a NULL pointer Argument name_dev specifies an invalid device Device is not open Device is not present Device needs to be low level formatted Device I O error Device timeout 357 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS The device MUST be a NOR device e g nor 0 358 A 10 7 FSDev_NOR_PhyWr LC FS API Reference Manual void FSDev_NOR PhyWr CPU_CHAR name_dev void p src CPU_INT32U start CPU_INT32
184. assigned the block count and block size of the device respectively 2 RegionNbr specifies the block region that will be used AddrRegionStart MUST be assigned the start address of this block region 3 DataPtr may store a pointer to any driver specific data 4 UnitNbr is the unit number of the NOR device 5 MaxClkFreg specifies the maximum SPI clock frequency 6 BusWIdth BusWidthMax and PhyDevCnt specify the bus configuration AddrBase specifies the base address of the NOR flash memory 453 LUC FS Porting Manual C 9 2 Close void Close FS DEV HOR PHY DATA p phy data File Called from Code enabled by NOR physical layer driver FSDev_NOR_Close N A Close uninitialize a NOR device instance ARGUMENTS p phy data Pointer to NOR phy data RETURNED VALUE None NOTES WARNINGS None 454 LUC FS Porting Manual C 9 3 Bai void Rd FS _DEV_NOR_PHY DATA p phy data void p dest CPU_INT32U start CPU_INT32U cnt FS_ERR p err File Called from Code enabled by NOR physical layer driver FSDev_NOR_PhyRdHandler N A Read from a NOR device and store data in buffer ARGUMENTS p phy data Pointer to NOR phy data p dest Pointer to destination buffer start Start address of read relative to start of device cnt Number of octets to read p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Octets read successfully FS_ER
185. at are sharing the bus Oe by sharing the CLK MOSI and MISO signals When a card is first connected to the host at card power on it is in the inactive state awaiting a GO_IDLE STATE command to start the initialization process The card will enter SPI mode rather than card mode because the driver holds the CS signal low while executing the GO_IDLE STATE command The card now in the idle state moves through the ready as long as it supports the voltage range specified by the host before ending up in standby It can now get selected by the host using the chip select for data transfers Figure 15 5 flowcharts this procedure 193 SD MMC Drivers 17 3 2 SD MMC SPI COMMUNICATION DEBUGGING The SD MMC SPI driver accesses the hardware through a port SPI BSP as described in section C 13 SD MMC SPI mode BSP on page 493 A new BSP developed according to MCU MPU documentation or by example must be verified step by step until flawless operation is achieved 1 Initialization Initialization must succeed 2 Read data Data must be read from card in both single and multiple block transactions 3 Write data Data must be written to the card in both single and multiple block transactions and subsequently verified by reading the modified sectors and comparing to the intended contents Start bit Transmission bit End bit Command Di Cmd ix Argument CRC 1
186. at will the receive return error code from this function FS_ERR_NONE Journaling started FS_ERR_DEV Device access error RETURNED VALUE None NOTES WARNINGS None 373 LC FS API Reference Manual A 12 4 FS_FAT_JournalStop void FS _ FAT JournalStop CPU_CHAR name_ vol FS_ERR p err File Called from Code enabled by fs_fat_journal c Application FS_CFG FAT JOURNAL EN Stop journaling on volume ARGUMENTS name vol Volume name p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Journaling stopped FS_ERR_DEV Device access error RETURNED VALUE None NOTES WARNINGS None 374 A 12 5 FS_FAT_VolChk File Called from LC FS API Reference Manual Code enabled by fs _fat c Application Check the file system on a volume ARGUMENTS name_vol Volume name FS_CFG FAT VOL CHK EN p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE FS ERR NAME NULL FS_ERR DEV FS ERR VOL NOT OPEN FS ERR BUF NONE AVAIL RETURNED VALUE None NOTES WARNINGS None Volume checked without errors Argument name vol passed a null pointer Device access error Volume not open No buffers available 375 Appendix UC FS Error Codes This appendix provides a brief explanation of uC FS error codes defined in fs_err h Any error codes not listed here may be searched in fs
187. ation can change a bit from a 0 to a 1 but any bit can be individually programmed from a 1 to a 0 The pC FS driver requires that any 2 byte word can be individually accessed read or programmed The driver RAM requirement depends on flash parameters such as block size and run time configurations such as sector size For a particular instance a general formula can give an approximate if secs_per blk lt 255 templ ceil blk_cnt_used 8 blk_cnt_used 1 else templ ceil blk_cnt_used 8 blk_cnt_used 2 if sec_ent lt 65535 temp2 sec_cnt 2 else temp2 sec_cnt 4 temp3 sec_size TOTAL templ temp2 temp3 where secs per blk The number of sectors per block blk_cnt_used The number of blocks on the flash which will be used for the file system sec_cnt The total number of sectors on the device sec_size The sector size configured for the device in octets 154 NOR Flash Driver secs per blk and sec ont can be calculated from more basic parameters secs per blk floor blk_size sec_size sec_cnt secs_per blk blk ent used where blk size The size of a block on the device in octets Take as an example a 16 Mb NOR that is entirely dedicated to file system usage with a 64 KB block size configured with a 512 B sector The following parameters describe the format blk_cnt_used 32 blk_size 65536 sec_size 512 secs_per_blk 65536 512 128 sec_cnt
188. be grouped together to form large blocks effectively making the flash appear uniform to the generic driver A custom physical layer driver can also implement advanced program operations unique to a NOR device family 450 LUC FS Porting Manual The physical layer driver acts via a BSP The generic drivers for traditional NOR flash require a BSP as described in Appendix C NOR Flash BSP on page 459 The drivers for SPI flash require a SPI BSP as described in Appendix C NOR Flash SPI BSP on page 466 fs_dev_nor c h Provides generic driver interface e g init read write and performs wear leveling so all blocks are used equally Traditional NOR Serial NOR Physical Layer Driver Physical Layer Driver Implements particular NOR flash command set accesses NOR directly on bus Implements particular interface NOR flash command set accesses NOR with SPI BSP Bus interface SPI BSP fs_dev_nor_bsp c Access NOR via SPI re de SE rer c Initialize uninitial ize bus interface Figure C 4 NOR Driver Architecture Each physical layer driver must implement the functions to be placed into a FS_DEV_NOR_PHY_APT structure const FS_DEV_NOR_PHY API FSDev_NOR FSDev_NOR_PHY_Open FSDev_NOR_PHY_Close FSDev_NOR_PHY Rd FSDev_NOR_PHY Wr FSDev_NOR_PHY_EraseBlk FSDev_NOR_PHY IO Ctrl H The functions which must be implemented are listed an
189. ble Function File fs_opendir fs api c fs_closedir fs api c fs readdir_ CO fs api c FSDir_Open fs dir c FSDir_Close fs dir c FSDir_Rd fs dir c Table E 2 Directory function exclusion These functions are NOT included if FS_CFG_DIR_EN is DEF_DISABLED E 2 FEATURE INCLUSION CONFIGURATION Individual file system features may be selectively disabled FS_CFG_ FILE_BUF_EN FS CFG BUF EN enables when set to DEF ENABLED or disables when set to DEE DISABLED code generation of file buffer functions When disabled the functions in the following table will not be available Function File fs fflush fs api c fs_setbuf fs api c fs_setvbuf fs api c FSFile BufAssign fs file c FSFile_ BufFlush fs file c Table E 3 File buffer function exclusion These functions are NOT included if FS_CFG_FILE_BUF_EN is DEF_DISABLED 527 UC FS Configuration FS_CFG FILE LOCK EN FS CFG FILE LOCK EN enables when set to DEF_ENABLED or disables when set to DEE DISABLED code generation of file lock functions When enabled a file can be locked across several operations when disabled a file is only locked during a single operation and the functions in the following table will not be available Function File Ce flockfile fs api c fs_funlockfile fs api c fs_ftrylockfile fs api c FSFile_LockGet fs file c FSFile_LockSet fs_file c FSFile_ LockAccept fs file c Tab
190. bli Se SE e o 2 a a Chapter 1 Introduction This chapter Chapter 2 uC FS Architecture This chapter contains a simplified block diagram of the various different pC FS modules and their relationships The relationships are then explained Chapter 3 Directories and Files This chapter explains the directory structure and files needed to build a wC FS based application Learn about the files that are needed where they should be placed which module does what and more Chapter 4 Miscellaneous In this chapter you will learn the nomenclature used in pC FS to access files and folders and the ressources needed to use uC FS in your application Chapter 5 Devices and Volumes Every file and directory accessed with uC FS is a constituent of a volume a collection of files and directories on a device a physical or logical sector addressed entity This chapter explains how devices and volumes are managed 19 Introduction Chapter 6 POSIX API The best known API for accessing and managing files and directories is specified within the POSIX standard IEEE Std 1003 1 which is based in part in the ISO C standard C SO IEC 9899 This chapter explains how to use this API and examines some of its pitfalls and shortcomings Chapter 7 Files uC FS complements the POSIX API with its own file access API This chapter explains this API Chapter 8 Directories uC FS complements the POSIX API with its own directory access API This
191. br Volume number name vol String buffer that will receive the volume name see Note 2 RETURNED VALUE None NOTES WARNINGS 1 name vol MUST point to a character array of FS_CFG_MAX VOL NAME LEN characters 2 Ifthe volume does not exist name_vol will receive an empty string 322 LC FS API Reference Manual A 7 7 FSVol_IsDfit CPU_BOOLEAN FSVol_IsDflt CPU CHAR name vol File Called from Code enabled by fs vol Application N A Determine whether a volume is the default volume ARGUMENTS name_vol Volume name RETURNED VALUE DEF_YES if the volume with name name_vol is the default volume DEF_NO if no volume with name name_vol exists DEF_NO or the volume with name name_vol is not the default volume NOTES WARNINGS None 323 LC FS API Reference Manual A 7 8 FSVol_IsMounted CPU_BOOLEAN FSVol_IsMounted CPU_CHAR name vol File Called from Code enabled by fs _vol c Application N A Determine whether a volume is mounted ARGUMENTS name_vol Volume name RETURNED VALUE DEF_YES if the volume is open and is mounted DEF MO if the volume is not open or is not mounted NOTES WARNINGS None 324 LC FS API Reference Manual A 7 9 FSVol_LabelGet void FSVol_LabelGet CPU_CHAR name_vol CPU_CHAR label CPU_SIZE T len max FS_ERR p err File Called from Code enabled by fs_vol c Application N A Get volume label ARGUMENTS name_vol Volume name lab
192. bus common on many MCUs MPUs Because these modes involve different command protocols they require different drivers 175 SD MMC Drivers 17 1 FILES AND DIRECTORIES The files inside the SD MMC driver directory is outlined in this section the generic file system files outlined in Chapter 3 Directories and Files on page 28 are also required Micrium Software uC FS Dev This directory contains device specific files Micrium Software uC FS Dev SD This directory contains the SD MMC driver files fs_dev_sd contain functions and definitions required for both SPI and card modes Micrium Software uC FS Dev SD Card This directory contains the SD MMC driver files for card mode fs_dev_sd_card are device driver for SD MMC cards using card mode This file requires a set of BSP functions be defined in a file named fs_dev_sd_card_bsp c to work with a certain hardware setup BSP Template fs deu ed card bsp c is a template BSP See section C 12 SD MMC Cardmode BSP on page 467 for more information Micrium Software uC FS Dev SD SPI This directory contains the SD MMC driver files for SPI mode Ee dev_sd_spi are device driver for SD MMC cards using SPI mode This file requires a set of BSP functions be defined in a file named fs_dev_sd_spi bsp c to work with a certain hardware setup BSP Template fs_dev_sd_spi_bsp c is a template BSP See section C 13 SD MMC SPI mode BSP on page 493 for more information
193. bytes par Number of bytes to write p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Octets written successfully FS_ERR_DEV_INVALID OP Device invalid operation FS_ERR_DEV_IO Device I O error PG ERR DEV_TIMEOUT Device timeout error RETURNED VALUE None 436 LUC FS Porting Manual C 6 7 CopyBack void CopyBack FS_DEV_NAND PHY DATA p phy data CPU_INT32U src_page nbr phy CPU_INT32U dest page nbr phy FS_ERR p err File Called from Code enabled by NAND physical layer driver N A N A Make internal copy back of page data ARGUMENTS p_phy data Pointer to NAND phy data src_page_nbr_ phy Source page number dest_page_nbr_phy Destination page number p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Page copied successfully RETURNED VALUE None NOTES WARNINGS None 437 LUC FS Porting Manual C 6 8 EraseBlk void EraseBlk FS_DEV_NAND PHY DATA p phy data CPU_INT32U blk_nbr_phy FS_ERR p err File Called from Code enabled by NAND physical layer driver FSDev_NAND PhyEraseBlkHandler N A Erase block of NAND device ARGUMENTS p phy data Pointer to NAND phy data blk_nbr_phy Block to erase p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Block erased successfully FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device time
194. cccceseeeceeeeeeeeeeeeeeeeeeeeeeeeseeeseeeeseeaeseeeeeenes 385 CPOPO EE 386 OS Kernel ee A O A A E 386 D vice Dier eege aaaeaii a maa aa aaa aaea ENEE ENEE 394 t EE 396 WAIL EE 397 EIS ege site hanna e ee ee E ee 398 Close 0 Seed ege eege deed eelere ege 400 RO ised hvac Tee iden hese ege e ege ln eatin easel 401 d WEE 402 Geff eecccvccsecedinied cs ttvensis ev tiesvanetec sted aaiae iuui sania dik aa eainiie 404 lOsCtrl iia awk Sa ak aia a aaa aa AAA ae 406 IDE CF Device BSP ege dees a EAE A Gusta Seege Ee 408 FSDev_IDE_BSP_Opem csssscceeesseseeeeeesseeeeeeenseaaeeeesesnaeeeeeneeaes 410 FSDev_IDE_BSP_ClOS aaeain aa eea aaa aada aae aaa Aaina nahana 411 FSDev_IDE_BSP_Lock FSDev_IDE_BSP_Unlock seen 412 FSDev_IDE_BSP_ReSet ccssssccecssseeeceeeseseeeeeeeeseaeeeeensenaeeeeeseeaes 413 FSDev IDE BSP_ReGRd ssiscctccccsecctccceeiecticeeeuesesduvediecdlccveedecdvaceeveceee 414 FSDev_IDE_BSP_REQWI eccccccesseecceeeseeeeeeeeeeeeeseeeeeneeeeeeeeseeneeeeeeneaes 415 FSDev_IDE_BSP_CmdW 0 ccseccceceeseeeceeeeseeeeeeeenseaaeeeeeenaeeeeeeseeaes 416 FSDev_IDE_BSP_DataRd REENEN REENEN 417 FSDev_IDE_BSP_DataWr c ccceecesseeeceeeeseeeeeeeeseeeeeeeensenaeeeeenneaes 418 FSDev_IDE_BSP_DMA_Start ccssssscesssseeceeeesseeeeeeeeseeeeeeeenenees 419 FSDev_IDE_BSP_DMA_End cccssssecceeeeseeeeceeeeseeeeesneneaeeeeeeneeaes 420 FSDev_IDE_BSP_GetDrVND9r cecseecccee
195. ceive volume information see Note p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Volume information obtained FS_ERR_DEV Device access error FS_ERR_NAME NULL Argument name vol passed a NULL pointer PG ERR NULL PTR Argument p_info passed a NULL pointer FS_ERR_VOL MOT OPEN Volume is not open RETURNED VALUE None NOTES WARNINGS None 331 LC FS API Reference Manual A 7 13 FSVol_Rd Q void FSVol Rd CPU_CHAR name_vol void p dest FS SEC NBR start FS _SEC_QTY cnt FS_ERR p err File Called from Code enabled by fs _vol c Application N A Reads data from volume sector s ARGUMENTS name_vol Volume name p dest Pointer to destination buffer start Start sector of read cnt Number of sectors to read p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Sector s read FS_ERR_DEV Device access error FS_ERR_NAME NULL Argument name vol passed a NULL pointer PG ERR NULL PTR Argument p dest passed a NULL pointer PG ERR VOL NOT MOUNTED Volume is not mounted FS_ERR_VOL_NOT_OPEN Volume is not open 332 RETURNED VALUE None REQUIRED CONFIGURATION None NOTES WARNINGS None LC FS API Reference Manual 333 LC FS API Reference Manual A 7 14 FSVol_Wr void FSVol_ Wr CPU_CHAR name_vol void p src PG GEC NBR start PG _SEC_QTY cnt FS_ERR p err File Called fro
196. ces These files require a set of physical layer functions defined in a file name fs_dev_nor_ lt physical type gt as well as BSP functions to be defined in a file named fs_dev_nor_bsp c to work with a particular hardware setup For more details on this driver please refer to Chapter 15 NOR Flash Driver on page 151 RAMDisk This directory contains the RAM disk driver files 49 Directories and Files fs_dev_ramdisk constitue the RAM disk driver For more details on this driver please refer to Chapter 16 RAM Disk Driver on page 170 sD This directory contains the SD MMC driver files fs_dev_sd are device driver for SD devices Theses files require to be used with either the fs_dev_sd_spi for SPI one wire mode or fs_dev_sd_card for Card 4 wires mode files These files require a set of BSP functions to be defined in a file named either fs_dev_sd_spi_bsp c or fs_dev_sd_card_bsp c to work with a particular hardware setup For more details on this driver please refer to Chapter 17 SD MMC Drivers on page 174 3 11 pC FS PLATFORM SPECIFIC SOURCE CODE These files are provided by the pC FS device driver developer See Chapter 17 Porting uC FS However the uC FS source code is delivered with port examples Micrium Software uC FS Examples BSP Dev lt memory type gt lt manufacturer gt lt board name gt fs_dev_ lt memory type gt _bsp c Micrium This directory contains all softw
197. cessfully FS_ERR_DEV_INVALID IO CTRL T O control operation unknown to driver FS_ERR_DEV_INVALID UNIT NR Device unit number is invalid FS_ERR_DEV_IO Device I O error PG ERR DEV MO ODEN Device is not open PG ERR DEV MO PRESENT Device is not present FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None 406 LUC FS Porting Manual NOTES WARNINGS 1 Tracking whether a device is open is not necessary because this should ONLY be called when a device is open 2 Defined I O control operations are FS_DEV_IO CTRL REFRESH FS DEV 10 CTRL LOW FMT c FS_DEV_IO CTRL LOW MOUNT d FS_DEV_IO CTRL LOW UNMOUNT e FS DEV_IO CTRL LOW COMPACT f FS_DEV_IO CTRL LOW DEFRAH g FS DEV_IO CTRL SEC RELEASE h FS_DEV_IO CTRL PHY RD i FS_DEV_IO CTRL PHY WR j FS_DEV_IO CTRL PHY RD PAGE k FS_DEV_ IO CTRL PHY WR PAGE C D Refresh device Low level format device Low level mount device Low level unmount device Low level compact device Low level defragment device Release data in sector Read physical device Write physical device Read physical device page Write physical device page l FS_DEV_IO CTRL PHY ERASE BLK Erase physical device block m FS DV IO CIRL PHY ERASE CHIP Erase physical device Not all of these operations are valid for all devices The device driver IO_Ctr1 function is called while the caller holds the device lock 407 C 5 IDE CF DEVICE BSP LUC FS Porting Manual If you use and IDE CF device a dri
198. ch possible device FS_OS DevLock and FS_OS_DevUnlock acquire and release access to a specific device Lock operations for the same device are never nested FS_OS_FileInit FS_OS_FileAccept FS OS FileLock and FS_OS_FileUnlock Multiple calls to file access functions may be required for a file operation that must be guaranteed atomic For example a file may be a conduit of data from one task to several If a data entry cannot be read in a single file read some lock is necessary to prevent preemption by another consumer File locks represented by API functions like FSFile_LockGet and flockfile provide a solution Four functions implement the actual lock in the OS port FS OS FileInit creates one mutex for each possible file FS_OS FileLock FS OS FileAccept and FS OS FileUnlock acquire and release access to a specific file Lock operations for the same file MAY be nested so the implementations must be able to determine whether the active task owns the mutex If it does then an associated lock count should be incremented otherwise it should try to acquire the resource as normal 387 LUC FS Porting Manual FS_OS_WorkingDirGet and FS OS WorkingDirSet File and directory paths are typically interpreted absolutely they must start at the root directory specifying every intermediate path component If much work will be accomplished upon files in a certain directory or a task requires a root directory as part of its con
199. chip select ChipSelDis Disable device chip select SetClkFreq Set SPI clock frequency Table C 9 SPI port functions 497 LUC FS Porting Manual The first argument of each of these port functions is the device unit number an identifier unique to each driver device type after all it is the number in the device name For example sd 0 and nor 0 both have unit number 1 If two SPI devices are located on the same SPI bus either of two approaches can resolve unit number conflicts E Unique unit numbers All devices on the same bus can use the same SPI BSP if and only if each device has a unique unit number For example the SD MMC card sd 0 and serial NOR nor 1 require only one BSP E Unique SPI BSPs Devices of different types teg a SD MMC card and a serial NOR can have the same unit number if and only if each device uses a separate BSP For example the SD MMC card sd 0 and serial nor 0 require separate BSPs 498 LUC FS Porting Manual C 14 1 Open CPU_BOOLEAN FSDev_BSP_SPI_Open PG OD unit_nbr File Called from Code enabled by fs_dev_ lt dev_name gt _bsp c Device driver N A Open initialize hardware for SPI ARGUMENTS unit_nbr Unit number of device RETURNED VALUE DEE OR if interface was opened DEF_FAIL otherwise NOTES WARNINGS 1 This function will be called every time the device is opened 2 Several aspects of SPI communication may need to be conf
200. ciated with some logical typically human readable identifier file name Additional properties such as size update date time and access mode e g read only write only read write may be associated with a file File accesses constitute reading data from files writing data to files creating new files renaming files copying files etc File access is accomplished via file module level functions which are covered in Chapter 5 Directories can be accessed on a volume A directory is a container for files and other directories Operations include iterating through the contents of the directory creating new directories renaming directories etc Directory access is accomplished via directory module level functions which are covered in Chapter 6 A volume can be formatted More specifically high level formatted Formatting writes the control information for a file system to the partition on which a volume is located A volume can be closed unmounted During the closing of a volume any cached data is written to the underlying device and associated structures are freed For information about using volume names see section 4 2 uC FS Device and Volume Names on page 61 For FAT specific volume functions see Chapter 9 File Systems FAT on page 109 Function Description Valid for Unmounted Volume FSVol_CacheAssign Assign cache to volume Yes FSVol_Cachelnvalidate Invalidate cache for volume No FSVol_Cach
201. ciates a working directory with the active task The pointer is cast to the integral register data type and stored in a task register The application calls either of the core file system functions FS WorkingDirSet or fs_chdir to set the working directory The core function forms the full path of the working directory and saves it with the OS port function FS_OS WorkingDirSet The port function should associate it with the task in some manner so that it can be retrieved with FS OS WorkingDirGet even after many context switches have occurred if FS_CFG WORKING DIR EN DEF_ENABLED void FS_OS WorkingDirFree OS _TCB p_tcb OS_ERR Os_err CPU_INT32U reg_val CPU_CHAR path_buf reg_val OSTaskRegGet p_tcb FS_OS_ REG ID WORKING DIR amp OS_err if os_err OS ERR NONE return if reg_val 0u 1 return path_buf CPU_CHAR reg val FS_WorkingDirObjFree path_buf 2 endif Listing C 2 FS_OS_WorkingDirFree uC OS III LC 2 1 If the register value is zero no working directory has been assigned and no action need be taken LC 2 2 FS WorkingDirObjFree frees the working directory object to the working directory pool If this were not done the unfreed object would constitute a memory leak that could deplete the heap memory eventually 389 LUC FS Porting Manual The character string for the working directory is allocated from the uC LIB heap If a task is deleted it must
202. ckfile acquires the lock for a task Gf it does not already own it Accesses from other tasks will be blocked until a fs_funlockfile is called This functionality is available if FS_CFG_FILE LOCK_EN is DEF_ENABLED 6 3 1 OPENING READING amp WRITING FILES When an application needs to access a file it must first open it using fs_fopenO file pointer gt p file fs_fopen file txt lt file name wt lt mode string if p file FS_FILE 0 Handle error The return value of this function should always be verified as non NULL before the application proceeds to access the file The first argument of this function is the path of the file if working directories are disabled this must be the absolute file path beginning with either a volume name or a V see section 4 3 uC FS File and Directory Names and Paths on page 62 The second argument of this function is a string indicating the mode of the file this must be one of the strings shown in the table below Note that in all instances the b binary option has no affect on the behavior of file accesses 87 POSIX API fs_fopen Mode String Read Write Truncate Create Append r or rb Yes No No No No w or wb No Yes Yes Yes No a or ab No Yes No Yes Yes r or rb or r b Yes Yes No No No w or wb or w b Yes Yes Yes Yes No a or ab or a b
203. cmd void p src FS_ERR p err CPU_INT16U interrupt_status CPU_INT16U error_status CPU_INT16U timeout timeout 0u Wait until data xfer compl 1 interrupt status REG_INTERRUPT_STATUS while DEF_BIT_IS CLR interrupt_status BIT_INTERRUPT_STATUS ERROR BIT_INTERRUPT_STATUS_TRANSFER_COMPLETE DEF_YES timeout interrupt_status REG _INTERRUPT_STATUS if timeout TIMEOUT_TRANSFER_MAX p err FS DEV_SD CARD ERR WAIT TIMEOUT return Handle error eo 24 if DEF_BIT_IS SET interrupt_status BIT_INTERRUPT_STATUS ERROR DEF_YES error_status REG ERROR_STATUS if DEF_BIT_IS SET error_status REG ERROR_STATUS DATA END BIT DEF_YES p err FS DEV_SD CARD ERR_DATA else if DEF_BIT IS SET error_status REG ERROR STATUS DATA CRC DEF_YES p err FS DEV SD CARD ERR DATA CRC else if DEF_BIT IS SET error_status REG ERROR STATUS DATA TIMEOUT DEF YES FS_DEV_SD_CARD_ERR_DATA TIMEOUT p err else p err FS_DEV_SD_CARD_ERR_UNKONWN REG_ERROR_STATUS REG_INTERRUPT_STATUS return error_status interrupt_status p err FS DEV SD CARD ERR NONE 3 Listing C 11 FSDev_SD_Card_BSP_CmdDataWr 485 LUC FS Porting Manual LC 11 1 Wait until data transfer completes or an error occurs The wait loop or wait on semaphore SHOULD always have a timeout to avoid blocking the task in the case of an unforeseen hardware malfunction or
204. ction FS_DEV_SD_CARD_ERR_NONE FS_DEV_SD_CARD_ERR_NO CARD FS_DEV_SD_CARD_ERR_UNKNOWN FS DEV SD CARD ERR WAIT TIMEOUT FS DEV SD CARD ERR RESP TIMEOUT FS DEV_SD CARD ERR RESP CHKSUM FS DEV SD CARD ERR RESP CMD IX FS DEV SD CARD ERR RESP END BIT FS DEV_SD CARD ERR RESP FS DEV SD CARD ERR DATA RETURNED VALUE None No error No card present Unknown or other error Timeout in waiting for command response Timeout in receiving command response Error in response checksum Response command index error Response end bit error Other response error Other data error 477 LUC FS Porting Manual NOTES WARNINGS 1 This function will be called even if no response is expected from the command 2 This function will NOT be called if FSDev_SD_Card_BSP_CmdStart returned an error 3 The data stored in the response buffer should include only the response data i e should not include the start bit transmission bit command index CRC and end bit a For a command with a normal 48 bit response a 4 byte response should be stored in p_resp b For a command with a long 136 bit response a 16 byte response should be returned in p_resp The first 4 byte word should hold bits 127 96 of the response The second 4 byte word should hold bits 95 64 of the response The third 4 byte word should hold bits 63 32 of the response The four 4 byte word should hold bits 31 0 of the response EXAMPLE The implementation of FSDe
205. ctories and Files cpu_core c contains C code that is common to all CPU architectures Specifically this file contains functions to measure the interrupt disable time of the CPU_CRITICAL ENTER and CPU_CRITICAL EXIT macros a function that emulates a count leading zeros instruction and a few other functions cpu_core h contains the function prototypes of the functions provided in cpu_core c as well as allocation of the variables used by this module to measure interrupt disable time cpu_def h contains miscellaneous define constants used by the pC CPU module Cfg Template This directory contains a configuration template file cpu_cfg h that you will need to copy to your application directory in order to configure the pC CPU module based on your application requirements cpu_cfg h determines whether you will enable measurement of the interrupt disable time whether your CPU implements a count leading zeros instruction in assembly language or whether it will need to be emulated in C and more lt architecture gt This is the name of the CPU architecture for which uC CPU was ported to The lt and gt are not part of the actual name lt compiler gt This is the name of the compiler or compiler manufacturer used to build the code for the pC CPU port The lt and gt are not part of the actual name The files in this directory contain the uC CPU port cpu h contains type definitions to make uC FS and othe
206. cture gt lt compiler gt lib mem a asm Micrium This directory contains all software components and projects provided by Micrium 37 Directories and Files Software This sub directory contains all the software components and projects ucC LIB This is the main pC LIB directory Cfg Template This directory contains a configuration template file Lib_cfg h that must be copied to the application directory to configure the pC LIB module based on application requirements lib cfg h determines whether to enable assembly language optimization assuming there is an assembly language file for the processor i e lib mem_a asm and a few other defines 3 6 pC CLK TIME CALENDAR MANAGEMENT puC Clk consists of functions that are meant to centralize time management in one independant module This way the same time info can be easily shared across all Micrium products Micrium Software uC Clk Cfg Template clk_cfg h VOS lt rtos_name gt clk_os c Source clk c clk h Micrium This directory contains all software components and projects provided by Micrium 38 Directories and Files Software This sub directory contains all the software components and projects uc Clk This is the main pC Clk directory Cfg Template This directory contains a configuration template file clk_cfg h that must be copied to the application directory to configure the uC Clk module based on application requirements c
207. d Ctrl codes Input Mode Buffer size 0 Figure 11 1 IDE Detection Trace Output 127 IDE CF Driver 11 2 1 ATA TRUE IDE COMMUNICATION The interface between an ATA device and host is comprised of data bus address bus and various control signals as shown in Figure 11 2 Three forms of data transfer are possible each with several timing modes 1 PIO programmed input output PIO must always be possible indeed it may be the only possible transfer form on certain hardware Using PIO data requests are satisfied by direct reads or writes to the DATA register The IDENTIFY _ DEVICE command and standard sector and multiple sector read write commands always involve this type of transfer Five timing modes 0 1 2 3 and 4 are standard two more 5 and 6 are defined in the CF specification 2 Mutiword DMA In Multiword DMA mode a DMARQ and DMACK handshake initiates automatic data transmission during which the host moves data between its memory and the bus The DMA read write commands READ _DMA WRITE DMA may use Multiword DMA Three timing modes 0 1 and 2 are standard two more 3 and 4 are defined in the CF specification 3 Ultra DMA The purposes of several control signals are reassigned during Ultra DMA transfers For example IORDY becomes either DDMARDY or DSTROBE depending on the direction to control data flow The DMA read write commands READ_DMA WRITE DMA may use Ultra DMA Seven timing modes 0 1 2
208. d described in Table C 5 The first argument of each of these is a pointer to a FS_DEV_NOR_PHY_ DATA structure which holds physical device information Specific members will be described in subsequent sections as 451 LUC FS Porting Manual necessary The NOR driver populates an internal instance of this type based upon configuration information Before the file system suite has been initialized the application may do the same if raw device accesses are a necessary part of its start up procedure Function Description Open Open initialize a NOR device and get NOR device information Close Close uninitialize a NOR device Rd Read from a NOR device and store data in buffer Wr Write to a NOR device from a buffer EraseBlk Erase block of NOR device IO Ctrl Perform NOR device I O control operation Table C 5 NOR flash physical layer driver functions 452 LUC FS Porting Manual C 9 1 Open void Open FS_DEV_NOR PHY DATA p phy data FS_ERR p err File Called from Code enabled by NOR physical layer driver FSDev_NOR_Open N A Open initialize a NOR device instance and get NOR device information ARGUMENTS p phy data Pointer to NOR phy data p err Pointer to variable that will receive the return error code from this function RETURNED VALUE None NOTES WARNINGS Several members of p phy data may need to be used assigned 1 BlkCnt and BlkSize MUST be
209. de enabled by fs_api c FS_CFG WORKING DIR EN Application FS_CFG_API_EN and not Get the working directory for the current task ARGUMENTS path dir String buffer that will receive the working directory path size Size of string buffer RETURNED VALUE Pointer to path_dir if no error occurs Pointer to NULL otherwise NOTES WARNINGS None 231 LC FS API Reference Manual A 2 22 fs_localtime_r struct fs tm fs_localtime r const fs_time t p ts struct fs tm p time File Called from Code enabled by fs_api c Application FS_CFG API_EN Convert timestamp to date time ARGUMENTS p ts Pointer to time value p time Pointer to variable that will receive broken down time RETURNED VALUE Pointer to p_time if NO errors Pointer to NULL otherwise NOTES WARNINGS None 232 LC FS API Reference Manual A 2 23 fs_mkdir int fs_mkdir const char name full File Called from Code enabled by fs_api c Application FS_CFG_API_EN and not FS_CFG_RD_ONLY_EN Create a directory ARGUMENTS name full Name of the directory RETURNED VALUE 0 if the directory is created 1 if the directory is NOT created NOTES WARNINGS None EXAMPLE void App Fnct void sine OLES err fs_mkdir sd 0 data old Make dir 24 if err 0 APP_TRACE_INFO Could not make dir 233 LC FS API Reference Manual A 2 24 fs_mktime fs time t
210. ded When DEF_ENABLED statistics counters will be maintained FS_CFG_CTR_ERR_EN FS_CFG CTR STAT EN determines whether the code and data space used to keep track of errors will be included When DEF_ENABLED error counters will be maintained E 7 FAT CONFIGURATION Configuration constants can be used to enable disable features within the FAT file system driver FS Pat CFG LEN EN FG FAT CFG LFN EN is used to control whether long file names LFNs are supported When DEF_DISABLED all file names must be valid 8 3 short file names FS_FAT CFG FAT12_EN FS_FAT CFG FAT12 EN is used to control whether FAT12 is supported When DEF DISABLED FAT12 volumes can not be opened nor can a device be formatted as a FAT12 volume FS_FAT CFG FAT16_EN FS FAT CFG FAT16 EN is used to control whether FAT16 is supported When DEF DISABLED FAT16 volumes can not be opened nor can a device be formatted as a FAT16 volume 532 UC FS Configuration FS_FAT CFG FAT32_EN FS FAT CFG FAT32 EN is used to control whether FAT32 is supported When DEF DISABLED FAT32 volumes can not be opened nor can a device be formatted as a FAT32 volume FS_FAT_CFG_JOURNAL_EN FG FAT CFG JOURNAL EN selects whether journaling functions will be present When DEF_ENABLED journaling functions are present when DEF_DISABLED journaling functions are NOT present If disabled the functions in Table E 8 will not be available Function File FS_FAT_JournalOpen fs
211. dev Device name see Note p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Device erased successfully FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_DEV_INVALID Argument name dev specifies an invalid device FS_ERR_DEV_NOT_OPEN Device is not open FS_ERR_DEV_NOT_PRESENT Device is not present FS_ERR_DEV_INVALID_LOW_FMT Device needs to be low level formatted FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NOR device e g nor 0 This function should NOT be used while a file system exists on the device or if the device is low level formatted unless the intent is to destroy all existing information 363 LC FS API Reference Manual A 11 SD MMC DRIVER FUNCTIONS void FSDev_SD Card QuerySD CPU_CHAR name_ dev FS_DEV SD INFO p info FS_ERR p err void FSDev_SD SPI_QuerySD CPU_CHAR name_ dev FS DEV SD INFO p info FS_ERR p err void FSDev_SD Card RdCID CPU_CHAR name_ dev CPU_INTO8U p info FS_ERR p err void FSDev_SD_SPI_RdCID CPU_CHAR name_ dev CPU_INTO8U p info FS_ERR p err void FSDev_SD Card RdCSD CPU_CHAR name_ dev CPU_INTO8U p info FS_ERR p err void FSDev_SD SPI_RdCSD CPU_CHAR name_ dev CPU_INTO8U p info FS_ERR p err 364 A 11 1 FSDev_SD xxx QuerySD void FSDev_SD Card QuerySD CPU_CHAR L
212. dicates the direction of any data transfer that should follow this command if any FS DEV SD CARD DATA DIR NONE No data transfer FS_DEV_SD_ CARD DATA DIR_HOST_TO CARD Transfer host to card write FS_DEV_SD_ CARD DATA DIR CARD TO HOST Transfer card to host read 473 LUC FS Porting Manual e p_cmd gt DataType indicates the type of the data transfer that should follow this command if any PG DEV GD CARD DATA TYPE NONE No data transfer FS DEV SD CARD DATA TYPE SINGLE BLOCK Single data block FS DEV_SD CARD DATA TYPE MULTI BLOCK Multiple data blocks FS_DEV_SD CARD DATA TYPE STREAM Stream data f p cmd gt RespType indicates the type of the response that should be expected from this command FS_DEV_SD_ CARD RESP_TYPE NONE No response FS_DEV_SD_CARD RESP_TYPE RI R1 response Normal Response Command FS_DEV_ SD CARD RESP_TYPE R1B R1b response FS_DEV_SD_CARD RESP_TYPE RI R2 response CID CSD Register FS_DEV_SD_CARD RESP_TYPE_R3 R3 response OCR Register FS_DEV_SD CARD RESP TYPE R4 R4 response Fast I O Response MMC FS_DEV_SD_CARD RESP_TYPE_R5 R5 response Interrupt Request Response MMC FS_DEV_SD CARD RESP_TYPE R5B R5B response FS_DEV_SD CARD RESP_TYPE R6 R6 response Published RCA Response FS_DEV_SD CARD RESP TYPE BI R7 response Card Interface Condition g p_cmd gt B1lkSize and p cmd gt BlkCnt are the block size and block count of the data transfer that should follow this command if any 3 Th
213. directory Otherwise an error is output and the working directory is unchanged 543 Shell Commands F 3 3 fs_cp Copy a file USAGES fs cp source file dest file fs_ cp source file dest dir ARGUMENTS source_file Source file path dest_file Destination file path dest_dir Destination directory path OUTPUT None REQUIRED CONFIGURATION Available only if FS SHELL CFG CP_EN is DEF ENABLED and FS CFG RD ONLY EN is DEF DISABLED NOTES WARNINGS In the first form of this command neither argument may be an existing directory The contents of source file will be copied to a file named dest_file located in the same directory as source_file In the second form of this command the first argument must not be an existing directory and the second argument must be an existing directory The contents of source file will be copied to a file with name formed by concatenating dest_dir a path separator character and the final component of source_file 544 Shell Commands F 3 4 fs date Write the date and time to terminal output or set the system date and time USAGES fs_ date fs date time ARGUMENTS time If specified time to set in the form mmddhhmmccyy where the Ist mm is the month 1 12 the dd is the day 1 29 30 or 31 the hh isthe hour 0 23 the 2nd mm is the minute 0 59 the ccyy is the year 1900 or larger OUTPUT If no argument date and time REQUIRED CONFIGURATION Available o
214. e FS FILE p file FS FILE SIZE size FS_ERR p err CPU_SIZE T FSFile Wr FS_FILE p file void p src CPU_SIZE T size FS_ERR p err 289 LC FS API Reference Manual A 6 1 FSFile_BufAssign void FSFile BufAssign FS FILE p file void p buf FS_FLAGS mode CPU_SIZE T size FS_ERR p err File Called from Code enabled by fs file c Application FS_CFG FILE BUF EN fs_setbuf fs_setvbuf Assign buffer to a file See fs_setvbuf for more information ARGUMENTS p file Pointer to a file p buf Pointer to buffer mode Buffer mode FS_FILE BUF MOD RD Data buffered for reads FS_FILE BUF MODE WR Data buffered for writes FS_FILE BUF MODE RD WR Data buffered for reads and writes size Size of buffer in octets p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE File buffer assigned FS_ERR_NULL PTR Argument p file or p buf passed a NULL pointer FS_ERR_INVALID TYPE Argument p file s type is invalid or unknown FS ERR FILE INVALID BUF MODE Invalid buffer mode 290 LC FS API Reference Manual FS ERR FILE INVALID BUF SIZE Invalid buffer size FS ERR FILE BUF ALREADY ASSIGNED Buffer already assigned FS ERR FILE NOT OPEN File NOT open RETURNED VALUE None NOTES WARNINGS None 291 A 6 2 FSFile_BufFlush LC FS API Reference Manual void FSFile BufFlush FS FILE p file PG ERR p err File Called from Code enabled by fs file c
215. e volume the same name as the underlying device If the default partition is to be opened or if the device is not partition then the partition number 5c should be zero FSVol_Fmt formats a file system volume If the RAM disk is in volatile RAM it have no file system on it after it is opened it will be unformatted and must be formatted before a volume on it is opened If the RAM disk initialization succeeds the file system will produce the trace output as shown in Figure 16 1 Gf a sufficiently high trace level is configured See section E 9 Trace Configuration on page 534 about configuring the trace level Terminal 1 0 Output Log file Off RAM DISK FOUND Sec Size 512 bytes Size 32768 secs FS_FAT_Fmt CREATING FILE SYSTEM Type FATI6 Sec size 512 B Clus size 2 sec Vol size 32767 sec Clus 16303 FATs SS FS_FAT_Open FILE SYSTEM FOUND Type FATI6 Sec size 512 B Clus size 2 sec Vol size 32767 sec Clus 16302 FATs Ki Ctrl codes Input Mode Buffer size 0 Figure 16 1 RAM Disk Initialization Trace Output 173 Chapter 1 SD MMC Drivers SD Secure Digital cards and MMCs MultiMedia Cards are portable low cost media often used for storage in consumer devices Six variants as shown in Table 17 1 are widely available to electronic retail outlets all supported by SD MMC driver The MMCplus and SD or SDHC are offered in compatible large card formats Adapters are
216. e EE 219 ES Uer TT WE 220 TS ele TEE 221 TS fread sisinio anann aana ai anata aaaea aiat iaaa daana 222 TE teeki 2 ee eege ege TEE Ee Eege 223 ES E e EE 225 ES CT RE 226 ER e EE 227 fs ftrylockfile seed 228 fs f lockKfile aAa deeg a Vaadaa 229 ISIWE EE 230 A 2 21 A 2 22 A 2 23 A 2 24 A 2 25 A 2 26 A 2 27 A 2 28 A 2 29 A 2 30 A 2 31 A 2 32 A 3 A 3 1 A 3 2 A 3 3 A 3 4 A 3 5 A 3 6 A 3 7 A 3 8 A 3 9 A 3 10 A 3 11 A 3 12 A 3 13 A 4 A 4 1 A 4 2 A 4 3 A 4 4 A 5 A 5 1 A 5 2 A 5 3 A 5 4 A 5 5 A 5 6 TS 2QeteWd 0 es eege eed N eee at et antes 231 FS localtime r aaan eade de See SEENEN de 232 fs mkdir EE 233 EN ln TEE 234 fs opendir EE 235 fSreaddir T RE 236 LE une CT DEE 237 TS CC LE 239 Te Treines Eeer ee Eed 241 FS STIMU EE 242 fS setb f EE 244 Ts setvbuf E 245 Device FUNCTIONS dra amas Ea ae ee a aeaa aaa EN ege 247 IDLA e Co N E E T ATETEA 249 FSDev_GetDevName cecceeceeeceeeeeseeeeeeeeeeeeeeeeeeeneeeesseeneeseeeeenees 250 FSDev_GetDevGnt eege eege genee ee ee 251 FSDev_GetDevCntMax cccccececeeeeeseeeeeeeceeeeeeeeeeeeseseeeeeneeeeeeeeeees 252 FSDev_GetNbrPartitions ccccccccsssseceeesseeeceeenseceeeeeenseeaeeeeeneeees 253 FSDev iOpen egene tail ae dni Eege 254 FSDev Rartton gdelt edd dEr dE ENNEN cecetesgsencdicecsedendecvexs 256 FSDev_PartitioNFind een 257 FSDev_PartitionIMit cccccceeeesseecceeeseceeeeeeeseeaeeeeeeseaeseeens
217. e FIFO fast enough DMA avoids those pitfalls by offloading the responsibility for moving data directly to the CPU 469 LUC FS Porting Manual Second the completion of operations such as command execution and data read write are often signaled via interrupts unless some error occurs whereupon a different interrupt is triggered During large transfers these operations occur frequently and the typical wait between initiation and completion is measured in microseconds On most platforms polling the interrupt status register within the task performs better Oe results in faster reads and writes than waiting on a semaphore for an asynchronous notification from the ISR because the penalty of extra context switches is not incurred C 12 1 FSDev_SD_ Card Bb Open CPU_BOOLEAN FSDev_SD Card BSP_Open FS OTY unit_nbr File Called from Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_Refresh N A Open initialize SD MMC card interface ARGUMENTS unit_nbr Unit number of SD MMC card RETURNED VALUE DEE OR if interface was opened DEF_FAIL otherwise NOTES WARNINGS This function will be called EVERY time the device is opened 470 LUC FS Porting Manual C 12 2 FSDev_SD_Card_BSP_Lock FSDev_SD_Card_BSP_Unlock void FSDev_SD Card BSP Lock FS Om unit_nbr void FSDev_SD Card BSP_Unlock FS Om unit_nbr File Called from Code enabled by fs_dev_sd_card_bsp c SD MMC cardmode dri
218. e file system integrated into Microsofts DOS was FAT12 so called because each entry in the File Allocation Table was 12 bits This limited disk size to approximately 32 MB Extensions to 16 and 32 bit entries FAT16 and FAT32 expand support to 2 GB and 8 TB respectively As described in Appendix E Fat Configuration on page 532 support for FAT12 FAT16 and FAT32 can be individually disabled if desired FAT32 introduces several new innovations above its predecessors The root directory in the earlier systems was a fixed size i e when the medium is formatted the maximum number of files that could be created in the root directory typically 512 is set In FAT32 the root directory is dynamically resizable like all other directories Two special sectors are also included the FS info sector and the backup boot sector The former stores information convenient to the operation of the host such as the last used cluster The latter is a copy of the first disk sector the boot sector in case the original is corrupted 9 1 2 SHORT AND LONG FILE NAMES In the original version of FAT files could only carry short 8 dot 3 names with eight or fewer characters in the main name and three or fewer in its extension The valid characters in these names are letters digits characters with values greater than 127 and the following 3 f E e EK A Se In wC FS the name passed by the application is always verified both for invalid length a
219. e from the card also on the CMD line finally one or more blocks data may be sent in one direction on the data line s each appended with a CRC Host to card Card to host CMD Command LJ Respose EE 5 6 Card to host read Host to card write write only BA tee Sih beets eis Data g laing Busy 1 2 3 4 Figure 17 2 SD MMC communication sequence F17 2 1 When no data is being transmitted data lines are held low F17 2 2 Data block is preceded by a start bit 0 an end bit CU follows the CRC F17 2 3 The CRC is the 16 bit CCITT CRC 181 SD MMC Drivers F17 2 4 During the busy signaling following a write DATO only is held low F17 2 5 See Figure 17 3 for description of the command format F17 2 6 See Figure 17 3 for description of the command format Start bit Transmission bit End bit Command Argument format 32 bits Start bit Transmission bit End bit Response Response CRC format 32 or 128 bits 7 bits 1 2 Figure 17 3 SD MMC command and response formats F17 3 Command index is not valid for response formats R2 and R3 F17 3 2 CRC is not valid for response format R3 When a card is first connected to the host at card power on it is in the inactive state awaiting a GO_IDLE STATE command to start the initialization process which is dependent on the card type During initialization the card starting in the idle state mo
220. e from this function FS_ERR_NONE Error indicator obtained FS_ERR_NULL PTR Argument p file passed a NULL pointer FS_ERR_INVALID TYPE Argument p file s type is invalid or unknown FS ERR FILE NOT OPEN File NOT open RETURNED VALUE DEE MO if error indicator is NOT set or if an error occurred DEF_YES if error indicator is set NOTES WARNINGS None 296 LC FS API Reference Manual A 6 7 FSFile_IsOpen CPU_BOOLEAN FSFile IsOpen CPU_CHAR name full FS FLAGS p mode FS_ERR p err File Called from Code enabled by fs file c Application N A FSFile_Open Test if file is already open ARGUMENTS name full Name of the file See section 4 3 uC FS File and Directory Names and Paths on page 62 for information about file names p_mode Pointer to variable that will receive the file access mode see section 7 1 1 Opening Files on page 99 for the description the file access mode p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Error indicator obtained FS_ERR_NULL PTR Argument p file passed a NULL pointer FS_ERR_BUF_NONE AVAIL No buffer available FS ERR ENTRY NOT FILE Entry NOT a file FS_ERR_NAME INVALID Invalid file name or path FS_ERR_VOL_ INVALID SEC NBR Invalid sector number found in directory entry RETURNED VALUE DEF_NO if file is NOT open DEF_YES if file is open 297 LC FS API Reference Manual NOTES WARNINGS None 298 LC F
221. e is required with three basic elements First a device driver must be able to read and write to the device Next a file system driver must be able to parse the device s on disk structures to read the names 15 Introduction properties and data of files and to format those structures to modify existing entries and create new ones Finally an application level interface must provide for the exigencies of file and directory access 1 2 yC FS uC FS is a compact reliable high performance file system It offers full featured file and directory access with flexible device and volume management including support for partitions Source Code uC FS is provided in ANSI C source to licensees The source code is written to an exacting coding standard that emphasizes cleanness and readability Moreover extensive comments pepper the code to elucidate its logic and describe global variables and functions Where appropriate the code directly references standards and supporting documents Device Drivers Device drivers are available for most common media including SD MMC cards NAND flash NOR flash and IDE CF Each of these is written with a clear layered structure so that it can easily be ported to your hardware The device driver structure is simple basically just initialization read and write functions so that pC FS can easily be ported to a new medium Devices and Volumes Multiple media can be accessed simultaneously including mult
222. e pointer to the data buffer that will receive the data transfer that should follow this command p data is given so that a DMA transfer can be set up EXAMPLE The example implementation of FSDev_SD Card_BSP_CmdStart in like the examples in subsequent sections targets a generic host conformant to the SD card association s host controller specification While few hosts do conform most have a similar mixture of registers and registers fields and require the same sequences of basic actions 474 LUC FS Porting Manual void FSDev_SD_Card_ BSP_CmdStart PS Or unit_nbr FS _DEV_SD CARD CMD p cmd void p data FS_ERR p err CPU_INT16U command CPU_INT32U present_state CPU_LINT16U transfer_mode present_state REG STATE Chk if controller busy SE if DEF_BIT_IS SET AN present State BIT STATE CMD INHIBIT DAT BIT STATE CMD INHIBIT CMD DEF_YES p err FS DEV GD CARD ERR BUSY return transfer_mode DEF_BIT_NONE Calc transfer mode reg value 2 if p_cmd gt DataType FS_DEV_SD_CARD_DATA TYPE MULTIPLE BLOCK transfer mode BIT _TRANSFER_MODE MULTIPLE BLOCK BIT_TRANSFER MODE AUTO CMD12 BIT _TRANSFER_MODE BLOCK _COUNT_ENABLE if p_cmd gt DataDir FS_DEV_SD CARD DATA DIR CARD TO HOST transfer_mode BIT_TRANSFER_MODE_READ BIT TRANSFER MODE DMA ENABLE else transfer mode D BIT TRANSFER MODE DMA ENABLE
223. e programs In a simple embedded CPU the program is stored at a fixed location in a non volatile memory usually flash If an application must support firmware updates a file system may be a more convenient place since the software handles the details of storing the program The boot loader of course would need to be able to 17 Introduction load the application but since that requires only read only access no imposing program is required The ROM boot loaders in some CPUs can check the root directory of a SD card for a binary in addition to the more usual locations such as external NAND or NOR flash 1 4 WHY FAT File Allocation Table FAT is a simple file system widely supported across major OSs While it has been supplanted as the format of hard drives in Windows PCs removable media still use FAT because of its wide support That is suitable for embedded systems which would often be challenged to muster the resources for the modern file systems developed principally for large fixed disks uC FS supports FAT because of the interoperability requirements of removable media allowing that a storage medium be removed from an embedded device and connected to a PC All variants and extensions are supported to specification A notorious weakness of FAT exacerbated by early Windows system drivers is its non fail safe architecture Certain operations leave the file system in an inconsistent state albeit briefly which may corrupt the d
224. e set of file operations or entry functions manage the files and directories available on the system Using these functions the application can copy create delete and rename files and get and set a file or directory s attributes and date time The available entry functions are listed in Table 7 3 The entry functions and the FSFile_Open function accept full file paths For information about using file and path names see section 4 3 uC FS File and Directory Names and Paths on page 62 The functions listed in Table 7 1 and Table 7 3 are core functions in the file access module FSFile functions and entry module FSEntry functions These are matched in most cases by API level functions that correspond to standard C or POSIX functions The core and API functions provide basically the same functionality the benefits of the former are enhanced capabilities a consistent interface and meaningful return error codes 97 Files 7 1 FILE ACCESS FUNCTIONS The file access functions provide an API for performing a sequence of operations on a file located on a volume s file system The file object pointer returned when a file is opened is passed as the first argument of all file access functions a characteristic which distinguishes these from the entry access functions and the file object so referenced maintains information about the actual file on the volume and the state of the file access The file acces
225. eFlush Flush cache for volume No FSVol_Close Close unmount volume Yes 76 Devices and Volumes Function Description Valid for Unmounted Volume FSVol_Fmt Format volume Yes FSVol_IsMounted Determine whether volume is Yes mounted FSVol_LabelGet Get volume label No FSVol_LabelSet Set volume label No FSVol_Open Open mount volume 1 en FSVol_Query Get volume information Yes FSVol_Rd Read sector on volume No FSVol_Refresh Refresh a volume No FSVol_Wr Write sector on volume No 5 6 USING VOLUMES A volume is opened with FSVol_Open FSVol_Open CPU_CHAR ide 0 lt a volume name CPU_CHAR ide 0 lt b device name FS_PARTITION NBR 0 lt c partition number FS_ERR amp err lt d return error Table 5 2 Volume API Functions The parameters are the volume name a the device name b and the partition that will be opened c There is no restriction on the volume name a however it is typical to give the volume the same name as the underlying device If the default partition is to be opened or if the device is not partitioned then the partition number c should be zero The return error code from this function provides important information about the volume state 77 Devices and Volumes m If the return error code is FS_ERR_NONE then the volume has been mounted and is ready to use m If the return erro
226. e_full_new MUST specify entries on the same volume 2 If path_old and path_new specify the same entry the volume will not be modified and no error will be returned 3 If path_old specifies a file a path_new must NOT specify a directory b if path_new is a file it will be removed 239 LC FS API Reference Manual 4 If path_old specifies a directory a path_new must NOT specify a file b if path_new is a directory path_new MUST be empty if so it will be removed 5 The root directory may NOT be renamed EXAMPLE void App Fnct void int err See Note 1 err fs_rename sd 0 data file001 txt Rename file E sd 0 data old file001 txt if err 0 APP_TRACE_INFO Could not rename file L4 6 1 For this example file rename to succeed the following must be true when the function is called The file sd 0 data file001 txt must exist 2 The directory sd 0 data old must exist 3 If sd 0 data old file001 txt exists it must not be read only If sd 0 data old file001 txt exists and is not read only it will be removed and sd 0 data file001 txt will be renamed 240 LC FS API Reference Manual A 2 29 fs_rewind void fs_rewind FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG API EN Reset file position indicator of a file ARGUMENTS p file Pointer to a file RETURNED VALUE None NOTES WARNINGS 1 fs _rewind
227. each CPU has a different host controller that must be individually ported To that end a BSP supplementary to the general uC FS BSP is required that abstracts the SD MMC interface The port includes one code file FS DEV SD CARD BSP C This file is generally placed with other BSP files in a directory named according to the following rubric Micrium Software EvalBoards lt manufacturer gt lt board_name gt lt compiler gt BSP Several example ports are included in the uC FS distribution in files named according to the following rubric Micrium Software uC FS Examples BSP Dev SD Card lt cpu_name gt Function Description FSDev_SD Card BSP_Open Open initialize SD MMC card interface FSDev_SD Card BSP Close Close uninitialize SD MMC card interface FSDev_SD Card BSP_Lock Acquire SD MMC card bus lock FSDev_SD Card BSP_Unlock Release SD MMC card bus lock FSDev_SD Card BSP _CmdStart Start a command FSDev_SD_Card_BSP_CmdWaitEnd Wait for a command to end and get response FSDev_SD_Card_BSP_CmdDataRd Read data following command FSDev_SD_Card_BSP_CmdDataWr Write data following command FSDev_SD Card BSP _GetB1kCntMax Get max block count FSDev_SD_Card_BSP_GetBusWidthMax Get maximum bus width in bits 467 LUC FS Porting Manual Function Description FSDev_SD Card BSP _SetBusWidth Set bus width FSDev_SD Card BSP SetClkFreq Set clock frequency FSDev_SD Card BSP
228. ed CPU_BOOLEAN App ShellInit void CPU_BOOLEAN ok ok Shell Init if ok DEF_FAIL return DEF_FAIL ok FSShell Init if ok DEF FAIL return DEF_FAIL return DEF_OK Listing F 1 Initializing pC Shell 537 Shell Commands It s assumed that the application will create a task to receive input from a terminal this task should be written as shown in Listing F 2 void App ShellTask void sp arg CPU_CHAR cmd_line MAX CMD LEN SHELL ERR err SHELL CMD PARAM cmd Garam CPU_CHAR cwd_path FS CFG FULL NAME LEN Lui Init cmd param see Note 1 Str_Copy amp cwd_path 0 CPU_CHAR cmd_param pcur_working dir void cwd_path 0 cmd_param pout_opt void 0 while DEF TRUE App ShellIn cmd_line MAX CMD LEN Bd cmd see Note 2 Exec cmd see Note 3 Shell _Exec cmd_line App ShelloOut amp cmd param amp err switch err case SHELL ERR CHD NOT FOUND case SHELL ERR CHD SEARCH case SHELL ERR ARG TBL FULL App ShellOut Command not found r n 19 cmd_param pout_opt break default break LE kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk App ShellIn kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk kkkkkk SG CPU_LINT16S App ShellIn CPU_CHAR pbuf CPU_INT16U buf len Store line from terminal command line into pbuf return length of li
229. ed by a write only if the buffer has been flushed except when the read encountered the end of file in which case a write may happen immediately The buffer is automatically flushed when the file is closed File buffering is particularly important when data is written in small chunks to a medium with slow write time or limited endurance An example is NOR flash or even NAND flash where write times are much slower than read times and the lifetime of device is constrained by limits on the number of times each block can be erased and programmed EN POSIX API static CPU_INT32U App FileBuf 512 4 Define file buffer void App Fnct void CPU_INTO8U datal 50 p_file FS_fopen file txt wir if p file FS_FILE 0 Set buffer see Note 1 Si fs_setvbuf p file void App FileBuf P _IOFBF sizeof App FileBuf fs_fflush p file Make sure data is written to file s fs_fclose p file When finished close file SC Listing 6 3 Example file buffer usage L6 3 1 The buffer must be assigned immediately after opening the file An attempt to set the buffer after read or writing the file will fail L6 3 2 While it is not necessary to flush the buffer before closing the file some applications may want to make sure at certain points that all previously written data is stored on the device before writing more 92 POSIX API 6 3 4 DIAGNOSING A FILE ERROR The file maintains flags that reflect erro
230. eeeeeeeeeeseeeeeeeeaees 507 SO EE 508 FS DEViINF E EEE E A AET SE EE 510 FS DEV NAND CFG monar oe aAa Ea AAAA AANA eege 511 FS DEV NOR CFG urinni ent eege Reel NE 513 FS DEV RAM CFG eei aana Aeaee AER AARAA tani ee 516 FS_DIR_ENTRY struct fs_dirent ssssssssesenunnnennnnnnnnnnnnnnnnnnnnnnnnnnnnnne 517 FS ENTRY INFO ee edel ee ENN 518 FS FAT SYS CFG EE 520 FS PARTITION ENN BE creatii Eder s 522 FS VOLAINFO egene eege gege dE 523 HC FS Configuration cccccccesssenceeeeeseeeeeeeeeceeeeeeeseeeeeeesseeeneeeeseeeneeeeeess 525 File System Configuration eccccccesseecceceseeeeeeeeeeeeeeeeeeseeeeeeeeseeneeeenseeees 526 Feature Inclusion Configuration cccceseeecceeseseeeeeeeeeeneeeeeeeseeneeeeeeeeees 527 Name Restriction Configuration cccccseeecceseseeeeeeeeseeeeseeseseeeneeeeeeeees 530 Debug Configuration ccccecseecceeeeseeeeeeeeeeeeeseeeeeseeeeeeeeseeeeseeeeeeenseeeeeeees 531 Argument Checking Configuration EEN 531 E 6 E 7 E 8 E 9 Appendix F F 1 F 2 F 3 F 3 1 F 3 2 F 3 3 F 3 4 F 3 5 F 3 6 F 3 7 F 3 8 F 3 9 F 3 10 F 3 11 F 3 12 F 3 13 F 3 14 F 3 15 F 3 16 F 3 17 F 4 Appendix G Appendix H H 1 H 1 1 H 1 2 H 1 3 H 1 4 File System Counter Configuration ccccccesseeeeesseeeeseeeeseeeeeeeeeeeees 532 Fat CONTIQUIATION aaa e aaan raae e a a dea aaa e eae aaa aa aiaa 532 SD MMC SPI Configuration ccccceeesseeeeeeeeeeeeeeeeeeeeeeeeeeeseeeeeeeeeeeenees 533 Trace Configuration
231. eeseeeeeeeesseaeeeeeeseaeeeeeeneaes 422 FSDev_IDE_BSP_GetModesSupported see ENKEN 423 FSDev_IDE_BSP_SetMode ccccssseecceeeeseeeceeeeeseeeeeeenseeeeeeenenees 424 FSDev_IDE_BSP_Dly400_1 ee 425 NAND Flash Physical Layer Driver secccssseeeeeeeeeseeeeeeeeseeeeeeeeeeenes 426 ADDON Rea E TE sake cd tea esac E va agree A E 429 C 6 2 C 6 3 C 6 4 C 6 5 C 6 6 C 6 7 C 6 8 C 6 9 C 7 C 7 1 C 7 2 C 7 3 C 7 4 C 7 5 C 7 6 C 7 7 C 7 8 C 7 9 C 8 Cc 9 C 9 1 C 9 2 C 9 3 C 9 4 C 9 5 C 9 6 C 10 C 10 1 C 10 2 C 10 3 C 10 4 C 10 5 C 10 6 C 11 C 12 C 12 1 C 12 2 C 12 3 ClOS6 d E E groe akin det ee Mee nec E E ees 431 ROR AG 6 i See nde Ee 432 RdSpare EE 434 WrP age iiczesececcnts ciessevevied eesttacnterteesanttetaeri se cdveneecetenteens se eg 435 WYS Pale aaae amaaa i e aa Ea aa iaaa aaa aAa aa adsresneadsauuaassdindeciseecedenvease 436 Kap eekleg geed 437 EraseBiK eege EE ed ie eae eis 438 lO Ctrl E 439 NAND Flash BSP 220 440 FSDev_NAND_BSP_Open ceeceseeeeseeeeeeeeeeeeeeeeseseeessneaneeeeeeeenees 441 FSDev_NAND_BSP_CloS ccssccceeeseeeeeeeeeeseeeeeeeeseaeeeeeneseaeeeeenenees 442 FSDev_NAND_BSP_ChipSelEn ccccccsssesceeeeseeeeeeeeeseeeeeeeenseees 443 FSDev_NAND_BSP_ChipSelDis ccccesssecceeeseeeeeeeeeseeeeeeeeeeeees 444 FSDev_NAND_BSP_RdDatal cccssssscceeeeseeeceeeeeseeeeeeenseaaeeeeenesees 445 FSDev_NAND_BSP_WYr
232. eeseseeeseeeeneeeeeeeenees 120 Driver Characterization ccccccceeceeeeeseeeseeeeeeeeeeeeeseeeeesseneeeeeeeeenens 121 IDE GE Der ege ENEE EEN 124 Files and DireCtories ereere aaae aeaa daa eaaa iaa daaa HAEE 124 Using the IDE CF Driver 0 cccccceeceseeeseeeeeeeceeeeeeeeeseseessseeeeeeeeeeenees 125 ATA True IDE Communication EEN 128 IDE BSP Ove ie W Reesen Eege NES Eed dee 131 Logical Device Driver een 133 MSG BL 134 13 1 13 2 Chapter 14 14 1 14 2 14 3 14 3 1 14 3 2 14 3 3 14 4 14 4 1 14 4 2 14 4 3 Chapter 15 15 1 15 2 15 3 15 3 1 15 3 2 15 3 3 15 4 15 4 1 15 4 2 15 5 15 5 1 15 5 2 15 5 3 15 5 4 15 5 5 Chapter 16 16 1 16 2 Chapter 17 Files and Direc OES ug egen eeaeee geed e Eege len Ee 134 Using the MSC Driver osie taerak iaaa aE Aai aE E aE TA 135 NAND Flash DAV E 137 Files ANd Directortes e aerar eaaa ea a aae aa A aa ik aa daa aiana nania 138 Driver amp Device Characteristics sssssssssusnsnnnnnnnnnrnrnrnnrennnnnnennnnnnnn ek 139 Using a NAND Device Software ECC REENEN 140 Driver Architecture eege dE aada a adaa aai iiaiai 146 Hardware a a a a a a a EE edel 146 NAND BSP Overview ssssssssesesssnnnnnnnnnnnununnnnnnnnnnnnnnnnennnnnnnnnennnnnnennnn nnna 148 Physical Layer Drivers ccsseccccceseeeeeeeeeeeeeeeeeeeseeeeeeeeeeeseeeeeseaeseeeeeenes 148 WIRE TIVTISRACNER AT 149 FSDev_NAND_2048x08 FSDev_NAND_2048x16 0000seee 149 FSDevi NANDVAT4 eg
233. el String buffer that will receive volume label len max Size of string buffer p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Label gotten FS_ERR_DEV_CHNGD Device has changed FS_ERR_NAME NULL Argument name vol passed a NULL pointer FS_ERR_NULL PTR Argument label passed a NULL pointer FS_ERR_DEV Device access error FS_ERR VOL LABEL NOT FOUND Volume label was not found FS ERR VOL LABEL TOO LONG Volume label is too long FS_ERR_VOL_NOT MOUNTED Volume is not mounted FS ERR VOL NOT OPEN Volume is not open 325 LC FS API Reference Manual REQUIRED CONFIGURATION None NOTES WARNINGS len_max is the maximum length string that can be stored in the buffer label it does NOT include the final NULL character The buffer label MUST be of at least len max 1 characters 326 A 7 10 FSVol_LabelSet LC FS API Reference Manual void FSVol_LabelSet CPU CHAR name vol CPU CHAR label FS_ERR p err File Called from Code enabled by fs_vol c not FS_CFG_RD_ONLY_EN Application Set volume label ARGUMENTS name_vol Volume name label Volume label p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Label set FS_ERR_DEV_CHNGD FS_ERR_NAME_NULL FS_ERR_NULL PTR FS_ERR_DEV FS ERR DIR FULL FS ERR DEV FULL FS ERR VOL LABEL INVALID FS ERR VOL LABEL TOO LONG FS ERR VOL MOT MOUNTED FS ERR VOL NOT
234. en FS_ ERR VOL NOT MOUNTED Volume not mounted RETURNED VALUE None NOTES WARNINGS None 338 A 8 3 FSVol_CacheFlush LC FS API Reference Manual void FSVol_CacheFlush CPU_CHAR name vol FS_ERR p err File Called from Code enabled by fs_vol c FS_CFG_CACHE EN Application Flush cache on a volume ARGUMENTS name_vol Volume name p_err FS_ERR_NONE FS ERR NAME NULL FS ERR DEV CHNGD FS ERR VOL NO CACHE FS ERR VOL NOT OPEN FS_ERR_VOL MOT MOUNTED FS ERR DEV INVALID SEC NBR FS ERR DEV INVALID 10W FMT FS ERR DEV IO FS ERR DEV TIMEOUT FS ERR DEV NOT PRESENT RETURNED VALUE None NOTES WARNINGS None Pointer to variable that will receive return error code from this function Cache created name_vol passed a NULL pointer Device has changed No cache assigned to volume Volume not open Volume not mounted Sector start or count invalid Device needs to be low level formatted Device I O error Device timeout error Device is not present 339 A 9 NAND DRIVER FUNCTIONS LC FS API Reference Manual void FSDev_NAND LowFmt CPU_CHAR name dev FS_ERR p err void FSDev_NAND LowMount CPU_CHAR name dev FS_ERR p err void FSDev_NAND LowUnmount CPU_CHAR name dev FS_ERR p err void FSDev_NAND PhyRdSec CPU_CHAR name dev void p dest void p spare FS_SEC_NBR sec _nbr phy FS_ERR p err void FSDev_NAND PhyWrSec CPU_CHAR name
235. en 512 2048 or 4096 bytes and a spare area often 1 32 the size of the data area The page is fundamentally the smallest programmable unit but some devices allow several program operations per page between erases NAND flash experience occasional bit errors where one or more bits stored are flipped upon retrieval An error correcting code ECC is required so software can correct these bit errors or take appropriate measures if too many errors occur A single bit error correcting code per 512 bytes of data is sufficient for single level cell SLC flash The driver RAM requirement depends on flash parameters such as block size and run time configurations such as sector size Typical cases can be found in the datasheet 14 3 USING A NAND DEVICE SOFTWARE ECC To use the NAND driver five files in addition to the generic file system files must be included in the build E fs dev_nand c E fs dev nand bh E fs dev nand bsp c located in the user application or BSP E A physical layer driver typically one provided in Micrium Software uC FS Dev NAND PHY The file fs_dev_nand h must also be included in any application or header files that directly reference the driver for example by registering the device driver The following directories must be on the project include path E Micrium Software uC FS Dev NAND E Micrium Software uC FS Dev NAND PHY A single NAND volume is opened as shown in Listing 14 1 The file system initializat
236. en the volume is later accessed the file system will attempt to refresh the device information and detect a file system see section 5 2 Using Devices on page 69 for more information FSVol_Open opens mounts a volume The parameters are the volume name 2a the device name 2b and the partition that will be opened 2c There is no restriction on the volume name 2a however it is typical to give the volume the same name as the underlying device If the default partition is to be opened or if the device is not partition then the partition number 2c should be zero High level format can be applied to the volume if FS ERR PARTITION NOT FOUND is returned by the call to FSVol_Open function If the IDE initialization succeeds the file system will produce the trace output as shown in Figure 11 1 Gf a sufficiently high trace level is configured See section E 9 Trace Configuration on page 534 about configuring the trace level Terminal 1 0 Output Log file Off Adding opening IDE volume ide 0 IDE CF FOUND Name ide 0 Secs 7831152 size 3823 MB Su 41403829400000200201 PN Rev 20070918 Model LEXAR ATA FLASH CARD opened device F Partition_RdEntry Found possible partition Start 0 sector Size 0 sectors Type 00 FS_FAT_Open File system found Type FAT32 Sec size 512 B Clus size 6 sec Vol size 7831153 sec Clus 976981 FATs i2 opened volume mounte
237. encce cecetee evens enedenduncctieaseteesesecengeae 76 USING VOLUMES E 77 Using Volume Cache ccccceeseeeceeeeeeeeeeeeneeneesenseeeneeeeeneeneeeseeneseeeeeseesnaees 79 Choosing Cache Parameters ccesseescceeeseeeeeeeeeeeeeeeeeeseeeeeeeeeseneeeeneeee 80 Other Caching amp Buffering Mechanisms cccssseeesseeeeeeeeseeeeeneees 82 Ets 83 SUPPOrted FUNCTIONS eeneg ceed dace see ae eaaa a aaae a ra a ana SE 84 Working Directory Functions ssssssssseseunnennnnnnrnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn nna 85 File Access FUN IONS ae a aeaa araa eaaa aaraa aa dta eae aaas sanaaa naana 86 Opening Reading amp Writing Files 2 0 eeeeesesesseeeeeeeeeeeeeeeeesseeeeeeeeeeees 87 Getting or Setting the File Position eceeceseseeeeeeeeeseeeeeeeeeeeeneeeeeenees 90 Configuring a File Buffer ccccccssseerceeeeeneeeeeeeeeeeeeeeeeseeeeeeeeeseenseeeeeeees 91 Diagnosing a File Error csseccccssseeeeeeeeeeeeeeeeeeeeneeseeseeneeeseeseeneeeeeenseneeees 93 Atomic File Operations Using File LOCK REENEN 93 Directory ACCESS FUNCTIONS REENEN EEN 94 Entry Access FUNCTIONS i cccteicictcensnccieceessteicvesenstsictevnensivedssantenseesenntcies 96 el 97 File Access FUNCTIONS sgeesg reet maa aa aaa ENNER Eege dE 98 Opening Files saarra oae Eege EES sfecueees Soeceteca seus 99 7 1 2 7 1 3 7 1 4 7 1 5 7 2 7 2 1 7 2 2 7 2 3 Chapter 8 8 1 Chapter 9 9 1 9 1 1 9 1 2 9 1 3 9 1 4 9 2 9 2 1 9 2 2 9 2 3 Chapter 10 10 1
238. er be deleted with FS OS SemDel FS OS SemPost signals the semaphore with or without timeout and FS OS SemPend waits until the semaphore is signaled On systems without an OS kernel the trivial implementations in Listing C 4 are recommended CPU_BOOLEAN FS_OS SemCreate FS_BSP_SEM p sem 1 CPU_INT16U cnt p sem cnt Create semaphore with initial count cnt return DEF_OK CPU_BOOLEAN FS_OS SemDel FS_BSP_SEM op sem 2 p sem Ou Delete semaphore return DEF_OK Listing C 4 FS_OS_Sem trivial implementations 391 LUC FS Porting Manual CPU_BOOLEAN FS _OS_SemPend FS_BSP_SEM p_sem 3 CPU_INT32U timeout CPU_INT32U timeout_cnts CPU_INT16U sem val CPU_SR_ALLOC if timeout 0u sem val 0u while sem val 0u CPU_CRITICAL ENTER sem val p sem If semaphore available if sem val gt 0u p sem sem val lu Z decrement semaphore count uf CPU_CRITICAL EXIT else timeout_cnts timeout FS _BSP_CNTS_PER_MS sem_val 0 while timeout_cnts gt 0u amp amp sem_val 0u CPU_CRITICAL ENTER sem val p sem If semaphore available if sem val gt 0 p sem sem val lu Z decrement semaphore count E CPU_CRITICAL EXIT timeout_cnts if sem val 0u return DEF_FAIL else return DEF_OK Listing C 5 FS_OS_Sem trivial implementations contin
239. er of files and directories that can be located in the root directory FAT Type The type of FAT This should be 12 for FAT12 16 for FAT16 or 32 for FAT32 Ths choice of FAT type must observe restrictions on the maximum number a clusters A FAT12 file system may have no more than 4085 clusters a FAT16 file system no more than 65525 520 LIC FS Types and Structures NbrFATs The number of actual FATs file allocation tables to create on the disk The typical value is 2 one for primary use a secondary for backup NOTES Further restrictions on the members of this structure can be found in Chapter 9 File Systems FAT on page 109 521 LIC FS Types and Structures D 9 FS_PARTITION_ENTRY typedef struct fs_partition_entry FS_SEC_NBR Start FS SEC OTY Size CPU_INTO8U Type FS_PARTITION ENTRY File Used for fs_partition h Third argument of FSDev_PartitionFind Receives information about a partition entry MEMBERS Start The start sector of partition Size The size of partition in sectors Type The type of data in the partition NOTES None 522 D 10 FS _VOL_INFO typedef struct fs_vol_ info PG STATE State PG STATE DevState FS SEC OTY DevSize FS_SEC_ SIZE DevSecSize FS SEC OTY PartitionSize FS SEC ON VolBadSecCnt FS GEC OI VolFreeSecCnt FS _SEC_OTY VolUsedSecCnt FS SEC QTY VolTotSecCnt FS_VOL_INFO File LIC FS Types and Structures Used for fs_vol h
240. er to buffer mode Buffer mode FS__IONBR Unbuffered FS__IOFBF Fully buffered size Size of buffer in octets RETURNED VALUE 1 if an error occurs 0 if no error occurs 245 LC FS API Reference Manual NOTES WARNINGS 1 f s_setvbuf MUST be used after a stream is opened but before any other operation is performed on stream 2 size MUST be more than or equal to the size of one sector it will be rounded DOWN to the nearest size of a multiple of full sectors 3 Once a buffer is assigned to a file a new buffer may not be assigned nor may the assigned buffer be removed To change the buffer the file should be closed and re opened 4 Upon power loss any data stored in file buffers will be lost 246 A 3 DEVICE FUNCTIONS LC FS API Reference Manual Most device access functions can return any of the following device errors PG ERR DEV INVALID LOW FMT Device needs to be low level formatted FS_ERR_DEV Device access error FS_ERR_DEV_IO Device I O error FS_ERR_DEV NOT OPEN Device is not open FS_ERR_DEV_ NOT PRESENT Device is not present FS_ERR_DEV_ TIMEOUT Device timeout error Each of these indicates that the state of the device is not suitable for the intended operation void FSDev_Close CPU_CHAR FS ERR name_dev p err FS PARTITION NBR FSDev_GetNbrPartitions CPU_CHAR name_dev FS_ERR p err void FSDev_GetDevName FS_OTY dev_nbr CPU_CHAR name_dev FS
241. erial flash memories DataFlash as described in various datasheets at Atmel http www atmel com This driver has been tested with or should work with the devices in the table below While their underlying flash technology is NOR type the AT45 series devices are organized in a typical NAND like way each page of the device has a data area and a smaller spare area No matter which AT45 series device is used the physical layer driver advertises its page size as 512 bytes consequently the driver MUST be configured with a 512 byte sector size Device Capacity Device Page Size Device Page Manufacturer Count Atmel AT45DB161D 16 Mb 512 byte 4096 Atmel AT45DB321D 32 Mb 512 byte 8192 Atmel AT45DB641D 64 Mb 1024 byte 8192 Table 14 4 Supported AT45 serial flash 150 Chapter 19 NOR Flash Driver NOR flash is a low capacity on board storage solution Traditional parallel NOR flash located on the external bus of a CPU offers extremely fast read performance but comparatively slow writes typically performed on a word by word basis Often these store application code in addition to providing a file system The parallel architecture of traditional NOR flash restricts use to a narrow class of CPUs and may consume valuable PCB space Increasingly serial NOR flash are a valid alternative with fast reads speeds and comparable capacities but demanding less of the CPU and hardware being accessed by SPI or SPI like
242. erminal I O window within your debugger or a serial port When porting a driver to a new platform this information can be used to debug the fledgling port Trace Level Meaning TRACE LEVEL OFF No trace TRACE LEVEL INFO Basic event information e g volume characteristics TRACE LEVEL DBG Debug information TRACE LEVEL LOG Event log Table E 9 Trace Levels 534 Appendix Shell Commands The command line interface is a traditional method for accessing the file system on a remote system or in a device with a serial port be that RS 232 or USB A group of shell commands derived from standard UNIX equivalents are available for uC FS These may simply expedite evaluation of the file system suite or become part a primary method of access or gathering debug information in your final product E COM4 PuTTY C LIB drw rw rw 07 2 54 uc CPU cd uC LIB Doc jun 0 jun 0 jun 0 jun 07 pat jun D jun D jun 0 C LIB Manual pdt Figure F 1 pC FS shell command usage 535 Shell Commands F 1 FILES AND DIRECTORIES uC FS with the shell commands and uC Shell is organized into the directory structure shown in Figure F 2 The files constituting the shell commands ares outlined in this section the generic file system files outlined in Chapter 3 Directories and Files on page 28 are also required Micrium amp Software uc cpu E uc crc 3 O uc rs CH APP a O BsP E O crc
243. etDevName void FSDev_GetDevName FS QTY dev_nbr CPU_CHAR name dev File Called from Code enabled by fs_dev c Application N A Get name of the nth open device n should be between O and the return value of FSDev_GetNbrDevs inclusive ARGUMENTS dev_nbr Device number name dev String buffer that will receive the device name see Note 2 RETURNED VALUE None NOTES WARNINGS 1 name dev MUST point to a character array of FS_CFG MAX DEV NAME LEN characters 2 If the device does not exist name_dev will receive an empty string 250 LC FS API Reference Manual A 3 3 FSDev_GetDevCnt FS OI FSDev_GetDevCnt void File Called from Code enabled by fs_dev c Application N A Gets the number of open devices ARGUMENTS None RETURNED VALUE Number of devices currently open NOTES WARNINGS None 251 LC FS API Reference Manual A 3 4 FSDev_GetDevCntMax FS OTY FSDev_GetDevCntMax void File Called from Code enabled by fs_dev c Application N A Gets the maximum possible number of open devices ARGUMENTS None RETURNED VALUE Maximum number of open devices NOTES WARNINGS None 252 LC FS API Reference Manual A 3 5 FSDev_GetNbrPartitions FS PARTITION NBR FSDev_GetNbrPartitions CPU_CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev c Application FS_CFG_PARTITION_EN Get number of partitions on a device ARGU
244. eturn error is FS_ERR_NONE and the return value a is DEE MO then the same device e g SD card is still inserted The application can continue to access open files directories and volumes E If the return error is neither FS_ERR_NONE nor FS_ERR_DEV_INVALID LOW FMT then no functioning device is present The device must be refreshed at a later time A device can be refreshed explicitly with FSDev_Refresh however refresh also happens automatically If a volume access e g FSVol_Fmt FSVol_Rd entry access FSEntry Create fs_remove file open fs _fopen or FSFile Open or 71 Devices and Volumes directory open s_opendir or FSDir_Open is initiated on a device that was not present at the last attempted access uC FS attempts to refresh the device information if that succeeds it attempts to refresh the volume information Files and directories have additional behavior If a file is opened on a volume and the underlying device is subsequently removed or changed all further accesses using the file API e g FSFile_Rd will fail with the error code FS_ERR_DEV_CHNGD all POSIX API functions will return error values The file should then be closed to free the file structure Similarly if a directory is opened on a volume and the underlying device is subsequently removed or changed all further FSDir_Rd attempts will fail with the error code FS_ERR_DEV_CHNGD fs_readdir_r will return 1 The directory shou
245. evice is already open Device needs to be low level formatted Specified device name not valid Invalid device sector size Invalid device size Specified unit number invalid Device I O error No devices available Device is not present Device timeout error Unknown device error Argument name_dev passed a NULL pointer 254 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS 1 The return error code from the function SHOULD always be checked by the calling application to determine whether the device was successfully opened Repeated calls to FSDev_Open resulting in errors that do not indicate failure to open such as FG ERR DEV_LOW_FMT INVALID without matching FSDev_Close calls may exhaust the supply of device structures a If FS_ERR_NONE is returned then the device has been added to the file system and is immediately accessible b If FS_DEV_INVALID LOW_FMT is returned then the device has been added to the file system but needs to be low level formatted though it is present c If FS_ERR DEV NOT PRESENT FS ERR DEV_IO or FS ERR DEV TIMEOUT is returned then the device has been added to the file system though it is probably not present The device will need to be either closed and re added or refreshed d If FS_ERR_DEV_INVALID_NAME FS ERR DEV INVALID SEC SIZE FS_ERR DEV INVALID SIZE FS_ERR DEV INVALID UNIT NBR or FS_ERR_DEV_NONE AVAIL is returned then the device has NOT been added to t
246. fg FS_ERR p err void FSVol_GetDf1tVolName CPU_CHAR name_ vol FS oi FSVol_GetVolCnt void FS_OTY FSVol_GetVolCntMax void void FSVol_GetVolName PS ON vol_nbr CPU_CHAR name_ vol CPU_BOOLEAN FSVol_IsMounted CPU_CHAR name_ vol void FSVol_LabelGet CPU_CHAR name_vol CPU_CHAR label CPU_SIZE T len_max FS_ERR p err void FSVol_LabelSet CPU_CHAR name_ vol CPU_CHAR label FS_ERR p err void FSVol_Open CPU_CHAR name_vol CPU_CHAR name_dev FS PARTITION NBR FS ERR partition_nbr p err 314 LC FS API Reference Manual void FSVol_Query CPU_CHAR name_vol FS_VOL_ INFO p info FS_ERR p err void FSVol_Rd CPU_CHAR name_vol void p dest FS_SEC_NBR start FS_SEC_OTY cnt FS_ERR p err void FSVol_Wr CPU_CHAR name_vol void p src FS_SEC_NBR start FS_SEC_OTY cnt FS_ERR p err 315 A 7 1 FSVol_Close void FSVol Close CPU_CHAR name vol LC FS API Reference Manual FS_ERR p err File Called from Code enabled by fs_vol c Application Close and free a volume ARGUMENTS name_vol Volume name Pointer to variable that will receive See Note 2 p_err FS_ERR_NONE FS ERR NAME NULL FS ERR VOL NOT OPEN RETURNED VALUE None NOTES WARNINGS None N A the return error code from this function Volume opened Argument name_vol passed a NULL pointer Volume not open 316 LC FS API Reference Manual
247. file or directory writable or read only and visible or hidden Creation Time and Creation Date are the time and date when the entry was created Access Date is the date on which the file was last accessed Write Time and Write Date are the time and date when the entry was last modified 1st Cluster High and 1st Cluster Low contain the first cluster containing the file s data File Size is the file size in octets If the entry is a directory this is blank 4 8 12 16 Name Am NT Crt Creation res ms Time H st st Creation T Cluster Write Time Write Date 1 Cluster File Size Date High Low Figure 9 2 FAT Directory Entry SFN Entry Within uC FS these are called Short File Name entries or SFN entries 112 File Systems FAT 4 8 12 16 o PE bn Chk 0x42 o p 0x0000 OxFFFF 0x0F 0x00 Sim OxFFFF OxFFFF OxFFFF OxFFFF OxFFFF OxFFFF 0x0000 OxFFFF OxFFFF 0x01 a b 7 d e 0x0F 0x00 Si P sum o h D n Ae 0x0000 p m a p e l p me p 0x0010x00 Crt Creation ms Time D st st Creation Access 1 Cluster Write Time Write Date 1 Cluster File Size Date Date High Low Figure 9 3 LFN Directory Entry To extend FAT for longer names Microsoft devised the LFN directory entry as shown in Figure 9 2 Thirteen characters overlay the fields in a traditional SFN entry in addition to seve
248. file system initialization FS_Init function must have previously been called ROM RAM characteristics and performance benchmarks of the RAM disk driver can be found in section 10 1 1 Driver Characterization on page 121 For more information about the FS_DEV_ RAM CFG structure see section D 5 FS_DEV_RAM_CFG on page 516 define APP CFG FS RAM SEC SIZE 512 1 define APP CFG FS RAM NBR_SECS 48 1024 static CPU_INT32U App FS RAM Disk APP_CFG FS_RAM_SEC_SIZE APP CFG FS RAM NBR_SECS 4 CPU_BOOLEAN App FS AddRAM void FS_ERR err FS_DEV_RAM CFG cfg FS_DevDrvAdd FS_DEV_API amp FSDev_RAM 2 FS_ERR amp err if err FS_ERR_NONE amp amp err FS_ERR_DEV_DRV_ALREADY_ADDED return DEF_FAIL ram cfg SecSize APP_CFG FS RAM SEC_SIZE He 3 Su ram_cfg Size APP CFG FS_RAM NBR_SECS ram_cfg DiskPtr void amp App FS RAM Disk 0 171 RAM Disk Driver 4 FSDev_Open CPU_CHAR ram 0 a void amp ram cfg Z b PS ERR amp err if err FS_ERR_NONE return DEF FAIL EE S FSVol_Open CPU_CHAR ram 0 a CPU_CHAR ram 0 b FS PARTITION NBR 0 c FS_ERR amp err switch err case FS_ERR_NONE APP_TRACE_DBG Opened volume mounted r n break case FS _ERR_PARTITION_NOT FOUND Volume error Ss APP_TRACE_DBG opened device not formatted r n FSVol_Fmt
249. file with that name created 105 Files Similar functions exist to copy and rename an entry FSEntry_Copy dir sre txt lt source file name dir dest txt lt destination file name DEF_NO lt DEF_NO means creation not exclusive amp err lt return error FSEntry_ Rename dir oldname txt lt old file name dir newname txt lt new file name DEF_NO lt DEF_NO means creation not exclusive amp err lt return error FSEntry_Copy can only be used to copy files The first two arguments of each of these are both full paths the second path is not relative to the parent directory of the first As with FSEntry Create the third argument of each excl indicates whether the creation should be exclusive If it is exclusive excl is DEF_YES nothing will happen if the destination or new file already exists 7 2 3 DELETING FILES AND DIRECTORIES A file or directory can be deleted using FSEntry_Del FSEntry_Del dir lt entry name FS_ENTRY_TYPE DIR lt means entry must be a dir amp err lt return error The second argument entry_type restricts deletion to specific types If it is FS ENTRY TYPE DIR then the entry specified by the first argument must be a directory if it is a file an error will be returned If it is FS _ENTRY_TYPE FILE then the entry must be a file If it is FS_ENTRY_TYPE ANY then the entry will be deleted whether it is a file or
250. finitions Ca det bi Configuration definitions fs_cfg_fs h 25 LIC FS Architecture 2 1 5 FILE SYSTEM DRIVER LAYER The file system driver layer understands the organization of a particular file system type such as FAT The current version of uC FS only supports FAT file systems fs_fat contains the file system driver which should be used for FAT12 FAT16 FAT32 disks with or without Long File Name LFN support 2 1 6 DEVICE DRIVER LAYER The device driver layer understands about types of file system media SD MMC card NOR flash etc In order for the device drivers to be independent of your CPU we use additional files to encapsulate such details as the access of registers reading and writing to a data bus and setting clock rates Each device driver is named according to the pattern fs_dev_ lt dev drv name gt c where lt dev drv name gt is the an identifier for the device driver For example the driver for SD MMC cards using SPI mode is called fs_dev_sd_spi c Most device drivers require a BSP layer with code for accessing registers reading from or writing to a data bus etc This file is named according to the pattern fs_dev_ lt dev drv name gt _bsp c For example fs_dev_sd_spi_bsp c contains the BSP functions for the driver SD MMC cards using SPI mode 2 1 7 CPU LAYER uC FS can work with either an 8 16 32 or even 64 bit CPU but needs to have information about the CPU you are using The CPU layer defines such
251. format 6 bits 32 bits 7 bits Start bit Transmission bit End bit Response 0 0 Cmd ix Response CRC 1 format 6 bits 32 or 128 bits 7 bits 1 2 Figure 17 11 SD MMC SPI mode communication sequence F17 110 When no data is being transmitted DataOut line is held high F17 11 2 During busy signaling DataOut line is held low F17 11 3 The CRC is the 16 bit CCITT CRC By default this is optional and dummy bytes may be transmitted instead The card only checks the CRC if CRC_ON_OFF has been executed 194 SD MMC Drivers Start bit Transmission bit End bit Command Di Cmd ix Argument CRC 1 format 6 bits 32 bits 7 bits Start bit Address Out Of Range Block Length Error Address Misalign Erase Sequence Error Com CRC Error Illegal Command Switch Error Erase Reset ie In Idle State Response 0 Additional format r sponse if any Sl eS R1 Response Figure 17 12 SD MMC SPI mode command and response formats 195 SD MMC Drivers Power On o_o GO_IDLE STATE 1 Inactive state Invalid Valid command command SEND_IF_COND 2 Invalid y Vv command pees SD_SEND_OP_COND SD_SEND_OP_COND 3 3 D Vv g 3 D 3 8 SEND OP COND a KE READ_OCR 4 5 y y READ_OCR CCS in 5 response v v v MMC V1 x Standard V2 0 Standard V2 0 High Capacity SD card Capacity SD card
252. fs_od REQUIRED CONFIGURATION Available only if FS_SHELL_CFG_CAT_EN is DEF_ENABLED NOTES WARNINGS None 541 Shell Commands F 3 2 fs cd Change the working directory USAGES fs cd dir ARGUMENTS dir Absolute directory path OR Path relative to current working directory OUTPUT None REQUIRED CONFIGURATION Available only if FS_SHELL_ CFG CD EN is DEF_ENABLED NOTES WARNINGS The new working directory is formed in three steps 1 If the argument dir begins with the path separator character slash or a volume name it will be interpreted as an absolute directory path and will become the preliminary working directory Otherwise the preliminary working directory path is formed by the concatenation of the current working directory a path separator character and dir 542 Shell Commands The preliminary working directory path is then refined from the first to last path component a If the component is a dot component it is removed b If the component is a dot dot component and the preliminary working directory path is not NULL the previous path component is removed In any case the dot dot component is removed c Trailing path separator characters are removed and multiple path separator characters are replaced by a single path separator character The volume is examined to determine whether the preliminary working directory exists If it does it becomes the new working
253. hat will the receive return error code from the function FS_ERR_NONE File truncated successfully FS_ERR_NULL PTR Argument p file passed a NULL pointer FS_ERR_INVALID TYPE Argument p file s type is invalid or unknown PG ERR FILE NOT OPEN File NOT open RETURNED VALUE None NOTES WARNINGS None 311 A 6 17 FSFile Wr CPU_SIZE T FSFile Wr FS FILE void CPU SIZE_T FS_ERR File Called from uC FS API Reference Manual p file p src size p err Code enabled by fs file c Application fs fwrite Write to a file See fs_fwrite for more information not FS CFG RD ONLY EN ARGUMENTS p file Pointer to a file p srce Pointer to source buffer size Number of octets to write p err Pointer to variable that will the receive return error code from the function FS_ERR_NONE File write successfully FS_ERR_NULL PTR FS_ERR_INVALID TYPE FS ERR FILE NOT OPEN FS ERR FILE INVALID OP FS ERR DEV Argument p file p_ sre passed a NULL pointer Argument p file s type is invalid or unknown File NOT open Invalid operation on file Device access error 312 RETURNED VALUE The number of bytes written if file write successful 0 otherwise NOTES WARNINGS None LC FS API Reference Manual 313 A 7 VOLUME FUNCTIONS LC FS API Reference Manual void FSVol_Close CPU_CHAR name_vol FS_ERR p err void FSVol_Fmt CPU_CHAR name_vol void p fs c
254. he file system e If P ERR DEV UNKNOWN is returned then the device driver is in an indeterminate state The system MAY need to be restarted and the device driver should be examined for errors The device has NOT been added to the file system 255 LC FS API Reference Manual A 3 7 FSDev_PartitionAdd FS PARTITION NBR FSDev_ PartitionAdd CPU CHAR name dev FS _SEC_QTY partition size FS_ERR p err File Called from Code enabled by fs_dev c Application FS_CFG_PARTITION_EN and not FS CFG _RD ONLY EN Adds a partition to a device See also section 5 4 Partitions on page 72 ARGUMENTS name_dev Device name partition size Size in sectors of the partition to add p err Pointer to variable that will receive return error code from this function FS_ERR_NONE Partition added FS_ERR_INVALID PARTITION Invalid partition FS_ ERR INVALID SEC_NBR Sector start or count invalid PG ERR INVALID SIG Invalid MBR signature FS_ERR_NAME NULL Argument name_dev passed a NULL pointer Or device access error see section B 4 Device Error Codes on page 377 RETURNED VALUE The index of the created partition The first partition on the device has an index of 0 FS INVALID PARTITION NBR is returned if the function fails to add the partition NOTES WARNINGS Device state change will result from device I O not present or timeout error 256 LC FS API Reference Manual A 3 8 FSDev _PartitionFind void FSDev_Parti
255. hown in Figure 17 1 if a sufficiently high trace level is configured See section E 9 Trace Configuration on page 534 about configuring the trace level COM1 PuTTY Figure 17 1 SD MMC detection trace output 17 2 1 SD MMC CARDMODE COMMUNICATION In card mode seven nine or thirteen pins on the SD MMC device are used with the functions listed in the table below All cards start up in 1 bit mode upon entering identification mode which involves only a single data line Once the host the MCU MPU discovers the capabilities of the card it may initiate 4 or 8 bit communication the latter available only on new MMCs Some card holders contain circuitry for card detect and write protect indicators which the MCU MPU may also monitor Pin Name Type Description 1 CD DAT3 WO Card Detect Data Line Bit 3 2 CMD 1 0 Command Response 3 Vss1 S Supply voltage ground 4 VDD S Supply voltage 180 SD MMC Drivers Pin Name Type Description 5 CLK Clock 6 VSS2 S Supply voltage ground 7 DATO VO Data Line Bit 0 8 DAT VO Data Line Bit 1 9 DAT2 VO Data Line Bit 2 10 DAT4 1 0 Data Line Bit 4 11 DAT5 VO Data Line Bit 5 12 DAT6 1 0 Data Line Bit 6 13 DAT7 VO Data Line Bit 7 Table 17 2 SD MMC pinout Card Mode Only present in MMC cards Exchanges between the host and card begin with a command sent by the host on the CMD line often followed by a respons
256. ices are required to have unique names That requirement is enforced in this file system suite 59 Miscellaneous A logical device is the combination of two or more separate devices To form a logical device the sector address spaces of the constituent devices are concatenated to form a single continuous address space A device can be partitioned or subdivided into one or more regions called partitions each consisting of a number of consecutive sectors Typically structures are written to the device instructing software as to the location and size of these partitions This file system suite supports DOS partitions A volume is a device or device partition with a file system A device or device partition must go through a process called mounting to become a volume which includes finding the file system and making it ready for use The name by which a volume is addressed may also be called the volume s mount point A device or volume may be formatted to create a new file system on the device For disambiguation purposes this process is also referred to as high level formatting The volume or device will automatically be mounted once formatting completes For certain devices it is either necessary or desirable to perform low level formatting This is the process of associating logical sector numbers with areas of the device A file system driver is a code module which allows the general purpose file system suite to access a specific
257. igured including a Transfer unit length b Shift direction c Clock frequency d Clock polarity and phase CPOL and CPHA e Slave select polarity 3 For a SD MMC card the following settings should be used 499 LUC FS Porting Manual a Transfer unit length 8 bits b Shift direction MSB first c Clock frequency 400 kHz initially d Clock polarity and phase CPOL and CPHA CPOL 0 CPHA 0 e Slave select polarity active low The slave select SSEL or CS MUST be configured as a GPIO output it should not be controlled by the CPU s SPI peripheral The SPI port s ChipSelEn and ChipSelDis functions manually enable and disable the SSEL 500 LUC FS Porting Manual C 14 2 Close void FSDev_BSP_ SPI Close FS Om unit_nbr File Called from Code enabled by fs_dev_ lt dev_name gt _bsp c Device driver N A Close uninitialize hardware for SPI ARGUMENTS unit_nbr Unit number of device RETURNED VALUE None NOTES WARNINGS This function will be called every time the device is closed 501 LUC FS Porting Manual C 14 3 Lock Unlock void FSDev_BSP_SPI_Lock FS_QTY unit_ nbr void FSDev_BSP_SPI_ Unlock FS_QTY unit_nbr File Called from Code enabled by fs_dev_ lt dev_name gt _bsp c Device driver N A Acquire release SPI bus lock ARGUMENTS unit_nbr Unit number of device RETURNED VALUE None NOTES WARNINGS Lock will be called before the
258. ing Manual unit_nbr reg val Code enabled by fs_dev_ide_bsp c various Write to IDE CF device register ARGUMENTS unit_nbr Unit number of IDE CF device reg Register to read FS DEV IDE REG FR FS DEV_IDE REG SC FS DEV_IDE REG SN FS DEV_IDE REG CYL FS DEV_IDE REG CYH FS DEV_IDE REG DH FS DEV_IDE REG CMD FS DEV_IDE REG DEVCTRL val Value to write into register RETURNED VALUE None NOTES WARNINGS None N A Features Register Sector Count Register Sector Number Register Cylinder Low Register Cylinder High Register Card Drive Head Register Command Register Device Control Register 415 LUC FS Porting Manual C 5 7 FSDev_IDE_BSP_CmdWr void FSDev_IDE BSP _CmdWr FS Om unit_nbr CPU_INTO8U cmd File Called from Code enabled by fs_dev_ide bsp c FSDev_IDE_RdData N A FSDev_IDE WrData Write 7 byte command to IDE CF device registers ARGUMENTS unit_nbr Unit number of IDE CF device cmd Array holding command RETURNED VALUE None NOTES WARNINGS The 7 bytes of the command should be written to the IDE device registers as follows REG FR cmd 0 REG SC cmd 1 REG SN cmd 2 REG CYL cmd 3 REG CYN cmd 4 REG DH cmd 5 REG CMD cmd 6 416 LUC FS Porting Manual C 5 8 FSDev_IDE_BSP_DataRd void FSDev_IDE BSP DataRd FS Org unit_nbr void p dest CPU_SIZE T cnt File Called from Code enabled by fs_dev_ide_bs
259. ion FS Init function must have previously been called and the NAND device driver FSDev_NAND registered using FS_DevDrvAddO 140 NAND Flash Driver ROM characteristics and performance benchmarks of the NAND driver can be found in section 10 1 1 Driver Characterization on page 121 The NAND driver also provides interface functions to perform low level operations see section A 9 NAND Driver Functions on page 340 static CPU BOOLEAN App FS AddNAND void FS_DEV_NAND CFG nand cfg FS_ERR err FS _DevDrvAdd FS_DEV_API amp FSDev_NAND 1 FS_ERR amp err if err FS_ERR_NONE amp amp err FS_ERR_DEV_DRV_ALREADY ADDED APP_TRACE_DBG could not add driver w err d r n r n amp err return DEF_FAIL 2 nand cfg BlkNbrFirst APP_CFG FS NAND BLK NBR FIRST nand cfg BlkCnt APP CFG FS_NAND_BLK CNT nand cfg SecSize APP CFG FS_NAND_SEC_SIZE nand cfg RBCnt APP CFG FS_NAND_RB_CNT nand_cfg PhyPtr FS_DEV_NAND PHY API APP CFG FS NAND PHY PTR nand_cfg BusWidth APP CFG FS NAND BUS WIDTH nand_cfg MaxClkFreq APP CFG FS NAND MAX CLK FREQ 141 NAND Flash Driver IES JE Si FSDev_Open nand 0 a void amp nand_cfg Z b amp err switch err case FS_ERR_ NONE APP_TRACE_DBG opened device r n break case FS ERR DEV_INVALID LOW FMT APP_TRACE_DBG opened device not low level formatted r n if
260. iple instances of the same type of medium since all drivers are re entrant DOS partitions are supported so more than one volume can be located on a device In addition the logical device driver allows a single volume to span several typically identical devices such as a bank of flash chips FAT All standard FAT variants and features are supported including FAT12 FAT16 FAT32 and long file names which encompasses Unicode file names Files can be up to 4 GB and volumes up to 8 TB the standard maximum An optional journaling module provides total power fail safety to the FAT system driver Application Programming Interface API uC FS provides two APIs for file and directory access A standard POSIX compatible API is provided including functions like fs_fwriteO fs_freadO and fs_fsetposO that have the same arguments and return values as 16 Introduction the POSIX functions fwriteO freadOQ and fsetposOQ Another API with parallel argument placement and meaningful return error codes is provided as an alternate with functions like FSFile_WrO FSFile_RdO and FSFile_PosSetQ Scalable The memory footprint of pC FS can be adjusted at compile time based on the features you need and the desired level of run time argument checking For applications with limited RAM features such as cache and read write buffering can be disabled for applications with sufficient RAM these features can be enabled in order to gain better performance Por
261. ir Js_cache Js_entry Ze op fb Ss_err fs_ctr h Ss_file fs_def h Js_partition Js_pool SJs_sys ZG Done bh Js_unicode JSs_util Js_vol System Driver Layer CRC fx_fat fs fat _fatl2 fs_fat_sfn ede_ere fx fa dinn fx fat fatl6 _fx_fat_typeh ecc_hamming fs_fat_entry fx_fat_fat32 _fs_fat_journal a fx fat file fs fat_Ifn I Device Driver Layer IDE NOR Js_dev_ide Js_dev_nor NAND Js_dev_nand RAM Disk IS deu rom SD MMC IS deu si fs_dev_sd_spi IS deu al cord D D Vv CPU Layer Clk Layer Device Driver BSP RTOS Layer cpu_a asm clk Js_dev_ lt driver gt _bsp c Ss_os c h cpu h cpu_def h Time management Device RTOS Figure 2 1 pC FS architecture 23 LIC FS Architecture 2 1 ARCHITECTURE COMPONENTS uC FS consists of a set of modular software components It also requires a few external components provided with the release be compiled into the application and a few configuration and BSP files be adapted to the application 2 1 1 YOUR APPLICATION Your application needs to provide configuration information to uC FS in the form of one C header file named fs_cfg h Some of the configuration data in fs_cfg h consist of specifying whether certain features will be present For example LFN support volume cache and file buffering are all enab
262. isk or force a disk check upon unexpected power failure uC FS minimizes the problem by ordering modifications wisely The problem is completely solved in an optional journaling module which logs information about pending changes so those can be resumed on start up after a power failure 1 5 CHAPTER CONTENTS Figure 1 1 shows the layout and flow of the book This diagram should be useful to understand the relationship between chapters The first leftmost column lists chapters that should be read in order to understand uC F9 s structure The chapters in the second column give greater detail about the application of uC FS Each of the chapters in the third column examines a storage technology and its device driver Finally the fourth column lists the appendices the topmost being the uC FS reference configuration and porting manuals Reference these sections regularly when designing a product using uC FS 18 Introduction 8 SD MMC S H i Directories Driver Policy Figure 1 1 C FS Book Layout A uC Fs API Preface Reference Manual 1 B uC FS Error Codes 2 11 C IDE CF UES Driver M g anual Directories 3 Logical 12 D HCIES and Devices Types and Files Driver Structures 4 Mass Storage 13 E HCIES Class MSC Configuration Driver Manual Devices 3 9 NAND 14 and PALES Flash Volumes y Driver F uC FS e Shell EEN NOR Commands Drivers Blast Driver 7 16 G RAM Disk i
263. it is an empty directory 3 The root directory cannot be deleted 281 A 5 5 FSEntry_Query void FSEntry Query CPU_CHAR LC FS API Reference Manual name full FS_ENTRY_INFO p info i FS_ERR p err File Called from Code enabled by fs_entry c Application N A fs_stat Get information about a file or directory ARGUMENTS name full Name of the entry See section 4 3 uC FS File and Directory Names and Paths on page 62 p_info Pointer to structure that will receive the file information p err Pointer to variable that will the receive return error code from the function FS_ERR_NONE File information obtained successfully FS ERR NULL PTR FS ERR NAME INVALID FS ERR NAME PATH TOO LONG FS ERR VOL NOT OPEN FS ERR VOL MOT MOUNTED FS ERR BUF_NONE AVAIL FS ERR DEV RETURNED VALUE None Argument name full passed a NULL pointer Entry name specified invalid OR volume could not be found Entry name specified too long Volume was not open Volume was not mounted Buffer not available Device access error 282 LC FS API Reference Manual NOTES WARNINGS None 283 LC FS API Reference Manual A 5 6 FSEntry_Rename void FSEntry Rename CPU_CHAR name_full old CPU_CHAR name full new CPU_BOOLEAN excl FS_ERR p err File Called from Code enabled by fs_entry c Application not FS_CFG_RD_ONLY_EN fs_rename Rename a file or directory See also fs_rename ARGU
264. iver ECC fs_dev_nand_0512x08 Calculation fs_dev_nand_2048x08 Calculate fs_dev_nand_2048x16 and check ECC Implements particular NAND flash command set BSP fs_dev_nand_bsp c Access NAND via bus interface or GPIO Figure 14 2 NAND driver architecture 14 3 2 HARDWARE Parallel NAND devices typically connect to a host MCU MPU via an external bus interface EBD with a 8 or 16 data lines or via GPIO pins Many silicon vendors offer NAND product lines many new devices are conformant to the Open NAND Flash Interface ONFD A set of query information allows the uC FS NAND driver physical layer drivers to interface with these newer flash without configuration or modification most older flash can be handled based purely on device ID 146 e6eq moy gt NAND Flash Driver 1 Block n Pages EE Pin Input Output Description Chip Enable nCE O Enables access to a specific chip Several NANDs can be placed on the same bus if each has a separate chip enable Command Latch O Indicates that data is a command Enable CLE Address Latch O Indicates that data is an address Enable ALE Read Enable nRE Enables serial data output from NAND Write Enable nWE Controls latching of data input to NAND Read Busy R nB Indicates status of NAND operation Data Bus D0 D7 WO Used to write commands and addresses and to read write or DO D15 data Table 14 2 Pins st
265. ks simultaneously An OS kernel port leverages the kernel s mutual exclusion services mutexes for that purpose These files are generally placed in a directory named according to the following rubric Micrium Software uC FS 0S lt os_name gt Four sets of files are included with the pC FS distribution Micrium Software uC FS 0S Template Template Micrium Software uC FS 0S None No OS kernel port Micrium Software uC FS 0S uCOS II pC OS IL port Micrium Software uC FS OS uCOS III pC OS IIL port If you don t use any OS including a custom in house OS you should include the port for no OS in your project You must also make sure that you manage interrupts correctly If you are using pC OS II or pC OS HI you should include the appropriate ports in your project If you use another OS you should create your own port based on the template The functions that need to be written in this port are described here 386 LUC FS Porting Manual FS_OS_Init FS_OS_Lock and FS_OS_ Unlock The core data structures are protected by a single mutex FS OS Init creates this semaphore FS OS Lock and FS_OS Unlock acquire and release the resource Lock operations are never nested FS_OS_DevInit FS OS DevLock and FS OS DevUnlock File system device generally do not tolerate multiple simultaneous accesses A different mutex controls access to each device and information about it in RAM FS_OS DeviInit creates one mutex for ea
266. l E 3 NAME RESTRICTION CONFIGURATION Individual file system features may be selectively disabled Table E 7 Read only function exclusion continued These functions are NOT included if FS_CFG_RD_ONLY_EN is DEF_ENABLED FS_CFG MAX PATH NAME LEN FS CFG MAX PATH NAME LEN configures the maximum path name length in characters not including the final NULL character The default value is 260 the maximum path name length for paths on FAT volumes FS_CFG MAX FILE _NAME_LEN FS CFG MAX FILE NAME LEN configures the maximum file name length in characters not including the final NULL character The default value is 255 the maximum file name length for FAT long file names 530 UC FS Configuration FS_CFG MAX DEV_DRV_NAME_LEN FS CFG MAX DEV DRV NAME LEN configures the maximum device driver name length in characters not including the final NULL character The default value is 10 FS_CFG MAX DEV_NAME_ LEN FS_CFG MAX DEV NAME LEN configures the maximum device name length in characters not including the final NULL character The default value is 15 FS_CFG MAX VOL NAME LEN FS CFG MAX VOL NAME LEN configures the maximum volume name length in characters not including the final NULL character The default value is 10 E 4 DEBUG CONFIGURATION A fair amount of code in uC FS has been included to simplify debugging There are several configuration constants used to aid debugging FS_CFG_DBG_MEM CLR_EN FS_CFG DBG MEM CLR
267. lable the function returns an error See fs_flockfile 228 LC FS API Reference Manual A 2 19 fs_funlockfile void fs funlockfile FS_FILE p file File Called from Code enabled by fs_api c Application FS_CFG AGT EN and FS_CFG FILE LOCK EN Release task ownership of a file ARGUMENTS p file Pointer to a file RETURNED VALUE None NOTES WARNINGS See fs_flockfile 229 A 2 20 fs_fwrite fs_size t fs _fwrite void fs_ size_t fs_ size_t FS FILE File Called from LC FS API Reference Manual p src size nitems p file Code enabled by fs_api c Application Write to a file ARGUMENTS p sre Pointer to source buffer size Size of each item to write nitems Number of items to write p file Pointer to a file RETURNED VALUE Number of items written NOTES WARNINGS FS_CFG_API_EN and not FS_CFG_RD ONLY_EN 1 The size or nitems is 0 then the file is unchanged and zero is returned 2 If the file is buffered and the last operation is input read then a call to fs_fsetpos or fs_fseek MUST occur before output write can be performed unless the end of file was encountered 3 The file must have been opened in write or update read write mode 4 If the file was opened in append mode all writes are forced to the end of file 230 LC FS API Reference Manual A 2 21 fs_getcwd char fs_getcwd char path dir fs size t size File Called from Co
268. ld then be closed to free the directory structure 5 4 PARTITIONS A device can be partitioned into two or more regions and a file system created on one or more of these each of which could be mounted as a volume uC FS can handle and make DOS style partitions which is a common partitioning system The first sector on a device with DOS style partitions is the Master Boot Record MBR with a partition table with four entries each describing a partition An MBR entry contains the start address of a partition the number of sectors it contains and its type The structure of a MBR entry and the MBR sector is shown in Figure 5 4 4 8 12 16 Flag Start CHS Addr Type End CHS Addr Start LBA Addr Size in Sectors Figure 5 3 Partition entry format 72 Devices and Volumes Boot Code 448 1 Entry 2 Entry 3 Entry 4 Entry 464 480 496 Signature OxAA55 Figure 5 4 Master Boot Record An application can write an MBR to a device and create an initial partition with FSDev_PartitionInit For example if you wanted to create an initial 256 MB partition on a 1 GB device ide 0 FSDev_PartitionInit CPU_CHAR ide 0 lt a device name FS_SEC QTY 512 1024 lt b size of partition FS_ERR Serr lt C return error The parameters are the device name a and the size of the partition in sectors b If b is 0 then the partition will take up
269. ld work with the devices in the table below The M25P series devices are programmed on a page 256 byte basis and erased on a sector 32 or 64 KB basis The M25PE series devices are also programmed on a page 256 byte basis but are erased on a page subsector 4 KB or sector 64 KB basis Manufacturer Device Capacity Block Size Block Count ST M25P10 1 Mb 64 KB 2 ST M25P20 2 Mb 64 KB 4 ST M25P40 4 Mb 64 KB 8 ST M25P80 8 Mb 64 KB 16 ST M25P16 16 Mb 64 KB 32 ST M25P32 32 Mb 64 KB 64 ST M25P64 64 Mb 64 KB 128 ST M25P128 128 Mb 64 KB 256 ST M25PE10 1 Mb 64 KB 2 ST M25PE20 2 Mb 64 KB 4 ST M25PE40 4 Mb 64 KB 8 ST M25PE80 8 Mb 64 KB 16 ST M25PE16 16 Mb 64 KB 32 Table 15 7 Supported M25 serial flash 168 NOR Flash Driver 15 5 5 FSDEV_NOR_SST25 FSDev_NOR_SST25 supports SST s SST25 serial flash memories as described in various datasheets at Numonyx http www numonyx com This driver has been tested with or should work with the devices in the table below The M25P series devices are programmed on a word 2 byte basis and erased on a sector 4 KB or block 32 KB basis The revision A devices and revision B devices differ slightly Both have an Auto Address Increment AAI programming mode In revision A devices the programming is performed byte by byte in revision B devices word by word Revision B devices can also be erased on a 64 KB block basis and support a command to read a
270. le Called from Code enabled by fs_dev_nor c Application N A Low level unmount a NOR device ARGUMENTS name_dev Device name see Note p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Device low level unmounted successfully FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_DEV_INVALID Argument name dev specifies an invalid device FS_ERR_DEV_NOT_OPEN Device is not open FS_ERR_DEV_NOT_PRESENT Device is not present FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NOR device e g nor 0 Low level unmounting clears software knowledge of the on disk structures forcing the device to again be low level mounted or formatted prior to further use 354 LC FS API Reference Manual A 10 4 FSDev_NOR_LowCompact void FSDev NOR LowCompact CPU_CHAR name dev FS_ERR p err File Called from Code enabled by fs_dev_nor c Application N A Low level compact a NOR device ARGUMENTS name_dev Device name see Note p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Device low level compacted successfully FS ERR NAME NULL Argument name_dev passed a NULL pointer FS ERR DEV_INVALID Argument name_dev specifies an invalid device PG ERR DEV MO ODEN Device is not open PG ERR DEV MO PRESENT Device is
271. le E 4 File lock function exclusion These functions are NOT included if FS_CFG_FILE_LOCK_EN is DEF_DISABLED FS_CFG_PARTITION_EN When FS_CFG PARTITION EN is enabled DEF_ENABLED volumes can be opened on secondary partitions and partitions can be created When it is disabled DEF_DISABLED volumes can be opened only on the first partition and the functions in the following table will not be available The function FSDev_PartitionInit which initializes the partition structure on a volume will be included in both configurations Function File FSDev_GetNbrPartitions fs_dev c FSDev_PartitionAdd fs_dev c FSDev_PartitionFind fs_dev c Table E 5 Partition function exclusion These functions are NOT included if FS_CFG_PARTITION_EN is DEF_DISABLED 528 UC FS Configuration FS_CFG WORKING DIR EN When FS_CFG_ WORKING DIR EN is enabled DEF_ENABLED file system operations can be performed relative to a working directory When it is disabled DEF_DISABLED all file system operations must be performed on absolute paths and the functions in the following table will not be available Function File fs_chdir fs api c fs_getcwd fs api c FS_WorkingDirGet fs h FS_WorkingDirSet fs h Table E 6 Working directory function exclusion These functions are NOT included if FS_CFG_WORKING_DIR_EN is DEF_DISABLED FS_CFG_UTF8_EN FS CFG UTF8 EN selects whether file names may be specified in UTF 8 When enab
272. led DEF ENABLED file names may be specified in UTF 8 when disabled DEF_DISABLED file names must be specified in ASCII FS_CFG_CONCURRENT_ENTRIES_ACCESS_EN FS _CFG CONCURRENT ENTRIES ACCESS EN selects whether one file can be open multiple times in one or more task When enabled DEF_ENABLED files may be open concurrently mutliple times and without proection When disabled DEF_DISABLED files may be open concurrently only in read only mode but may not be open concurrently in write mode This option makes the filesystem safer when disabled FS_CFG_ RD ONLY EN FS CFG RD ONLY EN selects whether write access to files volumes and devices will be possible When DEF_ENABLED files volumes and devices may only be read code for write operations will not be included and the functions in the following table will not be available Function File fs fwrite fs api c fs_remove fs api c fs_rename fs api c 529 UC FS Configuration Function File fs_mkdir fs api c fs_truncate fs api c fs_rmdir fs api c FSDev_PartitionAdd fs_dev c FSDev_PartitionInit fs deu FSDev_Wr fs deu FSEntry AttribSet fs entry FSEntry_Copy fs_ entry FSEntry_ Create fs_ entry FSEntry_TimeSet fs_ entry FSEntry_ Del fs_ entry FSEntry_ Rename fs_ entry FSFile_Truncate fs file c FSFile Wr fs file c FSVol_Fmt fs _vol c FSVol_LabelSet fs _vol c FSVol_Wr fs vo
273. led or disabled in this file In all there are about 30 define to set However most of these can be set to their default values 2 1 2 LIB LIBRARIES Because uC FS is designed to be used in safety critical applications all standard library functions like strepy memset etc have been re written to follow the same quality as the rest of the file system software 2 1 3 POSIX API LAYER Your application interfaces to pC FS using the well known stdio h API Application Programming Interface Alternately you can use uC FS s own file and directory interface functions Basically POSIX API layer is a layer of software that converts POSIX file access calls to uC FS file access calls 2 1 4 FS LAYER This layer contains most of the CPU RTOS and compiler independent code for uC FS There are three categories of files in this section 1 File system object specific files E Devices fs_dev 24 LIC FS Architecture Directories fs_dir Entries fs_entry Files fs_file Partitions fs_partition Volumes f s_vol Support files Buffer management fs_buf Cache management fs_cache Counter management fs_ctr h Pool management s_pool File system driver s_sys Unicode encoding support fs unicode Utility functions fs_util Miscellaneous header files Master uC FS header file s h Error codes fs_err h Miscellaneous data types fs_type h Miscellaneous de
274. les for details about file access fs_pool c h contains the code for pool management used internally by C FS fs_sys c h contains the code for system driver management used internally by pC FS fs_unicode c h contains the code for handling Unicode strings used internally by yC FS 44 Directories and Files 3 9 uC FS FAT FILESYSTEM SOURCE CODE The files in these directories are available to uC FS licensees see Appendix H Licensing Policy Micrium Software uC FS FAT fs_fat c fs_fat h fs_fat_dir c fs_fat_dir h fs_fat_entry c fs_fat_entry h fs_fat_fat1l2 c fs_fat_fat12 h fs_fat_fatl6 c fs_fat_fat16 h fs_fat_fat32 c fs_fat_fat32 h fs_fat_file c fs_fat_file h fs_fat_journal c fs_fat_journal h fs_fat_lfn c fs_fat_lfn h fs_fat_sfn c fs_fat_sfn h fs_fat_type h Micrium This is where we place all software components and projects provided by Micrium Software This sub directory contains all the software components and projects 45 uc FS This is the main pC FS directory FAT Directories and Files This directory contains the FAT system driver for pC FS All the files in this directory should be included in your build assuming you have the source code 3 10 uC FS MEMORY DEVICE DRIVERS These files are generic drivers to use with differenty memory devices Micrium Software uC FS Dev IDE fs_dev_ide c fs_dev_ide h BSP Template fs_dev_ide_bsp c MSC f
275. lication FS_CFG_API_EN Converts timestamp to string in the form Sun Sep 16 01 03 52 1973 n 0 ARGUMENTS p ts Pointer to timestamp to format str_time String buffer that will receive date time string see Note RETURNED VALUE Pointer to str_time if NO errors Pointer to NULL otherwise NOTES WARNINGS str Lime MUST be at least 26 characters long Buffer overruns MUST be prevented by caller 214 LC FS API Reference Manual A 2 6 fs_fclose int fs fclose FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG_API_EN Close and free a file ARGUMENTS p file Pointer to a file RETURNED VALUE 0 if the file was successfully closed FS_EOF otherwise NOTES WARNINGS 1 After a file is closed the application MUST desist from accessing its file pointer This could cause file system corruption since this handle may be re used for a different file 2 If the most recent operation is output write all unwritten data is written to the file 3 Any buffer assigned with fs_setbuf or fs_setvbuf shall no longer be accessed by the file system and may be re used by the application 215 LC FS API Reference Manual A 2 7 fs_feof int fs feof FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG_API_EN Test EOF indicator on a file ARGUMENTS p file Pointer to a file RETURNED VALUE 0 if EOF indicator is NOT set or if an error
276. lk_cfg h determines whether clock will be managed by the RTOS or in your application A few other defines are used to enable disable some features of pC Clk and to configure some parameteres like the clock frequency os This is the main OS directory lt rtos_name gt This is the directory that contains the file to perform RTOS abstraction Note that the file for the selected RTOS abstraction layer must always be named clk_os c uC Clk has been tested with pC OS II pC OS II and the RTOS layer files for these RTOS are found in the following directories Micrium Software uC C1k 0S uCOS II clk_os c Micrium Software uC C1k 0S uCOS III clk_os c Source This directory contains the CPU independant source code for wC Clk All file in this directory should be included in the build assuming the presence of the source code Features that are not required will be compiled out based on the value of define constants in clk_cfg h 39 Directories and Files 3 7 pC CRC CHECKSUMS AND ERROR CORRECTION CODES uC CRC consists of functions to compute different error detection and correction codes The functions are speed optimized to avoid the important impact on performances that these CPU intensive calcutions may present Micrium Software uC CRC Cfg Template erc_cfg h Ports lt architecture gt lt compiler gt ecc_bch_4bit_a asm ecc_bch_8bit_a asm ecc_hamming a asm edc_crc_a asm Source edc_crc h edc_crc c ecc
277. lso called by various FSEntry_ functions to prevent concurrent access to an entry in the FAT filesystem ARGUMENTS name full Name of the directory See section 4 3 uC FS File and Directory Names and Paths on page 62 p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Directory opened FS_ERR_NULL PTR Argument name full passed a NULL pointer FS_ERR_NAME INVALID Entry name specified invalid or volume could not be found Or entry error see section B 8 Entry Error Codes on page 378 RETURNED VALUE DEF_NO if dir is NOT open DEF_YES if dir is open NOTES WARNINGS None 269 A 4 3 FSDir_Open FS DIR FSDir Open CPU_CHAR LC FS API Reference Manual name full FS_ERR p err File Called from Code enabled by fs dir c Application FS_CFG DIR EN fs_opendir Open a directory See fs_opendir for more information ARGUMENTS name full Name of the directory See section 4 3 uC FS File and Directory Names and p_err Paths on page 62 Pointer to variable that will the receive return error code from this function FS_ERR NONE FS ERR NULL PTR FS ERR DIR DIS FS ERR DIR NONE AVAIL FS_ERR DEV FS ERR NAME INVALID FS ERR NAME PATH TOO LONG FS_ERR VOL NOT OPEN FS_ERR VOL NOT MOUNTED FS_ERR BUF NONE AVAIL Directory opened Argument name_full passed a NULL pointer Directory module disabled No directory available Device
278. ly they are not plagued by the complications of NAND flash which simplifies interfacing with them This chapter describes the function of these devices and the architecture of the supporting driver 20 Introduction Chapter 16 RAM Disk This chapter demonstrates the use of the simplest storage medium the RAM disk Chapter 17 SD MMC Devices SD and MMC cards are flash based removable storage devices commonly used in consumer electronics For embedded CPUs a SD MMC card is an appealing medium because of its simple and widely supported physical interfaces one choice is SPI This chapter describes the interface and function of these devices Appendix A uC FS API Reference Manual The reference manual describes every API function The arguments and return value of each function are given supplemented by notes about its use and an example code listing Appendix B uC FS Error Codes This appendix provides a brief explanation of pC FS error codes defined in fs_err h Appendix C pC FS Porting Manual The portability of uC FS relies upon ports to interface between its modules and the platform or environment Most of the ports constitute the board support package BSP which is interposed between the file system suite or driver and hardware The OS port adapts the software to a particularly OS kernel The porting manual describes each port function Appendix D pC FS Types and Structures This appendix provides a reference to the uC FS
279. m Code enabled by fs_dev_nand c Application N A Low level mount a NAND device ARGUMENTS name_dev Device name see Note p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Device low level mounted successfully FG ERR NAME NULL Argument name_dev passed a NULL pointer FS ERR DEV_INVALID Argument name_dev specifies an invalid device PG ERR DEV MO ODEN Device is not open PG ERR DEV MO PRESENT Device is not present FS ERR DEV_INVALID LOW FMT Device needs to be low level formatted FS_ERR_DEV_IO Device I O error FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS The device MUST be a NAND device e g nand 0 Low level mounting parses the on device structure detecting the presence of a valid low level format If FS_ERR_DEV_INVALID_LOW_FMT is returned the device is NOT low level formatted 342 LC FS API Reference Manual A 9 3 FSDev_NAND_LowUnmount void FSDev_NAND LowUnmount CPU_CHAR name_dev FS_ERR p err File Called from Code enabled by fs_dev_nand c Application N A Low level unmount a NAND device ARGUMENTS name_dev Device name see Note p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Device low level unmounted successfully FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_DEV_INVALID Argument name dev specifies an inv
280. m Code enabled by fs_vol c Application not FS_CFG_RD_ONLY_EN Writes data to volume sector s ARGUMENTS name_vol Volume name p sre Pointer to source buffer start Start sector of write cnt Number of sectors to write p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Sector s written FS_ERR_DEV Device access error FS_ERR_NAME NULL Argument name vol passed a NULL pointer FS_ERR_NULL PTR Argument p_src passed a NULL pointer FS_ERR_VOL_NOT_MOUNTED Volume is not mounted FS_ERR_VOL MOT OPEN Volume is not open RETURNED VALUE None NOTES WARNINGS None 334 LC FS API Reference Manual A 8 VOLUME CACHE FUNCTIONS void FSVol_CacheAssign CPU_CHAR name_vol FS VOL CACHE API p cache api void p cache data CPU_INT32U size CPU_INTO8U pet_mgmt CPU_INTO8U DCL dr FS_FLAGS mode FS_ERR p err void FSVol_CacheInvalidate CPU_CHAR name vol FS_ERR p err void FSVol_CacheFlush CPU_CHAR name vol FS_ERR p err 335 LC FS API Reference Manual A 8 1 FSVol_CacheAssign void FSVol_CacheAssign CPU_CHAR name_vol FS VOL CACHE API p cache api void p cache data CPU_INT32U size CPU_INTO08U pct mgmt CPU_INTO8U pct dir FS_FLAGS mode FS_ERR p err File Called from Code enabled by FS_CFG_CACHE EN fs vol c Application Assign cache to a volume ARGUMENTS name_vol Volume name p cache api Pointer to a c
281. matters each block may be subjected to a finite number of erases only A wear leveling algorithm must be employed so that each block is used equally Device r Capacity Page Size Block Size Endurance ECC Category Small page 128 Mb to 1 512 bytes 16 kB 100 000 1 bit correction SLC NAND Gb erases block 2 bit detection Flash Large Page SLC 1 Gb to 4 Gb 2 KB or 4 kB 128 kB or 256 100 000 1 bit correction NAND Flash kB erases block 2 bit detection Table 14 1 NAND Flash Devices 137 NAND Flash Driver 14 1 FILES AND DIRECTORIES The files inside the NAND driver directory are outlined in this section the generic file system files outlined in Chapter 3 Directories and Files on page 28 are also required Micrium Software uC FS Dev This directory contains device specific files Micrium Software uC FS Dev NAND This directory contains the NAND driver files fs_dev_nand These files are device driver for NAND flash devices This file requires a set of BSP functions be defined in a file named fs_dev_nand_bsp c to work with a certain hardware setup BSP Template fs_dev_nand_bsp c This is a template BSP for traditional NAND devices accessed via a bus interface See section C 7 NAND Flash BSP on page 440 for more information BSP Template GPIO fs_dev_nand_bsp c This is a template BSP for NAND devices accessed via GPIO See section C 7 NAND Flash BSP on page 440 for more information
282. measured in bytes from the beginning of the file 226 LC FS API Reference Manual A 2 17 fs_ftruncate int fs _ftruncate FS FILE p file fs off t size File Called from Code enabled by fs_api c Application FS_CFG_API_EN and not FS _CFG RD ONLY EN Truncate a file ARGUMENTS p file Pointer to a file size Size of the file after truncation RETURNED VALUE 0 if the function succeeds 1 otherwise NOTES WARNINGS 1 The file MUST be opened in write or read write mode 2 If fs ftruncate succeeds the size of the file shall be equal to length a If the size of the file was previously greater than length the extra data shall no longer be available b If the file previously was smaller than this length the size of the file shall be increased 3 If the file position indicator before the call to fs_ftruncate lay in the extra data destroyed by the function then the file position will be set to the end of file 227 LC FS API Reference Manual A 2 18 fs_ftrylockfile int fs _ftrylockfile FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG AGT EN and FS_CFG FILE LOCK EN Acquire task ownership of a file Gf available ARGUMENTS p file Pointer to a file RETURNED VALUE 0 if no error occurs and the file lock is acquired Non zero value otherwise NOTES WARNINGS fs_ftrylockfile is the non blocking version of fs_flockfile if the lock is not avai
283. must NOT be an empty string 2 The Init device driver interface function is called to initialize driver structures and any hardware for detecting the presence of devices for a removable medium 202 LC FS API Reference Manual A 1 2 ES In FS ERR FS Init FS CFG p fs cfg File Called from Code enabled by fs h Application N A Initializes uC FS and MUST be called prior to calling any other uC FS API functions ARGUMENTS p_fs_ cfg Pointer to file system configuration see Section C 01 RETURNED VALUE FS_ERR_NONE if successful Specific initialization error code otherwise The return value SHOULD be inspected to determine whether wC FS is successfully initialized or not If p FS did NOT successfully initialize search for the returned error in fs_err h and source files to locate where uC FS initialization failed NOTES WARNINGS uC LIB memory management function Mem _Init MUST be called prior to calling this function 203 LC FS API Reference Manual A 1 3 FS_VersionGet CPU_INT16U FS VersionGet void File Called from Code enabled by fs c Application N A Gets the uC FS software version ARGUMENTS None RETURNED VALUE uC FS software version NOTES WARNINGS The value returned is multiplied by 100 For example version 4 03 would be returned as 403 204 LC FS API Reference Manual A 1 4 FS _WorkingDirGet void FS WorkingDirGet CPU_CHAR path_dir CPU_SIZE T size
284. nalOpen sd 0 amp err APP_TEST FAULT err FS_ERR NONE Listing 9 2 Opening the journal 117 File Systems FAT Listing 9 3 Starting and stopping journaling 118 Chapter 10 Device Drivers The file system initializes controls reads and writes a device using a device driver A uC FS device driver has eight interface functions grouped into a FS_DEV_DRV structure that is registered with the file system with FS_DevDrvAdd as part of application start up immediately following FS Init Several restrictions are enforced to preserve the uniqueness of device drivers and simplify management E Each device driver must have a unique name D No driver may be registered more than once E Device drivers cannot be unregistered E All device driver functions must be implemented even if one or more is empty 119 Device Drivers 10 1 PROVIDED DEVICE DRIVERS Portable device drivers are provided for standard media categories E IDE driver The IDE driver supports compact flash CF cards and ATA IDE hard drives m MSC driver The MSC Mass Storage Class driver supports USB host MSC devices Oe thumb drives or USB drives via pwC USB Host E NAND driver The NAND flash driver support parallel typically ONFI compliant and serial typically Atmel Dataflash NAND flash devices E NOR driver The NOR flash driver support parallel typically CFI compliant and serial typically SPID NOR flash devices D R
285. nd invalid characters If valid the name is converted to upper case for storage in the directory entry Eventually in a backwards compatible extension Microsoft introduced long file names LENs LENS are limited to 255 characters stored as 16 bit Unicode in long directory entries Each name is stored with a short file name composed by attaching a numeric tail to the original this results in names like file 1 txt In addition to the characters allowed in SFNs the following are allowed in LFNs 2 vier es 111 File Systems FAT As described in Appendix E Fat Configuration on page 532 support for LFNs can be disabled if desired If LFNs are enabled the application may choose to specify file names in UTF 8 format which will be converted to 16 bit Unicode for storage in directory entries This option is available if FS_CFG UTF8_EN is DEF_ENABLED see Appendix E Feature Inclusion Configuration on page 527 9 1 3 DIRECTORIES AND DIRECTORY ENTRIES In the FAT file system directories are just special files composed of 32 byte structures called directory entries The topmost directory the root directory is located using information in the boot sector The normal short file name entries in this directory and all other directories follow the format shown in Figure 9 2 with the following fields Name is the 11 character 8 3 SFN Attr are the attributes of the entry indicating whether it is a
286. ne 538 Shell Commands KKK KKK KKK KKK KKK KKK RRR KKK KKK KEK KKK RRR EK EK KK KKK k k k KK k k k k k k k k k k k k k k k k k k kk k k k k kk kk k k kk k App ShellOut KKK KKK KKK KK KKK KKK KKK KKK KKK KKK EE KKK KKK KKK E E EEEE KERR RK KKK E E E EEEE E E E E E EEE E E E EEE EE E EE E E EE CPU_LINT16S App Shellout CPU_CHAR pbuf CPU_LINT16U buf len void popt Output pbuf data on terminal command line return nbr bytes tx d LF 2 1 LF 2 2 LF 2 3 Listing F 2 Executing shell commands amp handling shell output The SHELL CMD PARAM structure that will be passed to Shell_Exec must be initialized The peur_working_ dir member MUST be assigned a pointer to a string of at least FS_SHELL CFG MAX PATH LEN characters This string must have been initialized to the default working directory path if the root directory XN The next command ending with a newline should be read from the command line The received command should be executed with Shell Exec If the command is a valid command the appropriate command function will be called For example the command fs_1s will result in FSShell_1s in fs_shell c being called FSShell_1s will then print the entries in the working directory to the command line with the output function App Shellout passed as the second argument of Shell_Exec 539 Shell Commands F 3 COMMANDS The supported commands listed in the
287. ng the AMD command set is used in this driver if the Maximum number of bytes in a multi byte write Gin the CFI device geometry definition is non zero Some flash implementing AMD command set have non zero multi byte write size but do not support the write to buffer amp program command Often these devices will support alternate fast programming methods This driver MUST be modified for those devices to ignore the multi byte write size in the CFI information Define NOR_NO_BUF_PGM to force this mode of operation 15 5 2 FSDEV_NOR_INTEL_1X16 FSDev_NOR_ Intel_1x16 supports CFI NOR flash implementing Intel command set including E Most Intel Numonyx devices E Some ST Numonyx M28 device P Others 167 NOR Flash Driver 15 5 3 FSDEV_NOR_SST39 FSDev_NOR_SST39 supports SST s SST39 Multi Purpose Flash memories as described in various datasheets at SST Chttp www sst com SST39 devices use a modified form of the AMD command set A more significant deviation is in the CFI device geometry information which describes two different views of the memory organization division in to small sectors and division into large blocks rather than contiguous separate regions The driver always uses the block organization 15 5 4 FSDEV_NOR_STM25 FSDev_NOR_STM25 supports Numonyx ST s M25 amp M45 serial flash memories as described in various datasheets at Numonyx Chttp www numonyx com This driver has been tested with or shou
288. nly if FS_SHELL CFG DATE EN is DEF_ENABLED NOTES WARNINGS None COM4 PuTTY fs_date Thu Jun 11 18 18 10 Figure F 4 fs_date output 545 Shell Commands F 3 5 fs_df Report disk free space USAGES fs_ df fs df vol ARGUMENTS vollIf specified volume on which to report free space Otherwise information about all volumes will be output OUTPUT Name total space free space and used space of volumes REQUIRED CONFIGURATION Available only if FS_SHELL CFG DF EN is DEF_ENABLED NOTES WARNINGS None i COM4 PuTTY Figure F 5 fs_df Output 546 Shell Commands F 3 6 fs_Is List directory contents USAGES fs Le ARGUMENTS None OUTPUT List of directory contents REQUIRED CONFIGURATION Available only if FS_SHELL_CFG_LS_ EN is DEF_ENABLED NOTES WARNINGS The output resembles the output from the standard UNIX command Is l See the figure below jun 07 jun 07 drw rw rw Figure F 6 fs_Is Output 547 Shell Commands F 3 7 fs_mkdir Make a directory USAGES fs mkdir dir ARGUMENTS dir Directory path OUTPUT None REQUIRED CONFIGURATION Available only if FS SHELL CFG MKDIR EN is DEF ENABLED and FS CFG RD ONLY EN is DEF_DISABLED NOTES WARNINGS None 548 Shell Commands F 3 8 fs_mkfs Format a volume USAGES fs mkfs_ vol ARGUMENTS vol Volume name OUTPUT None REQUIRED CONFIGURATION Av
289. nts and projects provided by Micripm Software This sub directory contains all the software components and projects uC FS This is the main pC FS directory Dev This is where you will find the device driver files for the storage devices you are planning on using IDE This directory contains the IDE CF driver files 48 Directories and Files fs_dev_ide are device driver for IDE devices These files require a set of BSP functions to be defined in a file named fs_dev_ide_bsp c to work with a particular hardware setup For more details on this driver please refer to Chapter 11 IDE CF Driver on page 124 MSC This directory contains the MSC Mass Storage Class USB drives driver files fs_dev_msc are device driver for MSC devices This driver is designed to work with uC USB host stack For more details on this driver please refer to Chapter 13 MSC Driver on page 134 NAND This directory contains the NAND driver files fs_dev_nand are the device driver for NAND devices These files require a set of physical layer functions defined in a file name fs_dev_nand_ lt physical type gt as well as BSP functions to be defined in a file named fs_dev_nand_bsp c to work with a particular hardware setup For more details on this driver please refer to Chapter 14 NAND Flash Driver on page 137 NOR This directory contains the NOR driver files fs_dev_nor are the device driver for NOR devi
290. o a file p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Error and end of file indicators cleared PG ERR NULL PTR Argument p file passed a NULL pointer FS ERR INVALID TYPE Argument p file s type is invalid or unknown FS_ERR FILE NOT OPEN File NOT open RETURNED VALUE None NOTES WARNINGS None 294 LC FS API Reference Manual A 6 5 FSFile_IsEOF CPU_BOOLEAN FSFile IsEOF FS FILE p file PG ERR p err File Called from Code enabled by fs file c Application N A fs_feof Test EOF indicator on a file See fs_feof for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE EOF indicator obtained PG ERR NULL PTR Argument p file passed a NULL pointer FS_ERR_INVALID_TYPE Argument p file s type is invalid or unknown FS_ERR FILE NOT OPEN File NOT open RETURNED VALUE DEF_NO if EOF indicator is NOT set or if an error occurred DEF_YES if EOF indicator is set NOTES WARNINGS None 295 LC FS API Reference Manual A 6 6 FSFile_IsErr CPU_BOOLEAN FSFile IsErr FS FILE p file PG ERR p err File Called from Code enabled by fs file c Application N A fs_ferr Test error indicator on a file See fs_ferror for more information ARGUMENTS p file Pointer to a file p err Pointer to variable that will receive the return error cod
291. o assign and flush a file buffer that are equivalents to POSIX API functions the primary difference is the advantage of valuable return error codes to the application File Module Function void FSFile BufAssign FS FILE p file void p buf FS_FLAGS mode CPU_SIZE T size FS_ERR p err void FSFile BufFlush FS FILE p file FS_ERR p err For more information about and an example Configuring a File Buffer on page 91 POSIX API Equivalent int fs _setvbuf FS_FILE stream char buf int mode fs_size t size int fs_fflush FS_FILE stream of configuring a file buffer see section 6 3 3 101 7 1 4 FILE ERROR FUNCTIONS Files The file module has functions get and clear a file s error status that are almost exact equivalents to POSIX API functions the primary difference is the advantage of valuable return error codes to the application File Module Function void FSFile ClrErr FS_FILE p file FS_ERR p err CPU_BOOLEAN FSFile IsErr FS FILE p file FS ERR p err CPU_BOOLEAN FSFile IsEOF FS FILE p file PS ERR p err POSIX API Equivalent void fs_clearerr FS_FILE stream int fs_ferror FS_FILE stream int fs_feof FS_FILE stream For more information about this functionality see section 6 3 4 Diagnosing a File Error on page 93 7 1 5 ATOMIC FILE OPERATIONS USING FILE LOCK The file module has functions lock files across several operations that are almost ex
292. ock count will be incremented and the caller will own the file Otherwise the caller will wait until the lock count returns to zero 4 Each call to s_funlockfile incremenets the lock count 5 Matching calls to fs_flockfile or fs_ftrylockfile and fs_funlockfile can be nested 220 LC FS API Reference Manual A 2 12 fs_fopen FS FILE fs fopen const char name full const char str_mode File Called from Code enabled by fs_api c Application FS_CFG API_EN Open a file ARGUMENTS name full Name of the file See section 4 3 uC FS File and Directory Names and Paths on page 62 for information about file names str_mode Access mode of the file RETURNED VALUE Pointer to a file if NO errors Pointer to NULL otherwise NOTES WARNINGS 1 The access mode should be one of the strings shown in section Table 7 2 fopenO mode strings and mode equivalents on page 100 2 The character b has no effect 3 Opening a file with read mode fails if the file does not exist 4 Opening a file with append mode causes all writes to be forced to the end of file EEN LC FS API Reference Manual A 2 13 fs_fread fs size t fs fread void p dest fs size t size fs size t nitems PG FILE p file File Called from Code enabled by fs_api c Application FS_CFG API_EN Read from a file ARGUMENTS p dest Pointer to destination buffer size Size of each item to read nitems Number of i
293. of uC FS to be adjusted based on your requirements Most of the defines should be configured with the default configuration values This leaves about a dozen or so values that should be configured with values that may deviate from the default configuration 525 UC FS Configuration E 1 FILE SYSTEM CONFIGURATION Core file system modules may be selectively disabled FS_CFG_SYS_DRV_SEL FS_ CFG SYS DRV_SEL selects which file system driver s will be included Currently there is only one option When PG GG DRV_SEL FAT the FAT system driver will be included FS_CFG_ CACHE EN FS CFG CACHE EN enables when set to DEF ENABLED or disables when set to DEF DISABLED code generation of volume cache functions Function File FSVol_CacheAssign fs_vol c FSVol_CacheFlush fs_vol c FSVol_CacheInvalidate fs_vol c Table E 1 Cache function exclusion These functions are NOT included if FS_CFG_CACHE_EN is DEF_DISABLED FS_CFG_API_EN FS CFG API EN enables when set to DEF ENABLED or disables when set to DEF DISABLED code generation of the POSIX API functions This API includes functions like Ce fopen or fs_opendir which mirror standard POSIX functions like fopenO or opendirO 526 UC FS Configuration FS_CFG_DIR_EN FS CFG DIR EN enables when set to DEF ENABLED or disables when set to DEF DISABLED code generation of directory access functions When disabled the functions in the following table will not be availa
294. offered for the remaining devices so that these can fit in standard SD MMC card slots Two further products incorporating SD MMC technology are emerging First some cards now integrate both USB and SD MMC connectivity for increased ease of access in both PCs and embedded devices The second are embedded MMC trademarked eMMC fixed flash based media addressed like MMC cards 174 Card Size Pin Count SD MMC Drivers Description MMCPlus 32 x 24x 1 4mm 13 MMCmobile 18 x 24x 1 4mm 13 MMCmicro SD or SDHC 14x 12x 1 1mm 32 x 24x 1 4mm 13 SDmini 21 5 x 20x 1 4mm 11 SDmicro 15x 11x 1 0 mm Most current MMC cards can operate with 1 4 or 8 data lines though legacy media were limited to a single data line The maximum clock frequency is 20 MHz providing for maximum theoretical transfer speeds of 20 MB s 80 MB s and 160 MB s for the three possible bus widths SD cards can operate in cardmode with 1 or 4 data lines or in SPI mode The maximum clock frequency is 25 MHz providing for maximum theoretical transfer speeds of 25 MHz and 50 MHz for the two possible bus widths Table 17 1 SD MMC Devices SD MMC cards can be used in two modes card mode also referred to as MMC mode and SD mode and SPI mode The former offers up to 8 data lines depending on the type of card the latter only one data line but the accessibility of a communication
295. open FS_ERR_VOL NOT MOUNTED Volume was not mounted PG ERR DUE NONE AVAIL Buffer not available FS_ERR_DEV Device access error Or entry error See section B 8 Entry Error Codes on page 378 RETURNED VALUE None 274 LC FS API Reference Manual NOTES WARNINGS 1 If the entry does not exist an error is returned Three attributes may be modified by this function FS ENTRY ATTRIB RD Entry is readable FS_ENTRY ATTRIB WR Entry is writable FS_ENTRY_ ATTRIB HIDDEN Entry is hidden from user level processes An attribute will be cleared if its flag is not OR d into attrib An attribute will be set if its flag is OR d into attrib If another flag besides these are set then an error will be returned The attributes of the root directory may NOT be set 275 LC FS API Reference Manual A 5 2 FSEntry_Copy void FSEntry Copy CPU_CHAR name_full_ src CPU_CHAR name full dest CPU_BOOLEAN excl FS_ERR p err File Called from Code enabled by fs_entry c Application not FS_CFG_RD_ONLY_EN Copy a file ARGUMENTS name full src Name of the source file See section 4 3 uC FS File and Directory Names and Paths on page 62 name_full dest Name of the destination file excl Indicates whether the creation of the new entry shall be exclusive see Note 1 DEF_YES if the entry shall be copied only if name_full_dest does not exist DEE MO if the entry shall be copied even if name_full_dest does exist
296. or COMSS wcecccsiesccacsssescewes ctcretteneesscteccnscdeneenaccavsctoeneessetecenees 376 Buffer Error CodeS seccisicccssesciecoeteeeett eetevtestaseeneecae ee EEEN ES SEEEEE Siet 376 Gache Error OOd OS 2s occccccecieceeaudteuecncaceceneerasuansestadeanesetea dndecusradnedustae 377 Device Error Goes Zuegeg egee ege Nee SEENEN Eed SARL dee 377 Device Driver Error Codes ANS EEEEEEE REENEN 378 Directory Error Codes eccceeeeeeeeeeesseeeeeeeeeeeeeeeseseeeeeseaneeeeeeeenees 378 EGG Error Code eessen ge ENEE ed 378 Entry Error Codes tege EENS RESEARCH 378 Bile Emor Codes ea aa aena aaa raana E nee lec eked sp ede ara a aae che dee chee 379 B 10 B 11 B 12 B 13 B 14 B 15 Appendix C C 1 C 2 C 3 G A C 4 1 C 4 2 C 4 3 C 4 4 C 4 5 C 4 6 C 4 7 C 4 8 C 5 C 5 1 C 5 2 C 5 3 C 5 4 C 5 5 C 5 6 C 5 7 C 5 8 C 5 9 C 5 10 C 5 11 C 5 12 C 5 13 C 5 14 C 5 15 C 6 C 6 1 Name Error e 379 Partition Error COGS ccecceceeeeeeeeeeeeeeeneeeeeeeeeeeeseeseeeesaneeeeeeeeeeees 380 Pools Error Godes ea aa aaa iaaa a Ea ndan 380 File System Error Codes cccccsssseeceessseeeeceeessneeceesessneeceeensneeeeeeenssnes 380 Volume Error CodeS ccecceeeceeceeeeeeseeeeeeceeceeeeeeseseeeeeeesneeeeeeeeeeeeens 381 OS Layer Error Codes i cciiccscescinttiacececcsveisteveesssencecbdeneesseseveevcesesubecees 382 HC FS Porting Manual osioissa iner aon Kr EA aeaa iE adaa aKa 383 Date Time management ceec
297. or additional information H 1 3 pC FS SOURCE CODE UPDATES If you are under maintenance you will be automatically emailed when source code updates become available You can then download your available updates from the Micrium FTP server If you are no longer under maintenance or forget your Micrium FTP username or password please contact sales Micrim com H 1 4 yC FS SUPPORT Support is available for licensed customers Please visit the customer support section in www Micrim com If you are not a current user please register to create your account A web form will be offered to you to submit your support question Licensed customers can also use the following contact Contact Micrium Micripm 1290 Weston Road Suite 306 Weston FL 33326 1 954 217 2036 1 954 217 2037 FAX 564 Mouser Electronics Authorized Distributor Click to View Pricing Inventory Delivery amp Lifecycle Information Analog Devices Inc AD UCFS JRN SPRD AD UCFS SPRD AD UCFS MJRN SP AD UCFS MNT SP
298. ormation ARGUMENTS p file Pointer to a file offset Offset from the file position specified by origin origin Reference position for offset FS_FILE ORIGIN START Offset is from the beginning of the file FS FILE ORIGIN CUR Offset is from the current file position FS FILE ORIGIN END Offset is from the end of the file p err Pointer to variable that will the receive return error code from the function FS_ERR_NONE File position set successfully FS_ERR_NULL PTR Argument p file passed a NULL pointer FS_ERR_INVALID TYPE Argument p file s type is invalid or unknown FG ERR FILE INVALID ORIGIN Invalid origin specified FS_ERR FILE INVALID OFFSET Invalid offset specified FS_ERR_FILE_NOT_OPEN File NOT open 306 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS None 307 A 6 14 FSFile_Query LC FS API Reference Manual void FSFile Query FS FILE p file FS ENTRY INFO p info FS_ERR p err File Called from Code enabled by fs file c Application N A fs_fstat FSFile Query is used to get information about a file ARGUMENTS p file Pointer to a file p_info Pointer to structure that will receive the file information see Note p err Pointer to variable that will the receive return error code from the function FS_ERR_NONE File information obtained successfully FS ERR NULL PTR FS ERR INVALID TYPE FS ERR FILE NOT OPEN RETURNED VALUE None NOTES WARNINGS None
299. ost stack must be initialized as shown in Listing 13 1 The file system initialization function FS_Init must then be called and the MSC driver FSDev_MSC restivered using FS_DevDrvAdd The USB notification function should add remove devices when events occur as shown in Listing 13 1 ROM RAM characteristics and performance benchmarks of the MSC driver can be found in section 10 1 1 Driver Characterization on page 121 static void App InitUSB_Host void USBH_ERR err err USBH_HostCreate amp App USB Host amp USBH_AT91SAM9261 Drv if err USBH_ERR_NONE return err USBH_HostInit amp App USB Host if err ls USBH_ERR NONE return USBH_ClassDrvReg amp App USB_Host amp USBH_MSC_ClassDrv USBH_CLASS_NOTIFY_FNCT App USB HostMSC_ClassNotify void 0 Listing 13 1 Example pC USB initialization 135 MSC Driver static void App USB HostMSC_ClassNotify void pclass_ dev CPU_INTO8U is_conn void pctx USBH_MSC_DEV p_msc_dev USBH_ERR usb_err FS_ERR fs_err p_msc_dev USBH_MSC_DEV pclass_dev switch is_conn case USBH_CLASS DEV_STATE CONNECTED MASS STORAGE DEVICE CONN D St usb err USBH_MSC_RefAdd p_msc_dev if usb_err USBH_ERR_NONE FSDev_MSC_DevOpen p_msc_dev amp fs_err break case USBH_CLASS DEV_STATE REMOVED MASS STORAGE DEVICE REMOVED FSDev_MSC_DevClose p_msc_dev USBH_MSC_RefRel p _msc_dev break default break
300. out error RETURNED VALUE None NOTES WARNINGS None 438 LUC FS Porting Manual C 6 9 IOC void IO Ctrl FS_DEV_NAND PHY DATA p phy data CPU_INTO8U opt void p data FS_ERR p err File Called from Code enabled by NAND physical layer driver N A N A Perform NAND device I O control operation ARGUMENTS p_phy data Pointer to NAND phy data opt Control command p data Buffer which holds data to be used for operation OR Buffer in which data will be stored as a result of operation p err Pointer to variable that will receive the return error code from this function FS_ERR DEV INVALID IO CTRL I O control unknown to driver RETURNED VALUE None NOTES WARNINGS None Table C 4 439 LUC FS Porting Manual C 7 NAND Flash BSP The NAND driver must adapt to the specific hardware using a BSP The following functions must be implemented to interface the NAND driver on a parallel bus 440 LUC FS Porting Manual C 7 1 FSDev_NAND_BSP_Open CPU_BOOLEAN FSDev_NAND BSP_Open FS_QTY unit_nbr CPU_INTO8U bus width File Called from Code enabled by Ca dev nand bep NAND physical layer driver N A Open initialize bus for NAND ARGUMENTS unit_nbr Unit number of NAND bus_width Bus width in bits RETURNED VALUE DEF OF if interface was opened DEF_FAIL otherwise NOTES WARNINGS This function will be called every time the device is opened 441 LUC FS Porting Man
301. own in Table 15 5 As with any SPI device four signals are used to communicate with the host CS SI SCK and SO MCU MPU SERIAL NOR HHI Figure 15 4 Typical serial NOR connections 164 NOR Flash Driver 15 4 2 NOR SPI BSP OVERVIEW An NOR BSP is required so that a physical layer driver for a serial flash will work on a particular system For more information about these functions see section C 11 on page 466 Function Description FSDev_NOR_BSP_SPI_Open Open initialize SPI FSDev_NOR_BSP_SPI_Close Close uninitialize SPI FSDev_NOR_BSP_SPI_Lock Acquire SPI lock FSDev_NOR_BSP_SPI_Unlock Release SPI lock FSDev_NOR_BSP_SPI_Rd Read from SPI FSDev_NOR_BSP_SPI_Wr Write to SPI FSDev_NOR_BSP_SPI_ChipSelEn Enable chip select FSDev_NOR_BSP_SPI_ChipSelDis Disable chip select FSDev_NOR_BSP_SPI_SetClkFreq Set SPI clock frequency Table 15 5 NOR SPI BSP Functions 165 NOR Flash Driver 15 5 PHYSICAL LAYER DRIVERS The physical layer drivers distributed with the NOR driver see the table below support a wide variety of parallel and serial flash devices from major vendors Whenever possible advanced programming algorithms such as the common buffered programming commands are used to optimize performance Within the diversity of NOR flash some may be found which implement the basic command set but not the advanced features for these a released phy
302. p c FSDev_IDE_RdData N A Read data from IDE CF device ARGUMENTS unit_nbr Unit number of IDE CF device p_dest Pointer to destination memory buffer cnt Number of octets of data to read RETURNED VALUE None NOTES WARNINGS None 417 LUC FS Porting Manual C 5 9 FSDev_IDE_BSP_DataWr void FSDev_IDE BSP DataRd FS QTY unit_nbr void p src CPU_SIZE T cnt File Called from Code enabled by fs_dev_ide_bsp c FSDev_IDE WrData N A Write data to IDE CF device ARGUMENTS unit_nbr Unit number of IDE CF device p srce Pointer to source memory buffer cnt Number of octets of data to write RETURNED VALUE None NOTES WARNINGS None 418 LUC FS Porting Manual C 5 10 FSDev_IDE_BSP_DMA Start void FSDev_IDE BSP_DMA Start FS QTY unit_nbr void p data CPU_SIZE T cnt FS_FLAGS mode_type File CPU BOOLEAN rd Called from Code enabled by fs_dev_ide_bsp c FSDev_IDE_RdData N A FSDev_IDE WrData Setup DMA for command initialize channel ARGUMENTS unit_nbr Unit number of IDE CF device D data ent Pointer to memory buffer Number of octets to transfer mode type Transfer mode type rd FS DEV_IDE MODE TYPE DMA Multiword DMA mode FS DEV_IDE MODE TYPE UDMA Ultra DMA mode Indicates whether transfer is read or write DEF_YES Transfer is read DEF_NO Transfer is write RETURNED VALUE None 419 LUC FS Porting Manual NOTES WARN
303. paring for the next command or preventing further interrupts must be first handled Error returned e Start command execution d Return FSDev_SD_Card_BSP_CmdStart Ke ey Error Wait for command to execute and returned a S response to be returned C Return ft FSDev_SD_Card_BSP_CmdWaitEnd FSDev_SD_Card_BSP_CmdDataWr FSDev_SD_Card_BSP_CmdDataRd Return Figure 17 9 Command execution 188 SD MMC Drivers 17 3 USING THE SD MMC SPI DRIVER To use the SD MMC SPI driver five files in addition to the generic file system files must be included in the build fs_dev_sd c fs_dev_sd h fs _dev_sd_spi c fs_dev_sd_spi h fs_dev_sd_spi bsp c The file fs dev_sd_spi h must also be included in any application or header files that directly reference the driver for example by registering the device driver The following directories must be on the project include path Micrium Software uC FS Dev SD Micrium Software uC FS Dev SD SPI A single SD MMC volume is opened as shown in Listing 17 2 The file system initialization FS _Init function must have previously been called 189 SD MMC Drivers ROM RAM characteristics and performance benchmarks of the SD MMC driver can be found in section 10 1 1 Driver Characterization on page 121 The SD MMC driver also provides interface functions to get low level card information and read the Card ID and Card Specific
304. pened A pointer to this structure is passed as the second argument of FSDev_Open for a NAND device MEMBERS BLkNbrFirst MUST specify which block of the NAND flash memory will be the first used for the file system data SecSize MUST specify the sector size in bytes for the NAND flash either 512 1024 2048 or 4096 BlkCnt MUST specify the size of the NAND flash in number of blocks RBCnt MUST specify the number of replacement blocks that will be used by the driver PhyPtr MUST point to the appropriate physical layer driver FSDev_NAND 0512x08 512 byte page NAND 8 bit data bus FSDev_NAND_2048x08 2048 byte page NAND 8 bit data bus FSDev_NAND 2048x16 2048 byte page NAND 16 bit data bus FSDev_NAND AT45 Atmel AT45 serial DataFlash 511 LIC FS Types and Structures Other User developed BusWidth is the bus width in bits between the MCU MPU and each connected device MaxClkFreq For a serial flash the maximum clock frequency is specified via MaxClkFreq NOTES None 512 LIC FS Types and Structures D 4 FS_DEV_NOR_CFG typedef struct fs dev nor cfg CPU_ADDR AddrBase CPU_INTO8U RegionNbr CPU_ADDR AddrStart CPU_INT32U DevSize FS SEC SIZE SecSize CPU_INTO8U PctRsvd CPU_INT16U EraseCntDiffTh FS_DEV_NOR_PHY API PhyPtr CPU_INTO8U BusWidth CPU_INTO8U BusWidthMax CPU_INTO8U PhyDevCnt CPU_INT32U MaxClkF req FS_DEV_NOR CFG File Used for fs_dev_nor h Second argument of FSDev_Open when
305. perties of the file system can be configured with a FS FAT SYS CFG structure An example of populating and using the FAT configuration is shown in Listing 9 1 If the configuration is invalid an error will be returned from FSVol_Fmt For more information about the FS _FAT SYS CFG structure see Appendix D FS_FAT_SYS_CFG on page 520 115 File Systems FAT void App InitFS void FS_ERR err FS FAT SYS CFG fat cfg fat_cfg ClusSize 4 Cluster size 4 512 B 2 kB fat_cfg RsvdAreaSize ele Reserved area 1 sector a fat_cfg RootDirEntryCnt 512 Entries in root dir 512 ay fat_cfg FAT_Type 12 FAT type FAT12 Z fat_cfg NbrFATs 2 Number of FATs 2 Gi FSVol_Fmt ram 0 amp fat cfg amp err if err FS_ERR_NONE APP TRACE DEBUG Format failded r n Listing 9 1 Example device format 9 2 2 DISK CHECK Errors may accrue on a FAT volume either by device removal during file system modifications or by improper host operation Several corruptions are common E Cross linked files If a cluster becomes linked to two files then it is called cross linked The only way to resolve this is by deleting both files if necessary they can be copied first so that the contents can be verified E Orphaned directory entries If LFNs are used a single file name may span several directory entries If a file deletion is interrupted some of these may be left behind or orphaned
306. pi c Read SD MMC Card ID CID register ARGUMENTS name_dev Device name see Note 1 p_dest Pointer to 16 byte buffer that will receive SD MMC Card ID register p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE SD MMC Card ID register read FS_ERR_NAME NULL Argument name deyv passed a NULL pointer FS_ERR_NULL PTR Argument p dest passed a NULL pointer FS_ERR_DEV_INVALID Argument name_dev specifies an invalid device PG ERR DEV MO OPEN Device is not open PG ERR DEV MO PRESENT Device is not present FS_ERR_DEV_IO Device I O error FS_ERR_DEV_ TIMEOUT Device timeout RETURNED VALUE None 367 LC FS API Reference Manual NOTES WARNINGS 1 The device MUST be a SD MMC device for FSDev_SD Card QuerySD e g sdcard 0 for FSDev_SD_SPI_QuerySD e g sd 0 For SD cards the structure of the CID is defined in the SD Card Association s Physical Layer Simplified Specification Version 2 00 Section 5 1 For MMC cards the structure of the CID is defined in the JEDEC s MultiMediaCard MMC Electrical Standard High Capacity Section 8 2 368 LC FS API Reference Manual A 11 3 FSDev_SD_xxx_RdCSD void FSDev_SD Card _RdCSD CPU_CHAR name_dev CPU_INTO8U p info FS_ERR p err void FSDev_SD SPI _RdCSD CPU_CHAR name_dev CPU_INTO8U p info FS_ERR p err File Called from Code enabled by fs_dev_sd_card c Ap
307. plication N A fs_dev_sd_spi c Read SD MMC Card Specific Data CSD register ARGUMENTS name dey Device name see Note 1 p dest Pointer to 16 byte buffer that will receive SD MMC Card Specific Data register p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE SD MMC Card Specific Data register read FS_ERR_NAME NULL Argument name_dev passed a NULL pointer FS_ERR NULL PTR Argument p_dest passed a NULL pointer FS_ERR_DEV_INVALID Argument name_dev specifies an invalid device PG ERR DEV MO OPEN Device is not open PG ERR DEV MO PRESENT Device is not present FS_ERR_DEV_IO Device I O error FS_ERR_DEV_ TIMEOUT Device timeout RETURNED VALUE None 369 NOTES WARNINGS LC FS API Reference Manual 1 The device MUST be a SD MMC device for FSDev_SD Card _QuerySD e g sdcard 0 for FSDev_SD_SPI_QuerySD e g sd 0 2 For SD cards the structure of the CSD is defined in the SD Card Association s Physical Layer Simplified Specification Version 2 00 Section 5 3 2 v1 x and v2 0 standard capacity or Section 5 3 3 v2 0 high capacity For MMC cards the structure of the CSD is defined in the JEDEC s MultiMediaCard MMC Electrical Standard High Capacity Section 8 3 A 12 FAT SYSTEM DRIVER FUNCTIONS void FS_FAT JournalOpen CPU_CHAR name vol FS_ERR p err void FS_FAT JournalClose CPU_CHAR name vol FS_
308. ports a certain device type such as SD MMC cards NAND flash or NOR flash Drivers are only available to pC FS licensees This is the pC FS code that is adapted to a specific platform It consists of small code modules written for specific drivers called ports that must be adapted to the memory device controllers or peripherals integrated into or attached to the CPU The requirements for these ports are described in Appendix C Porting Manual uC FS does not require an RTOS However if uC FS is used with an RTOS a set of functions must be implemented to prevent simultaneous access of devices and core uC FS structures by multiple tasks This uC FS configuration file defines which pC FS features fs_cfg h are included in the application 3 1 APPLICATION CODE When Micrium provides you with example projects we typically place those in a directory structure as shown below Of course you can use whatever directory structure suits your project product Micrium Software EvalBoards lt manufacturer gt lt board name gt lt compiler gt lt project name gt VW 31 Directories and Files Micrium This is where we place all software components and projects provided by Micrium This directory generally starts from the root directory of your computer Software This sub directory contains all the software components and projects EvalBoards This sub directory contains all the projects related to the evaluation
309. r unexpected condition could make an assumption about initial controller state false This simple validation is recommended to avoid side effects and to aid port debugging Calculate the transfer mode register value The command s DataType and DataDir members specify the type and direction of any transfer Since this examples uses DMA DMA is enabled in the transfer mode register Calculate the command register value The command index is available in the command s Cmd member which is supplemented by the bits OR d into Flags to describe the expected result response and data transfer following the command execution The hardware registers are written to execute the command The sequence in which the registers are written is important Typically as in this example the assignment to the command register actually triggers execution 476 LUC FS Porting Manual C 12 4 FSDev_SD_ Card _BSP_CmdWaitEnd void FSDev_SD Card BSP CmdWaitEnd FS QTY unit_nbr FS _DEV_SD CARD CMD p cmd CPU_INT32U p resp FS_ERR p err File Called from Code enabled by fs_dev_sd_card_bsp c SD MMC cardmode driver N A Wait for command to end and get command response ARGUMENTS unit_nbr Unit number of SD MMC card p_cmd p resp p err Pointer to command that is ending Pointer to buffer that will receive command response if any Pointer to variable that will receive the return error code from this fun
310. r code is FS_ERR_PARTITION_NOT_FOUND then no valid file system could be found on the device or the specified partition does not exist The device may need to be formatted see below E If the return error code is FS_ERR_DEV PG ERR DEV MOT PRESENT FS ERR _DEV_IO or FS_ERR DEV TIMEOUT the device is either not present or did not respond This is an important consideration for removable devices The volume is still registered with the file system suite and the file system will attempt to re open the volume each time the application accesses it see section 5 2 Using Devices on page 69 for more information E If any other error code is returned the volume is not registered with the file system The developer should examine the error code to determine the source of the error FSVol_Fmt formats a device re initializing the file system on the device FSVol_Fmt CPU_CHAR ide 0 lt a volume name void 3 e lt b pointer to system configuration PS ERR amp err lt c return error The parameters are the volume name a and a pointer to file system specific configuration b The configuration is not required if you are willing to accept the default format a NULL pointer should be passed Alternatively the exact properties of the file system can be configured by passing a pointer to a FS_FAT SYS CFG structure as the second argument For more information about the FS_FAT SYS CFG structure see section D 8
311. r is cleared 4 If the file position indicator is set beyond the file s current data a and data is later written to that point reads from the gap will read 0 b the file MUST be opened in write or read write mode 224 LC FS API Reference Manual A 2 15 fs_fsetpos int fs _fsetpos FS FILE p file fs fpos t p pos File Called from Code enabled by fs_api c Application FS_CFG API_EN Set file position indicator ARGUMENTS p file Pointer to a file p_pos Pointer to variable containing file position indicator RETURNED VALUE 0 if the function succeeds Non zero value otherwise NOTES WARNINGS 1 The return value should be tested against 0 rtn fs_fsetpos pfile amp pos if rtn 0 No error occurred else Handle error 2 Ifa read or write error occurs the error indicator shall be set 3 The value stored in pos should be the value from an earlier call to fs_fgetpos No attempt is made to verify that the value in pos was obtained by a call to s_fgetpos 4 See also fs_fseek 225 LC FS API Reference Manual A 2 16 fs_ftell long int fs _ftell FS FILE p file File Called from Code enabled by fs_api c Application FS_CFG API_EN Get file position indicator ARGUMENTS p file Pointer to a file RETURNED VALUE The current file system position if the function succeeds 1 otherwise NOTES WARNINGS The file position returned is
312. r modules independent of the CPU and compiler word sizes Specifically you will find the declaration of the CPU_INT16U CPU_INT32U CPU_FP32 and many other data types Also this file specifies whether the CPU is a big or little endian machine and contains function prototypes for functions that are specific to the CPU architecture and more 36 Directories and Files cpu_a asm contains the assembly language functions to implement the code to disable and enable CPU interrupts count leading zeros Gf the CPU supports that instruction and other CPU specific functions that can only be written in assembly language This file could also contain code to enable caches setup MPUs and MMU and more The functions provided in this file are accessible from C cpu_c c contains C code of functions that are specific to the specific CPU architecture but written in C for portability As a general rule if a function can be written in C then it should unless there are significant performance benefits by writing it in assembly language 3 5 pC LIB PORTABLE LIBRARY FUNCTIONS pC LIB consists of library functions that are meant to be highly portable and not tied to any specific compiler This was done to facilitate third party certification of Micrium products Micrium Software uC LIB lib_ascii c lib_ascii h lib det hb lib_math c lib math h lib_mem c lib_mem h lib_str c lib_str h Cfg Template lib_cfg h Ports lt archite
313. r will work on a particular system The functions shown in the table below must be implemented Pleaser refer to section C 5 IDE CF Device BSP on page 408 for the details about implementing your own BSP Function Description FSDev_IDE BSP _Open Open initialize hardware FSDev_IDE BSP Close Close uninitialize hardware FSDev_IDE_BSP_Lock Acquire IDE bus lock FSDev_IDE_BSP_Unlock Release IDE bus lock FSDev_IDE_BSP_Reset Hardware reset IDE device FSDev_IDE_BSP_RegRd Read from IDE device register FSDev_IDE_BSP_RegWr Write to IDE device register FSDev_IDE_BSP_Cmdwr Write command to IDE device register FSDev_IDE_BSP_DataRd Read data from IDE device FSDev_IDE BSP_DataWr Write data to IDE device FSDev_IDE BSP_DMA Start Setup DMA for command Initialize channel FSDev_IDE_BSP_DMA End End DMA transfer and uninitialize channel FSDev_IDE BSP_GetDrvNbr Get IDE drive number FSDev_IDE BSP_GetModesSupported Get supported transfer modes FSDev_IDE BSP_SetMode Set transfer modes FSDev_IDE_BSP_Dly400_ns Delay for 400 ns Table 11 1 IDE BSP Functions 131 DMA Write command FSDev_IDE_ BSP_CmdWr EE Wait for data request Read or write data FSDev_IDE_BSP_DataRd Wr More data IDE CF Driver Command Setup DMA FSDev_IDE_BSP_DMA Start Write command FSDev_IDE_BSP_CmdWr
314. ral important markers The zeroth byte of the entry gives its order in the LFN entry sequence the first always has the sixth bit set If three entries were necessary they would carry order numbers of 0x43 0x02 and 0x01 respectively None of these you may note are valid characters which allows backward compatibility Byte 11 where the attributes value is in a SFN is always 0x0F Microsoft found that no older software would modify or use a directory entry with this marker Figure 9 3 gives an example of the directory entries created for the file abcdefghijklm op The checksum stored in byte 13 is calculated from the SFN It is checked each time the directory entries are parsed if incorrect the file system software knows that the SFN was modified presumably by a system not LFN aware 113 File Systems FAT 4 8 12 16 Chk Ord Char 1 Char 2 Char 3 Char 4 Char5 0x0F 0x00 s m Char 6 Char 7 Char 8 Char 9 Char 10 Char 11 0x0000 Char 12 Char 12 4 8 12 16 ex Ka vi Chk 0x42 o p 0x0000 OxFFFF 0x0F 0x00 Sim OxFFFF OxFFFF OxFFFF OxFFFF OxFFFF OxFFFF 0x0000 OxFFFF OxFFFF 0x01 a b IC d e 0x0F 0x00 Chk P sum S i 3 A LEE D a be d e p veo p ben wenn Crt Creation ms Time H st st Creation Access 1 Cluster Write Time Write Date 1 Cluster File Size Date Date High Low Figure 9 4 SNF entry and LFN
315. reference to uC FS services The following information is provided for each entry A brief description of the service The function prototype The filename of the source code The define constant required to enable code for the service A description of the arguments passed to the function A description of returned value s Specific notes and warnings regarding use of the service One or two examples of how to use the function Many functions return error codes These error codes should be checked by the application to ensure that the pC FS function performed its operation as expected Each of the user accessible file system services is presented in alphabetical order within an appropriate section the section for a particular function can be determined from its name 198 Section uC FS API Reference Manual Functions begin with General file system functions FS POXIX API functions fs_ Device functions FSDev_F Directory functions FSDir_ Entry functions FSEntry_ File functions FSFile_ Time functions FSTime_ Volume functions FSVol_ NAND driver functions FSDev_NAND_ NOR driver functions FSDev_NOR_ SD MMC driver functions FSDev_SD_ Compact Flash IDE driver functions FSDev_IDE_ MSC driver functions FSDev_MSC_ RAMDisk driver functions FSDev_RAM FAT functions FS_FAT_ BSP functions FS_BSP_ OS functions FS OS 199 LC FS API Reference Manual A 1 GENERAL FILE SYSTEM FUNCTIO
316. rmation herein and is not responsible for any errors and ommissions The publisher assumes no liability for damages resulting from the use of the information in this book or for any infringement of the intellectual property rights of third parties that would result from the use of this information Micrium 600 uC FS 001 For the Way Engineers Work Chapter 1 1 1 1 2 1 3 1 4 1 5 Chapter 2 2 1 2 1 1 2 1 2 2 1 3 2 1 4 2 1 5 2 1 6 2 1 7 2 1 8 Chapter 3 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 3 10 Table of Contents Introduction EE 15 VUEN 15 PIGIES E 16 Typical E E 17 Why FAT KEE 18 Chapter Contents st coc cascets enina inaaianei ania ianiai ariaa EE 18 PC FS ee 22 Architecture COMponents ceceseeeseeeeeee eee eeeeeeeeeeeeeeeeeaneeeeeeeeeeeeeeenees 24 YOur APPliGAation EE 24 LIB Lipra eS EE 24 ROSI Abt AV OM eer ee d 24 FS Layer uge cceesacai eg EENS ee dE CA 24 File System Driver Layer cccccesseeeeeeeseeeeeeeeeeeeeeeeeeseeeeseeeeeneeeeeeeseeenees 26 Device Driver Layer ees EE cueceoeteresssoedeertesecuenses 26 CPU AVON E 26 RTOS E 27 DireCtOnes and FCS zeguer eaae a eaaa aa Aa a aeaa a eaP ERa eaea 28 Appltcatton KO olo a E E A T E 31 GPU EE 33 Board Support Package BSP een 34 uC CPU CPU Specific Source Code ssssssssssesesenenennnnnnnnunnnnnnnnnnnnnnnn 35 uC LIB Portable Library Functions eeeeeeeeeeee eee eeeeeeeeeeeeeeees 37 yuC Clk Time Calendar Management
317. rned error values may be useful while debugging a port LC 10 Return no error The data has been transferred already to the memory buffer using DMA 483 LUC FS Porting Manual C 12 6 FSDev_SD_Card_BSP_CmdDataWr void FSDev_SD Card BSP CmdDataWr FS OI unit_nbr FS_ DEV _ SD CARD CMD p cmd void p src FS_ERR p err File Called from Code enabled by fs_dev_sd_card_bsp c FSDev_SD_Card_WrData N A Write data following a command ARGUMENTS unit_nbr Unit number of SD MMC card p_cmd Pointer to command that was started p sre Pointer to source buffer p err Pointer to variable that will receive the return error code from this function FS_DEV_SD CARD ERR NONE No error FS_DEV_SD CARD ERR NO CARD No card present FS DEV GD CARD ERR UNKNOWN Unknown or other error FS _DEV_SD CARD ERR WAIT TIMEOUT Timeout in waiting for data FS DEV _ SD CARD ERR DATA UNDERRUN Data underrun FS DEV SD CARD ERR DATA CHKSUM Error in data checksum FS DEV SD CARD ERR DATA START BIT Data start bit error FS _DEV_SD CARD ERR DATA Other data error RETURNED VALUE None NOTES WARNINGS None 484 LUC FS Porting Manual EXAMPLE The implementation of FSDev_SD_Card_BSP_CmdDataWr in Listing C 11 is targeted for the same host controller as the other listings in this chapter for more information see FSDev_SD Card BSP _CmdStart void FSDev_SD_Card BSP_CmdDataWr FS_QTY unit_nbr FS_DEV_SD CARD CMD p
318. rror returned Start command execution FSDev_SD_Card_BSP_CmdStart Error returned Wait for command to execute and response to be returned FSDev_SD_Card_BSP_CmdWaitEnd FSDev_SD_Card_BSP_CmdDataWr FSDev_SD_Card_BSP_CmdDataRd Figure C 5 Command execution The remaining functions either investigate host capabilities GetBlkCntMax GetBusWidthMax or set operational parameters SetBusWidth SetClkFreq SetTimeoutData SetTimeoutResp Together these function sets help configure a new card upon insertion Note that the parameters configured by the set functions belong to the card not the slot if multiple cards may be multiplexed in a single slot these must be saved when set and restored whenever Lock is called Two elements of host behavior routinely influence implementation and require design choices First block data can typically be read written either directly from a FIFO or transferred automatically by the peripheral to from a memory buffer with DMA While the former approach may be simpler no DMA controller need be setup it may not be reliable Unless the host can stop the host clock upon FIFO underrun for write or overrun for read effectively pausing the operation from the card s perspective transfers at high clock frequency or multiple bus configurations will probably fail Interrupts or other tasks can interrupt the operation or the CPU just may be unable to fill th
319. rs encountered in the previous file access and subsequent accesses will fail under certain conditions outlined here unless these flags are explicitly cleared using fs_clearerr There are actually two sets of flags One reflects whether the file encountered the end of file EOF during the previous access and if this is set writes will not fail but reads will fail The other reflects device errors and no subsequent file access will succeed except file close unless this is first cleared The functions fs_ferror and fs_feof can be used to get the state of device error and EOF conditions respectively 6 3 5 ATOMIC FILE OPERATIONS USING FILE LOCK If a file is shared between several tasks in an application the file lock can be employed to guarantee that a series of file operations are executed atomically fs flockfile or its non blocking equivalent fs_ftrylockfile acquires the lock for a task Gf it does not already own it Accesses from other tasks will be blocked until f s_funlockfile is called Each file actually has a lock count associated with it This allows nested calls by a task to acquire a file lock each of those calls must be matched with a call to s_funlockfile void App Fnct void unsigned char datal 50 unsigned char data2 10 if App FilePtr FS FILE 0 fs_flockfile App FilePtr Lock file f See Note 1 Wr data atomically af fs_fwrite datal 1 sizeof datal App FileP
320. s Concepts will be introduced as needed 4 1 NOMENCLATURE This manual uses a set of terms to consistently describe operation of uC FS and its hardware and software environment The following is a small list of these terms with definitions A file system suite is software which can find and access files and directories Using file system suite rather than file system eliminates any need for disambiguation among the second term s several meanings which include a system for organizing directories and files a collection of files and directories stored on a drive and commonly the software which will be referred to as a file system suite The term file system will always mean a collection of files and directories stored on a drive or in this document volume A device driver or just driver is a code module which allows the general purpose file system suite to access a specific type of device A device driver is registered with the file system suite A device is an instance of a device type that is accessed using a device driver An addressable area typically of 512 bytes on a device is a sector A sector is the smallest area that from the file system suite s point of view can be atomically read or written Several devices can use the same device driver These are distinguished by each having a unique unit number Consequently lt DEVICE NAME gt lt UNIT NUMBER gt is a unique device identifier if all dev
321. s October 2004 www misra c com 561 Appendix G 562 Appendix UC FS Licensing Policy H 1 yC FS LICENSING H 1 1 pC FS SOURCE CODE This book contains pC FS precompiled in linkable object form an evaluation board and tools compiler assembler linker debugger Use uC FS for free as long as it is only used with the evaluation board that accompanies this book You will need to purchase a license when using this code in a commercial product where the intent is to make a profit Users do not pay anything beyond the price of the book evaluation board and tools as long as they are used for educational purposes You will need to license pC FS if you intend to use pC FS in a commercial product where you intend to make a profit You need to purchase this license when you make the decision to use uC FS in a design not when you are ready to go to production If you are unsure about whether you need to obtain a license for your application please contact Micrium and discuss your use with a sales representative Contact Micrium Micrium 1290 Weston Road Suite 306 Weston FL 33326 1 954 217 2036 1 954 217 2037 FAX E Mail sales Micrium com Website www Micriym com 563 Appendix H H 1 2 C FS MAINTENANCE RENEWAL Licensing uC FS provides one year of limited technical support and maintenance and source code updates Renew the maintenance agreement for continued support and source code updates Contact sales Micrim com f
322. s and code to read switches and temperature sensors At Micrium we like to encapsulate CPU functionality These files define functions to disable and enable interrupts data types e g CPU_INTO8U CPU_FP32 independent of the CPU and compiler and many more functions uC LIB consists of a group of source files to provide common functions for memory copy string manipulation and character mapping Some of the functions replace stdlib functions provided by the compiler These are provided to ensure that they are fully portable from application to application and most importantly from compiler to compiler pC Clk is an independant clock calendar management module with source code for easily managing date and time in a product uC FS uses the date and time information from pC Clk to update files and directories with the proper creation modification access time uC CRC is a stand alone module for calculating checksums and error correction codes This module is used by some of uC FS device drivers This is the pC FS platform independent code free of dependencies on CPU and memory device This code is written in highly portable ANSI C code This code is only available to C FS licensees 30 F3 19 F3 1 10 F3 1 11 F3 1 12 F3 1 13 Directories and Files This is the uC FS system driver for FAT file systems This code is only available to uC FS licensees This is the collection of device drivers for uC FS Each driver sup
323. s state includes the file position the next place data will be read written error conditions and if file buffering is enabled the state of any file buffer Function Description FSFile BufAssign Assign buffer to a file FSFile BufFlush Write buffered data to volume FSFile Close Close a file FSFile ClrErr Clear error s on a file FSFile IsEOF Determine whether a file is at EOF FSFile IsErr Determine whether error occurred on a file FSFile_IsOpen Determine whether a file is open or not FSFile_LockGet FSFile_LockSet Acquire task ownership of a file Release task ownership of a file FSFile_ LockAccept Acquire task ownership of a file if available FSFile Open Open a file FSFile_PosGet Get file position FSFile_PosSet Set file position FSFile Query Get information about a file FSFile Rd Read from a file FSFile Truncate FSFile Wr Truncate a file Write to a file 98 Files Table 7 1 File Access Functions 7 1 1 OPENING FILES When an application needs to access a file it must first open it using fs_fopen or FSFile Open For most applications the former with its familiar interface suffices In some cases the flexibility of the latter is demanded file ptr gt p file FSFile Open file txt lt file name FS_FILE ACCESS MODE RD lt
324. s_dev_msc c fs_dev_msc h NAND fs_dev_nand c fs_dev_nand h PHY fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h fs_dev_nand_0512_x08 c fs_dev_nand_0512_x08 h Template fs_dev_nand_template c 46 Directories and Files fs_dev_nand_template h BSP Template fs_dev_nand_bsp c BSP Template GPIO fs_dev_nand_bsp c BSP Template SPI GPIO fs_dev_nand_bsp c BSP Template SPI fs_dev_nand_bsp c NOR fs_dev_nor c fs_dev_nor h PHY fs_dev_nor_amd_1x08 c fs_dev_nor_amd_1x08 h fs_dev_nor_amd_1x16 c fs_dev_nor_amd_1x16 h fs_dev_nor_intel c fs_dev_nor_intel h fs_dev_nor_sst25 c fs_dev_nor_sst25 h fs_dev_nor_sst39 c fs_dev_nor_sst39 h fs_dev_nor_stm25 c fs_dev_nor_stm25 h fs_dev_nor_stm29_1x08 c fs_dev_nor_stm29_1x08 h fs_dev_nor_stm29_1x16 c fs_dev_nor_stm29_1x16 h Template fs_dev_nor _template c fs_dev_nor_template h BSP Template fs_dev_nor_bsp c BSP Template SPI GPIO fs_dev_nor_bsp c BSP Template SPI fs_dev_nor_bsp c 47 Directories and Files RAMDisk fs_dev_ram c fs_dev_ram h SD fs_dev_sd c fs_dev_sd h Card fs_dev_sd_card c fs_dev_sd_card h BSP Template fs_dev_sd_card_bsp c SPI fs_dev_sd_spi c fs_dev_sd_spi h BSP Template fs_dev_sd_spi bsp c Template fs_dev_template c fs_dev_template h Micrium This directory contains all software compone
325. s_localtime r localtime_r fs feof feof fs_mkdir mkdir fs ferror ferror fs_mktime mktime fs fflush fflush fs_rewind rewind fs_fgetpos fgetpos fs_opendir opendir Ce flockfile flockfile fs readdir_ CO readdir CO fs_fopen fopen fs_remove remove fs_fread fread fs_rename rename 84 POSIX API Function POSIX Equivalent Function POSIX Equivalent fs_fseek fseek fs_rmdir rmdir fs_fsetpos fsetpos fs_setbuf setbuf fs_fstat fstat fs_setvbuf setvbuf fs_ftell ftell fs_stat stat Table 6 1 POSIX API functions 6 2 WORKING DIRECTORY FUNCTIONS Normally all file or directory paths must be absolute either on the default volume or on an explicitly specified volume p_filel fs_fopen file txt r File on default volume p_file2 fs_fopen sdcard 0 file txt ri File on explicitly specified volume If working directory functionality is enabled paths may be specified relative to the working directory of the current task p_file2 fs_fopen file txt r File in working directory p_filel fs_fopen file txt r File in parent of working directory oo The two standard special path components are supported The path component moves om to the parent of the current working directory The path component makes no change essen
326. se this should ONLY be called when a device is open 2 The device driver Rd function is called while the caller holds the device lock C 4 6 Wr static void FSDev Wr FS_DEV p dev void p src FS_SEC_ MR start FS_SEC QTY cnt FS_ERR p err File Called from Code enabled by fs_dev_ H c FSDev_WrLocked N A The device driver Wr function should write to a device the data from a buffer If an error is returned the file system suite assumes that no data has been written ARGUMENTS p_dev Pointer to device to write to p sre Pointer to source buffer start Start sector of write cnt Number of sectors to write 402 LUC FS Porting Manual p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Sector s written FS_ERR_DEV_INVALID UNIT NR Device unit number is invalid FS_ERR_DEV_IO Device I O error PG ERR DEV MO ODEN Device is not open FS_ERR_DEV_NOT_ PRESENT Device is not present FS_ERR_DEV_TIMEOUT Device timeout RETURNED VALUE None NOTES WARNINGS 1 Tracking whether a device is open is not necessary because this should ONLY be called when a device is open 2 The device driver Wr function is called while the caller holds the device lock 403 LUC FS Porting Manual C 4 7 Query static void FSDev_ H Query FS_DEV p dev FS DEV INFO p info FS_ERR p err File Called from Code enabled by fs_dev_ HH c FSDev_Open N A
327. sical layer may need to be modified In all cases the manufacturetr s reference should be compared to the driver description below Driver API Files Description FSDev_NOR_AMD 1x08 fs_dev_nor_amd_1x08 Supports CFl compatible devices with 8 bit data bus implementing AMD command set FSDev_NOR_AMD 1x16 fs_dev_nor_amd_1x16 Supports CFl compatible devices i with 16 bit data bus mplementing AMD command set FSDev_NOR_Intel_1x16 fs_dev_nor_intel Supports CFl compatible devices i with 16 bit data bus mplementing Intel command set FSDev_NOR_SST39 fs_dev_nor_sst39 Supports various SST SST39 devices with 16 bit data bus FSDev_NOR_STM29_ 1x08 fs_dev_nor_stm29 1x08 Supports various ST M29 devices with 8 bit data bus FSDev_NOR_STM29_ 1x16 fs_dev_nor_stm29 1x16 Supports various ST M29 devices with 16 bit data bus FSDev_NOR_STM25 FSDev_NOR_SST25 fs_dev_nor_stm25 fs_dev_nor_sst25 Supports various ST M25 serial devices Supports various SST SST25 serial devices Table 15 6 Physical layer drivers 166 NOR Flash Driver 15 5 1 FSDEV_NOR_AMD_1X08 FSDEV_NOR_AMD_1X16 FSDev_NOR_AMD 1x08 and FSDev_NOR_AMD 1x16 support CFI NOR flash implementing AMD command set including E Most AMD and Spansion devices E Most ST Numonyx devices E Others The fast programming command write to buffer and program supported by many flash implementi
328. suits your project product Micrium Software CPU lt manufacturer gt lt architecture gt Micrium This is where we place all software components and projects provided by Micrium Software This sub directory contains all the software components and projects CPU This sub directory is always called CPU lt manufacturer gt Is the name of the semiconductor manufacturer who provided the peripheral library The lt and gt are not part of the actual name lt architecture gt This is the name of the specific library and is generally associated with a CPU name or an architecture Vi k These are the library source files The names of the files are determined by the semiconductor manufacturer 33 Directories and Files 3 3 BOARD SUPPORT PACKAGE BSP The BSP is generally found with the evaluation or target board because the BSP is specific to that board In fact if well written the BSP should be used for multiple projects Micrium Software EvalBoards lt manufacturer gt lt board name gt lt compiler gt BSP Micrium This is where we place all software components and projects provided by Micrium Software This sub directory contains all the software components and projects EvalBoards This sub directory contains all the projects related to evaluation boards lt manufacturer gt Is the name of the manufacturer of the evaluation board The lt and
329. t can be added It MUST be greater than or equal to 1 MaxSecSize Maximum sector size in octets It must be 512 1024 2048 or 4096 No device with a sector size larger than MaxSecSize can be opened NOTES None 509 D 2 FS_DEV_INFO typedef struct fs_dev_info FS STATE State FS SEC QTY Size FS_SEC_ SIZE SecSize CPU_BOOLEAN Fixed FS_DEV_INFO File LIC FS Types and Structures Used for fs_dev h Receives information about a device MEMBERS State The device state FS DEV STATE CLOSED FS DEV STATE CLOSING FS DEV STATE OPENING FS DEV STATE OPEN FS DEV STATE PRESENT Second argument of FSDev_Query Device is closed Device is closing Device is opening Device is open but not present Device is present but not low level formatted FS DEV STATE LOW FMT VALID Device low level format is valid Size The number of sectors on the device SecSize The size of each device sector Fixed Indicates whether the device is fixed or removable NOTES None 510 LC FS Types and Structures D 3 FS_DEV_NAND CFG typedef struct fs deu nand cfg CPU_INT32U BlkNbrFirst FS SEC SIZE SecSize CPU_INT32U BlkCnt CPU_INTO8U RBCnt FS DEV HAND PHY API PhyPtr CPU_INTO8U BusWidth CPU_INT32U MaxClkFreq FS_DEV_NAND CFG File Used for fs_dev_nand h Second argument of FSDev_Open when opening a NAND device Configures the properties of a NAND device that will be o
330. table uC FS was designed for resource constrained embedded applications Although uC FS can work on 8 and 16 bit processors it will work best with 32 or 64 bit CPUs RTOS uC FS does not assume the presence of a RTOS kernel However if you are using a RTOS a simple port layer is required consisting of a few semaphores in order to prevent simultaneous access to core structures from different tasks If you are not using a RTOS this port layer may consist of empty functions 1 3 TYPICAL USAGES Applications have sundry reasons for non volatile storage A subset require or benefit from organizing data into named files within a directory hierarchy on a volume basically from having a file system Perhaps the most obvious expose the structure of information to the user like products that store images video or music that are transferred to or from a PC A web interface poses a similar opportunity since the URLs of pages and images fetched by the remote browser would resolve neatly to locations on a volume Another typical use is data logging A primary purpose of a device may be to collect data from its environment for later retrieval If the information must persist across device reset events or will exceed the capacity of its RAM some non volatile memory is necessary The benefit of a file system is the ability to organize that information logically with a fitting directory structure through a familiar API A file system can also stor
331. tatus BIT_INTERRUPT_STATUS ERROR BIT_INTERRUPT_STATUS_TRANSFER_COMPLETE DEF_YES timeout interrupt_status REG _INTERRUPT_STATUS if timeout TIMEOUT_TRANSFER_MAX p err FS DEV_SD CARD ERR WAIT TIMEOUT return Handle error eo 24 if DEF_BIT_IS SET interrupt_status BIT_INTERRUPT_STATUS ERROR DEF_YES error_status REG ERROR_STATUS if DEF_BIT_IS SET error_status REG ERROR_STATUS DATA END BIT DEF_YES p err FS DEV_SD CARD ERR_DATA else if DEF_BIT IS SET error_status REG ERROR STATUS DATA CRC DEF_YES p err FS DEV SD CARD ERR DATA CRC else if DEF_BIT IS SET error_status REG ERROR STATUS DATA TIMEOUT DEF YES FS_DEV_SD_CARD_ERR_DATA TIMEOUT p err else p err FS_DEV_SD_CARD_ERR_UNKONWN REG_ERROR_STATUS REG_INTERRUPT_STATUS return error_status interrupt_status p err FS DEV SD CARD ERR NONE 3 Listing C 10 FSDev_SD_Card_BSP_CmdDataRd 482 LUC FS Porting Manual LC 10 1 Wait until data transfer completes or an error occurs The wait loop or wait on semaphore SHOULD always have a timeout to avoid blocking the task in the case of an unforeseen hardware malfunction or a software flaw LC 10 2 Check if an error occurred The error status register is decoded to produce the actual error condition That is not necessary strictly but error counters that accumulate within the generic driver based upon retu
332. ted it will never be called 421 LUC FS Porting Manual C 5 12 FSDev_IDE_BSP_GetDrvNbr CPU_INTO8U FSDev_IDE BSP_GetDrvNbr FS OTY unit_nbr File Called from Code enabled by fs_dev_ide_bsp c FSDev_IDE_Refresh N A Get IDE CF driver number ARGUMENTS unit_nbr Unit number of IDE CF device RETURNED VALUE Drive number 0 or 1 NOTES WARNINGS Two IDE devices may be accessed on the same bus by setting the DEV bit of the drive head register If the bit should be clear this function should return 0 if the bit should be set this function should return 1 422 LUC FS Porting Manual C 5 13 FSDev_IDE_BSP_GetModesSupported FS FLAGS FSDev_IDE BSP _GetModesSupported PG Om unit_nbr File Called from Code enabled by fs_dev_ide_bsp c FSDev_IDE_Refresh N A Get supported transfer modes ARGUMENTS unit_nbr Unit number of IDE CF device RETURNED VALUE Bit mapped variable indicating supported transfer mode s should be the bitwise OR of one or more of FS DEV_IDE MODE TYPE PIO PIO mode supported FS_DEV_IDE MODE TYPE DMA Multiword DMA mode supported FS _DEV_IDE MODE TYPE UDMA Ultra DMA mode supported NOTES WARNINGS None 423 LUC FS Porting Manual C 5 14 FSDev_IDE_BSP_SetMode CPU_INTO8U FSDev_ IDE BSP SetMode FS QTY unit_nbr FS_FLAGS mode_type CPU_INTO8U mode File Called from Code enabled by fs_dev_ide bsp c FSDev_IDE_Refresh N A
333. tems to read p file Pointer to a file RETURNED VALUE Number of items read NOTES WARNINGS 1 The size or nitems is 0 then the file is unchanged and zero is returned 2 If the file is buffered and the last operation is output write then a call to fs_flush or fs_fsetpos or fs_fseek MUST occur before input read can be performed 3 The file must have been opened in read or update read write mode 222 A 2 14 fs_fseek LC FS API Reference Manual int fs_fseek FS_FILE p file long int offset int origin File Called from Code enabled by fs_api c FS_CFG API_EN Application fs_frewind Set file position indicator ARGUMENTS p file Pointer to a file offset Offset from the file position specified by whence origin Reference position for offset FS SEEK SET FS SEEK CUR FS SEEK END RETURNED VALUE 0 if the function succeeds 1 otherwise Offset is from the beginning of the file Offset is from the current file position Offset is from the end of the file 223 LC FS API Reference Manual NOTES WARNINGS 1 Ifa read or write error occurs the error indicator shall be set 2 The new file position measured in bytes form the beginning of the file is obtained by adding offset to a 0 the beginning of the file if whence is FS_SEEK SET b the current file position if whence is FS_SEEK_ CUR c the file size if whence is FS_SEEK_END 3 The end of file indicato
334. ters see section D 3 FS_DEV_NAND_CFG on page 511 143 NAND Flash Driver 114 13 FSDev_Open opens initializes a file system device The parameters are the device name a and a pointer to a device driver specific configuration structure 3b The device name 3a s composed of a device driver name Cnand a single colon an ASCII formatted integer the unit number and another colon 114 1 4 FSDev_NAND_LowFmt low level formats a NAND If the NAND has never been used with uC FS it must be low level formatted before being used Low level formatting will associate logical sectors with physical areas of the device FSVol_Open opens mounts a volume The parameters are the volume name 5a the device name 5b and the partition that will be opened Sc There is no restriction on the volume name 5a however it is typical to give the volume the same name as the underlying device If the default partition is to be opened or if the device is not partition then the partition number 5c should be zero FSVol_Fmt formats a file system device If the NAND has just been low level formatted there will be no file system on it after it is opened it will be unformatted and must be formatted before files can be created or accessed 144 NAND Flash Driver If the NAND initialization succeeds the file system will produce the trace output as shown in Figure 14 1 Gf a sufficiently high trace level is configured See section E 9
335. text working directories are valuable Once a working directory is set for a task subsequent non absolute paths will be interpreted relative to the set directory if FS_CFG WORKING DIR EN DEF_ENABLED CPU_CHAR FS OS WorkingDirGet void 1 OS_ERR Os_err CPU_INT32U reg_val CPU_CHAR p working dir reg_val OSTaskRegGet OS_TCB 0 PS OS REG ID WORKING DIR amp OS_err if os_err OS _ERR_NONE reg_val 0u p_working dir CPU_CHAR reg val return p working dir endif if FS_CFG WORKING DIR_EN DEF ENABLED void FS OS WorkingDirSet CPU_CHAR p working dir 2 OS_ERR Os_err CPU_INT32U reg_val reg_val CPU_INT32U p working dir OSTaskRegSet OS_TCB 0 FS OS REG ID WORKING DIR reg_val amp OS err void amp os_err endif Listing C 1 FS_OS_WorkingDirGet Set uC OS III LC 1 1 FS OG WorkingDirGet gets the pointer to the working directory associated with the active task In pC OS III the pointer is stored in one of the task registers a set of software data that is part of the task context Gust like hardware register values The implantation casts the integral register value to a 388 LUC FS Porting Manual pointer to a character If no working directory has been assigned the return value must be a pointer to NULL In the case of uC OS II that will be done because the register values are cleared upon task creation LC 1 2 FS_OS WorkingDirSet asso
336. th will be read or written Individual devices or drivers may also integrate a cache Standard hard drives overcome long seek times by buffering extra data upon read in anticipation of future requests or clumping writes to eliminate unnecessary movement The latter action can be particularly powerful but since it may involve re ordering the sequence of sector writes will eliminate any guarantee of fail safety of most file systems For that reason write cache in most storage devices should be disabled A driver may implement a buffer to reduce apparent write latency Before a write can occur to a flash medium the driver must find a free erased area of a block occasionally a block will need to be erased to make room for the next write Incoming data can be buffered while the long erase occurs in the background thereby uncoupling the application s wait time from the real maximum flash write time The ideal system might use both volume cache and file buffers A volume cache is most powerful when confined to the sector types most subject to repeated reads management and directory Caching of files if enabled should be limited to important often read files File buffers are more flexible since they cater to the many applications that find small reads and writes more convenient than those of full sectors 82 Chapter POSIX API The best known API for accessing and managing files and directories is specified within the POSIX standard
337. the card and the accepted voltage range The OCR register read with SD_SEND_OP_COND or SEND_OP_COND assumes basically the same format for all card types Finally the CID card ID and CSD card specific data registers are read the only times long 132 bit responses are returned Multiple bit initialization often 4 bit when performed on a SD card further confirms that the 8 byte SCR register and 64 byte SD status can be read and that the bus width can be set in the BSP Though all current cards support 4 bit mode operation the SD_BUS WIDTHS field of the SCR is checked before configure the card bus width Afterwards the 64 byte SD status is read to see whether the bus width change was accomplished When first debugging a port it may be best to force multi bit operation disabled by returning 1 from the BSP function FSDev_SD_Card_BSP_GetBusWidthMax 183 Power On GO_IDLE_STATE Invalid 1 SD MMC Drivers Inactive state command SEND_IF_COND 2 Valid command Invalid command SD_SEND_OP_COND SD_SEND_OP_COND 3 3 Vv g 3 D Go SEND OP COND ee READ_OCR 4 Vv y READ_OCR CCS in 5 response v v v v MMC V1 x Standard V2 0 Standard V2 0 High Capacity SD card Capacity SD card Capacity SD card Vv e SEND_CID 6 g S en TE ET e voa e A S SEND_CSD 7 Figure 17 4 Simplified SD MMC
338. the entire device After this call the device will be divided as shown in Figure 5 5 This new partition is called a primary partition because its entry is in the MBR The four circles in the MBR represent the four partition entries the one that is now used points to Primary Partition 1 Primary Partition 1 Unallocated space 256 MB 759 Figure 5 5 Device after partition initialization 73 Devices and Volumes More partitions can now be created on the device Since the MBR has four partition entries three more can be made without using extended partitions as discussed below The function FSDev_PartitionAddO should be called three times FSDev_PartitionAdd CPU_CHAR ide 0 lt a device name ES SEC OTY 512 1024 lt b size of partition FS_ERR amp err lt c return error Again the parameters are the device name a and the size of the partition in sectors b After this has been done the device is divided as shown in Figure 5 6 M B R Primary Primary Primary Primary L Partition 1 Partition 2 Partition 3 Partition 4 D 256 MB 256 MB 256 MB 256 MB Figure 5 6 Device after four partitions have been created When first instituted DOS partitioning was a simple scheme allowing up to four partitions each with an entry in the MBR It was later extended for larger devices requiring more with extended par
339. things as the C data type corresponding to 16 bit and 32 bit variables whether the CPU is little or big endian and how interrupts are disabled and enabled on the CPU etc 26 LIC FS Architecture CPU specific files are found in the uC CPU directory and in order to adapt uC FS to a different CPU you would need to either modify the cpu files or create new ones based on the ones supplied in the uC CPU directory In general it s much easier to modify existing files because you have a better chance of not forgetting anything 2 1 8 RTOS LAYER uC FS does not require an RTOS However if C FS is used with an RTOS a set of functions must be implemented to prevent simultaneous access of devices and core uC FS structures by multiple tasks uC FS is provided with a no RTOS which contains just empty functions a wC OS II and a pC OS III interface If you use a different RTOS you can use the fs_os for pC OS II as a template to interface to the RTOS of your choice 27 Chapter Directories and Files HC FS is fairly easy to use once you understand which source files are needed to make up a C FS based application This chapter will discuss the modules available for uC FS and how everything fits together Figure 1 01 shows the uC FS architecture and its relationship with the hardware Memory devices may include actual media both removable SD MMC CF cards and fixed NAND flash NOR flash as well as any controllers for such
340. tially it means the current working directory fs_chdir is used to set the working directory If a relative path is employed before any working directory is set the root directory of the default volume is used The application can get the working directory with fs_getcwd A terminal interface may use this function to implement an equivalent to the standard pwd print working directory command while calling fs _chdir to carry out a cd operation If working directories are enabled the pC Shell commands for uC FS manipulate and access the working directory with fs_chdir and fs_getcwd see also Appendix F Shell Commands on page 535 85 POSIX API 6 3 FILE ACCESS FUNCTIONS The file access functions provide an API for performing a sequence of operations on a file located on a volume s file system The file object pointer returned when a file is opened is passed as an argument of all file access function and the file object so referenced maintains information about the actual file on the volume and the state of the file access The file access state includes the file position the next place data will be read written error conditions and if file buffering is enabled the state of any file buffer As data is read from or written to a file the file position is incremented by the number of bytes transferred from to the volume The file position may also be directly manipulated by the application using the position set func
341. tion fs_fsetpos and the current absolute file position may be gotten with the position get function s_fgetpos to be later used with the position set function Must be Closed Open E Figure 6 1 File state transitions 86 POSIX API The file maintains flags that reflect errors encountered in the previous file access and subsequent accesses will fail under certain conditions outlined here unless these flags are explicitly cleared using fs_clearerr There are actually two sets of flags One reflects whether the file encountered the end of file EOF during the previous access and if this is set writes will not fail but reads will fail The other reflects device errors and no subsequent file access will succeed except file close unless this is first cleared The functions fs_ferror and fs _feof can be used to get the state of device error and EOF conditions respectively If file buffering is enabled FS_CFG FILE BUF_EN is DEF ENABLED then input output buffering capabilities can be used to increase the efficiency of file reads and writes A buffer can be assigned to a file using fs_setbuf or fs_setvbuf the contents of the buffer can be flushed to the storage device using fs_fflush If a file is shared between several tasks in an application a file lock can be employed to guarantee that a series of file operations are executed atomically fs_flockfile or its non blocking equivalent fs_ftrylo
342. tionFind CPU_CHAR name_dev PG PARTITION NBR partition_nbr FS PARTITION ENTRY p partition entry FS_ERR p err File Called from Code enabled by fs_dev c Application FS_CFG_PARTITION_EN Find a partition on a device See also section 5 4 Partitions on page 72 ARGUMENTS name_dev Device name partition_nbr Index of the partition to find p partition entry Pointer to variable that will receive the partition information p err Pointer to variable that will receive return error code from this function FS_ERR_NONE Partition found FS_ERR_DEV_VOL_OPEN Volume open on device FS_ERR_INVALID PARTITION Invalid partition FS_ERR_INVALID SEC NBR Sector start or count invalid FS_ERR_INVALID SIG Invalid MBR signature FG ERR NAME NULL Argument name_dev passed a NULL pointer FS_ERR NULL PTR Argument p partition_entry passed a NULL pointer Or device access error see section B 4 Device Error Codes on page 377 257 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS Device state change will result from device I O not present or timeout error 258 A 3 9 FSDev_PartitionInit void FSDev_ PartitionInit CPU_CHAR LC FS API Reference Manual name_dev FS_SEC_QTY partition_size FS_ERR p err File Called from Code enabled by fs deu not FS_CFG_RD_ONLY_EN Application Initialize the partition structure on a device See also section 5 4 Partitions on page 72
343. titions partitions that contains other partitions The primary extended partition is the extended partition with its entry in the MBR it should be the last occupied entry 74 Devices and Volumes An extended partition begins with a partition table that has up to two entries typically The first defines a secondary partition which may contain a file system The second may define another extended partition in this case a secondary extended partition which can contain yet another secondary partition and secondary extended partition Basically the primary extended partition heads a linked list of partitions M B R CN oO Primary SS g SS 2 Primary L Partition 1 E Sol ES o Extended Partition e 256 MB e 5 Sa 5 512 MB e Secondary Partition Partition 4 256 MB O00 Secondary Extended Partition 256 MB Secondary Partition Partition 5 256 MB Figure 5 7 Device with five partitions For the moment extended partitions are not supported in pC FS 75 5 5 VOLUME OPERATIONS Five general operations can be performed on a volume Devices and Volumes E A volume can be opened mounted During the opening of a volume file system control structures are read from the underlying device parsed and verified Files can be accessed on a volume A file is a linear data sequence file contents asso
344. tr fs_fwrite data2 1 sizeof datal App FilePtr fs_funlockfile App FilePtr Unlock file Listing 6 4 Example file lock usage 93 POSIX API L6 4 1 fs_flockfile will block the calling task until the file is available If the task must write to the file only if no other task is currently accessing it the non blocking function fs_funlockfile can be used 6 4 DIRECTORY ACCESS FUNCTIONS The directory access functions provide an API for iterating through the entries within a directory The fs_opendir function initiates this procedure and each subsequent call to fs readdir r until all entries have been examined returns information about a particular entry in a struct fs_dirent The fs_closedir function releases any file system structures and locks Figure 6 2 gives an example using the directory access functions to list the files in a directory An example result of listing a directory is shown in Figure 4 1 void App Fnct void FS_DIR p dir struct fs_dirent dirent struct fs_dirent p dirent char str 50 char p_cwd_path fs_time_t ts p_dir fs_opendir p cwd_path Open dir if p dir FS_DIR 0 void fs_readdir_r pdir amp dirent amp p dirent Rd first dir entry if p dirent FS_DIRENT 0 If NULL dir is empty APP_TRACE_INFO Empty dir s r n p cwd_path else Fmt info for each entry Str_Copy str r r r 3 mz while p_dirent
345. try shall be a directory FS ENTRY TYPE FILE ifthe entry shall be a file excl Indicates whether the creation of the new entry shall be exclusive see Note 1 DEF_YES if the entry shall be created only if p_name full does not exist DEF_NO if the entry shall be created even if p name full does exist p err Pointer to variable that will the receive return error code from this function FS_ERR_NONE Entry created successfully FS_ERR_NULL PTR Argument name full passed a NULL pointer FS_ERR_ NAME INVALID Entry name specified invalid OR volume could not be found 278 FS ERR MAME PATH TOO LONG FS_ERR_VOL NOT OPEN FS_ERR_VOL NOT MOUNTED FS ERR BUF NONE AVAIL FS_ERR_DEV Or entry error RETURNED VALUE None NOTES WARNINGS LC FS API Reference Manual Entry name specified too long Volume was not open Volume was not mounted Buffer not available Device access error 1 If the entry exists and is a file entry_type is FS_ENTRY_TYPE_FILE and excl is DEE MO then the existing entry will be truncated If the entry exists and is a directory and entry_type is FS_ENTRY_TYPE_DIR then no change will be made to the file system 2 If the entry exists and is a directory dir is DEF_NO and excl is DEF_NO then no change will be made to the file system Similarly if the entry exists and is a file dir is DEF_YES and excl is DEF_NO then no change will be made to the file system 3 The root directory may not be created
346. try_AttribSet path_name lt pointer to full path name attrib lt attributes amp err lt return error FS_ENTRY ATTRIB RD Entry is readable FS_ENTRY ATTRIB WR Entry is writable FS_ENTRY ATTRIB HIDDEN Entry is hidden from user level processes If a flag is clear not OR d in then that attribute will be clear In the example above the entry will be made read only i e not writable and will be visible G e not hidden since the WR and HIDDEN flags are not set in attrib Since there is no way to make files write only Oe not readable the RD flag should always be set 7 2 2 CREATING NEW FILES AND DIRECTORIES A new file can be created using FSFile_ Open or fs fopen if opened in write or append mode There are a few other ways that new files can be created most of which also apply to new directories The simplest is the FSEntry_Create function which just makes a new file or directory FSEntry_Create file txt lt file name FS_ENTRY_TYPE FILE lt means entry will be a file DEF_NO lt DEF_NO means creation NOT exclusive amp err lt return error If the second argument entry _type is FS_ENTRY_TYPE DIR the new entry will be a directory The third argument excl indicates whether the creation should be exclusive If it is exclusive excl is DEF_YES nothing will happen if the file already exists Otherwise the file currently specified by the file name will be deleted and a new empty
347. type of file system For example this file system suite includes a FAT file system driver FAT File Allocation Table is a common file system type prevalent in removable media that must work with various OSs It is named after its primary data structure a large table that records what clusters of the disk are allocated A cluster or group of sectors is the minimum data allocation unit of the FAT file system 60 Miscellaneous 4 2 C FS DEVICE AND VOLUME NAMES Devices are specified by name For example a device can be opened FSDev_Open sd 0 void 0 amp err In this case sd 0 is the device name It is a concatenation of sd The name of the device driver A single colon 0 The unit number A final colon The unit number allows multiple devices of the same type for example there could be several SD MMC devices connected to the CPU sd 0 sd 1 sd 2 The maximum length of a device name is FS_CFG MAX DEV_NAME LEN this must be at least three characters larger than the maximum length of a device driver name FS CFG MAX DEV DRV NAME LEN A device name or device driver name must not contain the characters Volumes are also specified by name For example a volume can be formatted FSVol_Fmt vol void 0 amp err Here vol is the volume name pC FS imposes no restrictions on these names except that they must end with a colon must be no more than FS_CFG MAX VOL NAME
348. typical serial flash The command and response both divide into 8 bit chunks the transfer unit for the device Within these units the data is transferred from most significant bit MSB to least significant bit LSB which is the slave s shift direction Though not evident from the diagram the horizontal axis being labeled in clocks rather than time the slave cannot operate at a frequency higher than 20 MHz Finally the clock signal prior to slave select activation is low clock polarity or CPOL is 0 and data is latched on the rising clock edge clock phase or CPHA is 0 Together those are the aspects of SPI communication that may need to be configured 494 LUC FS Porting Manual E Transfer unit length A transfer unit is the underlying unit of commands responses and data The most common value is eight bits though slaves commonly require and masters commonly support between 8 and 16 bits P Shift direction Either the MSB or LSB of each transfer unit can be the first transmitted on the data line P Clock frequency Limits are usually imposed upon the frequency of the clock signal Of all variable SPI communication parameters only this one is explicitly set by the device driver P Clock polarity and phase CPOL and CPHA SPI communication takes place in any of four modes depending on the clock phase and clock polarity settings If CPOL 0 the clock is low when inactive If CPOL 1 the clock is high when inactive
349. ual C 7 2 FSDev_NAND BSP _Close void FSDev_NAND BSP Close FS QTY unit_ nbr File Called from Code enabled by fs_dev_nand_bsp c NAND physical layer driver N A Close uninitialize bus for NAND ARGUMENTS unit_nbr Unit number of NAND RETURNED VALUE None NOTES WARNINGS This function will be called every time the device is closed 442 LUC FS Porting Manual C 7 3 FSDev_NAND_BSP_ChipSelEn void FSDev_NAND BSP _ChipSelEn FS Om unit_nbr File Called from Code enabled by fs_dev_nand_bsp c NAND physical layer driver N A Enable NAND chip select chip enable ARGUMENTS unit_nbr Unit number of NAND RETURNED VALUE None NOTES WARNINGS None 443 LUC FS Porting Manual C 7 4 FSDev_NAND_BSP_ChipSelDis void FSDev_NAND BSP_ChipSelDis FS QTY unit_nbr File Called from Code enabled by fs_dev_nand_bsp c NAND physical layer driver N A Disable NAND chip select chip enable ARGUMENTS unit_nbr Unit number of NAND RETURNED VALUE None NOTES WARNINGS None 444 LUC FS Porting Manual C 7 5 FSDev_NAND_BSP_RdData void FSDev_NAND BSP_RdData PG Om unit_nbr void p dest CPU_SIZE T cnt File Called from Code enabled by fs_dev_nand_bsp c NAND physical layer driver N A Read data from NAND ARGUMENTS unit_nbr Unit number of NAND p dest Pointer destination memory buffer cnt Number of octets to read R
350. ual NOTES WARNINGS 1 The command start will be followed by zero one or two additional BSP function calls depending on whether data should be transferred and on whether any errors occur a FSDev_SD_Card_BSP_CmdStart starts execution of the command IT may also set up the DMA transfer Gif necessary b FSDev_SD_Card_BSP_CmdWaitEnd waits for the execution of the command to end getting the command response if any c If data should transferred from the card to the host FSDev_SD Card BSP_CmdDataRd will read that data if data should be transferred from the host to the card FSDev_SD Card _BSP_CmdDataWr will write that data The command p cmd has the following parameters a p_cmd gt Cmd is the command index b p cmd gt Arg is the 32 bit argument or 0 if there is no argument c p_omd gt Flags is a bit mapped variable with zero or more command flags FS DEV ep CARD CMD FLAG INIT FS DEV SD CARD CMD FLAG BUSY FS DEV SD CARD CMD FLAG CRC VALID FS DEV SD CARD CMD FLAG IX VALID FS DEV SD CARD CMD FLAG OPEN DRAIN FS DEV SD CARD CMD FLAG DATA START FS DEV SD CARD CMD FLAG DATA STOP FS DEV SD CARD CMD FLAG RESP FS DEV SD CARD CMD FLAG RESP LONG Initialization sequence before command Busy signal expected after command CRC valid after command Index valid after command Command line is open drain Data start command Data stop command Response expected Long response expected d p_cmd gt DataDir in
351. ued LC 5 1 FS_OS SemCreate creates a semaphore in the variable p_sem For this trivial implementation FS_BSP_SEM is a integer type which stores the current count i e the number of objects available LC 5 2 FS OG SemDel deletes a semaphore created by FS_OS_SemCreate 392 LUC FS Porting Manual CPU_BOOLEAN FS OG SemPost FS_BSP_SEM p sem 4 CPU_INT16U sem val CPU_SR_ALLOC CPU_CRITICAL ENTER sem val p sem Increment semaphore value sem val p sem sem val CPU_CRITICAL EXIT return DEF_OK Listing C 6 FS_OS_Sem trivial implementations continued LC 6 3 FS_OS SemPend waits until a semaphore is signaled If a zero timeout is given the wait is possibly infinite Git never times out LC 6 4 FS_OS SemPost signals a semaphore 393 LUC FS Porting Manual C 4 DEVICE DRIVER Devices drivers for the most popular devices are already available for pC FS If you use a particular device for which no driver exist you should read this section to understand how to build your own driver A device driver is registered with the file system by passing a pointer to its API structure as the first parameter of FS_DevDrvAdd The API structure FS_DEV_APTI includes pointers to eight functions used to control and access the device const FS _DEV_API FSDev_ FSDev_ _NameGet FSDev_ _Init FSDev_ _Open FSDev_ _Close FSDev_ Rd if FS_CFG_RD_ONLY_E
352. ume label was not found Volume label is too long 381 LIC FS Error Codes B 15 OS LAYER ERROR CODES FS ERR OS LOCK FS ERR OS INIT FS ERR OS INIT LOCK FS ERR OS INIT LOCK NAME Lock not acquired OS not initialized Lock signal not successfully initialized Lock signal name not successfully initialized 382 Appendix UC FS Porting Manual uC FS adapts to its environment via a number of ports The simplest ones common to all installations interface with the application OS kernel Gf any and CPU More complicated may be ports to media drivers which require additional testing validation and optimization but many of those are still straightforward Figure C 1 diagrams the relationship between uC FS and external modules and hardware The sections in this chapter describe each require function and give hints for implementers Anyone creating a new port should first check the example ports are included in the pC FS distribution in the following directory Micrium Software uC FS Examples BSP Dev The port being contemplated may already exist failing that some similar CPU device may have already be supported 383 FC 1 1 FC 1 2 FC 133 FC 1 4 LUC FS Porting Manual 0 Clk 2 uC FS Platform Independent 3 RTOS i HC FS Drivers 4 IDE NAND NOR SD MMC Driver Driver Driver Driver 7 Controller Device Device Host Controller
353. ume open on device Invalid MBR signature Argument name_vol name_dev passed a NULL pointer Invalid partition number Partition not found Volume is already open Volume name invalid No volumes available Or device access error see section B 4 Device Error Codes on page 377 329 LC FS API Reference Manual RETURNED VALUE None NOTES WARNINGS 1 If FS_ERR_PARTITION_NOT_ FOUND is returned then no valid partition or valid file system was found on the device It is still placed on the list of used volumes however it cannot be addressed as a mounted volume eg files cannot be accessed Thereafter unless a new device is inserted the only valid commands are a FSVol_Fmt which creates a file system on the device b FSVol_Close which frees the volume structure c FSVol_Query which returns information about the device 2 If FS_ERR DEV FS ERR DEV NOT PRESENT FS ERR DEV 10 or FS_ERR DEV TIMEOUT is returned then the volume has been added to the file system though the underlying device is probably not present The volume will need to be either closed and re added or refreshed 330 LC FS API Reference Manual A 7 12 FSVol_Query void FSVol_ Query CPU_CHAR name_vol FS_VOL_INFO p info FS_ERR p err File Called from Code enabled by fs vol Application N A Obtain information about a volume ARGUMENTS name_vol Volume name p_info Pointer to structure that will re
354. unallocated portion of the device into two parts so that a volume could be located on each see section 5 4 Partitions on page 72 A device can be low level formatted Some device must be low level formatted before being used A device can be high level formatted High level formatting writes the control information for a file system to a device so that a volume on it can be mounted Essentially high level formatting is the process of creating a volume on an empty device or partition A device can be closed During the closing of a device it is uninitialized if necessary and associated structures are freed These operations and the corresponding API functions are discussed in this section For information about using device names see section 4 2 uC FS Device and Volume Names on page 61 Function Description FSDev_Close Remove device from file system FSDev_GetNbrPartitions Get number of paritions on a device FSDev_IO Ctrl Perform device I O control operation FSDev_Open Add device to file system FSDev_PartitionAdd Add partition to device 68 Devices and Volumes Function Description FSDev_PartitionFind Find partition on device and get information about partition FSDev_PartitionInit Initialize partition on device FSDev_Query Get device information FSDev_Rd Read sector on device FSDev_Refresh Refresh device in
355. unctions Rd_XX RdWord_XX WrWord_XX read data from or write data to the NOR If a single parallel NOR device will be accessed these function may be defined as macros to speed up bus accesses 15 4 USING A SERIAL NOR DEVICE When used with a serial NOR device the NOR driver is three layered as depicted in the figure below The generic NOR driver as always provides sector abstraction and performs wear leveling to make certain all blocks are used equally Below this the physical layer driver implements a particular command set to read and program the flash and erase blocks Lastly a BSP implements function to communicate with the device over SPI Device commands are executed though this BSP NOR Driver fs_dev_nor c h Provides generic driver interface e g init read write and performs wear leveling so all blocks are used equally Physical Layer Driver fs_dev_nor_stm25 fs_dev_nor_sst25 Implements particular serial NOR flash command set accesses NOR through SPI interface SPI BSP fs_dev_nor_bsp c Implements SPI communication for a particular MCU MPU Figure 15 3 NOR driver architecture serial NOR flash 163 NOR Flash Driver 15 4 1 HARDWARE Serial NOR devices typically connect to a host MCU MPU via an SPI or SPI like bus Eight pin devices with the functions listed in Table 15 5 or similar are common and are often employed with the HOLD and WP pins held high logic low or inactive as sh
356. updated upon write FS_VOL_CACHE_MODE_WR_THROUGH Write back cache Sectors cached upon read and write data on volume never updated upon write FS_VOL_CACHE_MODE_WR_BACK Table 5 3 Cache types File access presents a special case When a file is opened with a combination of FS FILE ACCESS MODE WR and FS FILE ACCESS MODE CACHED the update of the directory sector will be delayed until the file is closed pfile FSFile Open file txt FS_FILE ACCESS MODE WR FS_FILE ACCESS MODE CACHED amp err For files in read or write mode data from the file will be cached For files in write mode the update of the directory sector will be delayed until the file is closed 5 7 1 CHOOSING CACHE PARAMETERS The following is an example using the cache for the volume sdcard 0 The cache is used in write back mode and the cache parameters are 25 of cache size is used for management sector 15 is used for directories sectors and the remaining 60 is used for file sectors 80 Devices and Volumes FSVol_CacheAssign CPU_CHAR sdcard 0 lt volume name FS_VOL_CACHE API NULL lt pointer to vol cache API void amp CACHE BUF 0 lt pointer to the cache buf CPU_INT32U CACHE_BUF_LEN lt cache buf size in bytes CPU_INTO8U 25 lt see 1 CPU_INTO8U 15 lt see 2 FS_FLAGS FS_VOL CACHE MODE WR BACK lt cache mode FS_ERR amp err lt used for error
357. v_SD_Card_BSP_CmdWaitEnd in is targeted for the same host controller as the other listings in this chapter for more information see FSDev_SD_Card_BSP_CmdStart 478 LUC FS Porting Manual void FSDev_SD_Card_BSP_CmdWaitEnd PS Org unit_nbr FS_DEV_SD CARD CMD p cmd CPU_INT32U p_resp FS_ERR p err CPU_LINT16U interrupt_status CPU_INT16U error_status CPU_INT16U timeout timeout 0u Wait until cmd exec complete 1 interrupt_status REG INTERRUPT STATUS while DEE bit IS CLR interrupt status BIT_INTERRUPT_STATUS_ERROR BIT_INTERRUPT_STATUS_COMMAND COMPLETE DEF_YES timeout interrupt_status REG _INTERRUPT_STATUS if timeout TIMEOUT _RESP_ MAX p err FS DEV_SD CARD ERR WAIT TIMEOUT return Handle error SI 2 if DEF_BIT_IS SET interrupt_status BIT_INTERRUPT_STATUS ERROR DEF_YES error_status REG ERROR_STATUS if DEF_BIT_IS SET error_status REG ERROR STATUS COMMAND INDEX DEF_YES p err FS DEV_SD CARD ERR RESP CMD IX else if DEF_BIT IS SET error_status REG ERROR STATUS COMMAND END BIT DEF YES p err FS DEV_SD CARD ERR RESP END BIT else if DEF_BIT IS SET error_status REG ERROR STATUS COMMAND CRC DEF_YES p err FS DEV_SD CARD ERR RESP_CRC else if DEF_BIT IS SET error_status REG ERROR STATUS COMMAND TIMEOUT DEF YES p err FS DEV_SD CARD ERR RESP TIMEOUT else p err FS DEV_SD CARD ER
358. ver N A Acquire release SD MMC card bus lock ARGUMENTS unit_nbr Unit number of SD MMC card RETURNED VALUE None NOTES WARNINGS FSDev_SD Card BSP Lock will be called before the driver begins to access the SD MMC card bus The application should NOT use the same bus to access another device until the matching call to FSDev_SD_Card_BSP_Unlock has been made The clock frequency bus width and timeouts set by the FSDev_SD_Card_BSP_Set HHF functions are parameters of the card not the bus If multiple cards are located on the same bus those parameters must be saved in memory when set and restored when FSDev_SD Card BSP _Lock is called 471 LUC FS Porting Manual C 12 3 FSDev_SD_Card_BSP_CmdStart void FSDev_SD Card BSP CmdStart FS QTY unit_nbr FS DEM Sp CARD CMD p cmd void p data FS_ERR p err File Called from Code enabled by fs_dev_sd_card_bsp c SD MMC cardmode driver N A Start a command ARGUMENTS unit_nbr Unit number of SD MMC card p_cmd Pointer to command to transmit see Note 2 p data Pointer to buffer address for DMA transfer see Note 3 p err Pointer to variable that will receive the return error code from this function FS_DEV_SD_CARD_ERR_NONE FS_DEV_SD_CARD_ERR_NO CARD FS DEV_SD CARD ERR BUSY FS DEV_SD CARD ERR UNKNOWN RETURNED VALUE None No error No card present Controller is busy Unknown or other error 472 LUC FS Porting Man
359. ver is already available for uC FS A BSP is required so that the IDE driver will work on a particular system The port includes one code file FS DEV_IDE BSP C Several example ports are included in the uC FS distribution in files named according to the following rubric Micrium Software uC FS Examples BSP Dev IDE lt manufacturer gt lt board name gt Each BSP must implement the functions in Table C 2 Function Description FSDev_IDE BSP _Open Open initialize hardware FSDev_IDE BSP Close Close uninitialize hardware FSDev_IDE_BSP_Lock Acquire IDE bus lock FSDev_IDE_BSP_Unlock Release IDE bus lock FSDev_IDE_BSP_Reset Hardware reset IDE device FSDev_IDE_BSP_RegRd Read from IDE device register FSDev_IDE_BSP_RegWr Write to IDE device register FSDev_IDE_BSP_Cmdwr Write command to IDE device register FSDev_IDE_BSP_DataRd Read data from IDE device FSDev_IDE_BSP_DataWr Write data to IDE device FSDev_IDE BSP DMA Start Setup DMA for command Initialize channel FSDev_IDE_BSP_DMA End End DMA transfer and uninitialize channel FSDev_IDE_BSP_GetDrvNbr Get IDE drive number FSDev_IDE BSP_GetModesSupported Get supported transfer modes FSDev_IDE BSP_SetMode Set transfer modes FSDev_IDE_BSP_Dly400_ns Delay for 400 ns 408 LUC FS Porting Manual Table C 2 IDE CF BSP Functions Write command Setup DMA FSDev_IDE_BSP_CmdWr FSDev
360. ves through the ready as long as it supports the voltage range specified by the host and identification states if it is assigned an address by or is assigned an address before ending up in standby It can now get selected by the host for data transfers Figure 15 9 flowcharts this procedure 17 2 2 SD MMC CARDMODE COMMUNICATION DEBUGGING The SD MMC cardmode driver accesses the hardware through a port BSP A new BSP developed according to MCU MPU documentation or by example must be verified step by step until flawless operation is achieved 182 SD MMC Drivers 1 Initialization 1 bit Initialization must succeed for a SD MMC card in 1 bit mode 2 Initialization 4 or 8 bit Initialization must succeed for a SD MMC card in 4 or 8 bit mode 3 Read data Data must be read from card in both single and multiple block transactions 4 Write data Data must be written to the card in both single and multiple block transactions and subsequently verified by reading the modified sectors and comparing to the intended contents The 1 bit initialization process reveals that commands can be executed and responses are returned with the proper bits in the correct byte order Example responses for each step in the sequence are given in Figure 17 5 and Figure 17 6 The first command executed GO_IDLE STATE never receives a response from the card Only V2 SD cards respond to SEND_IF_ COND returning the check pattern sent to
361. was not open FS_ ERR VOL NOT MOUNTED Volume was not mounted FS_ERR_BUF_NONE AVAIL Buffer not available 286 FS ERR DEM RETURNED VALUE None NOTES WARNINGS None LC FS API Reference Manual Device access error 287 LC FS API Reference Manual A 6 FILE FUNCTIONS void FSFile BufAssign FS FILE p file void p buf FS FLAGS mode CPU_SIZE T size FS_ERR p err void FSFile BufFlush FS FILE p file FS_ERR p err void FSFile Close FS_FILE p file FS_ERR p err void FSFile ClrErr FS_FILE p file FS_ERR p err CPU_BOOLEAN FSFile_IsEOF FS_FILE p file FS_ERR p err CPU_BOOLEAN FSFile_IsErr FS_FILE p file FS_ERR p err CPU_BOOLEAN FSFile_ IsOpen CPU_CHAR name full FS_FLAGS p mode FS_ERR p err void FSFile LockAccept FS FILE p file FS_ERR p err void FSFile LockGet FS FILE p file FS_ERR p err 288 LC FS API Reference Manual void FSFile LockSet FS FILE p file FS_ERR p err FS FILE FSFile Open CPU_CHAR name_full FS_FLAGS mode FS_ERR p err FS FILE SIZE FSFile PosGet FS_FILE p file FS_ERR p err void FSFile_ PosSet FS_FILE p file FS FILE OFFSET offset FS FLAGS origin FS_ERR p err void FSFile Query FS_FILE p file FS ENTRY INFO ap info FS_ERR p err CPU_SIZE_T FSFile Rd FS_FILE p file void p dest CPU_SIZE T size FS_ERR p err void FSFile Truncat
362. which operate on file objects FS_FILEs are grouped under file access or simply file functions An application stores information in a file system by creating a file or appending new information to an existing file At a later time this information may be retrieved by reading the file Other functions support these capabilities for example the application can move to a specified location in the file or query the file system to get information about the file A separate set of file operations or entry functions manage the files and directories available on the system Using these functions the application can create delete and rename files and directories The entries within a directory can be traversed using the directory access or simply directory functions which operate on directory objects FS_DIRs The name and properties of the entries are returned within a struct fs_dirent structure The final group of functions is the working directory functions For information about using file and path names see section 4 3 uC FS File and Directory Names and Paths on page 62 Function POSIX Equivalent Function POSIX Equivalent fs_asctime_r asctime_r fe ftruncate ftruncate fs_chdir chdir fs_ftrylockfile ftrylockfile fs_clearerr clearerr fs_funlockfile funlockfile fs_closedir closedir fs fwrite fwrite fs _ctime r ctime_r fs_getcwd getcwd fs_fclose fclose f
363. y BlkCnt The number of blocks allocated to the file For a FAT file system this is the number of clusters occupied by the file data BlkSize The size of each block allocated in octets For a FAT file system this is the size of a cluster 518 LIC FS Types and Structures NOTES None 519 LIC FS Types and Structures D 8 FS_FAT_SYS CFG typedef struct fs Cat ses cfg FS_SEC_OTY ClusSize FS _FAT SEC NBR RsvdAreaSize CPU_INT16U RootDirEntryCnt CPU_INTO8U FAT Type CPU_INTO8U NbrFATs FS_FAT SYS CFG File Used for fs_fat_type h Second argument of FSVol_Fmt when opening a FAT volume optional A pointer to a FS FAT SYS CFG structure may be passed as the second argument of FSVol_Fmt It configures the properties of the FAT file system that will be created MEMBERS ClusSize The size of a cluster in sectors This should be 1 2 4 8 16 32 64 or 128 The size of a cluster in bytes must be less than or equal to 65536 so some of the upper values may be invalid for devices with large sector sizes RsvdAreaSize The size of the reserved area on the disk in sectors For FAT12 and FAT16 volumes the reserved should be 1 sector for FAT32 volumes 32 sectors RootDirEntryCnt The number of entries in the root directory This applies only to FAT12 and FAT16 volumes on which the root directory is a separate area of the file system and is a fixed size The root directory entry count caps the numb
364. y FS_SHELL_CFG CMD int EN Each FS FAT CFG CMD A EN separately enables disables a particular Ce 444 command FS FAT CFG CMD CAT EN FS FAT CFG CMD CD EN FS FAT CFG CMD CP EN FS FAT CFG CMD DF EN FS FAT CFG CMD DATE EN FS FAT CFG CMD LS EN FS FAT CFG CMD MKDIR EN FS FAT CFG CMD MKFS EN FS FAT CFG CMD MOUNT EN FS FAT CFG CMD MV EN FS FAT CFG CMD OD EN FS FAT CFG CMD PWD EN FS FAT CFG CMD RM EN Enable disable Ca Goar Enable disable s_cd Enable disable Ce op Enable disable Ce df Enable disable Ca date Enable disable s_1s Enable disable fs_mkdir Enable disable fs_mkfs Enable disable Ce mount Enable disable s_mv Enable disable s_od Enable disable Ca God Enable disable fe om 559 Shell Commands FS PaT CFG CMD RMDIR EN Enable disable s_xmdir FS FAT CFG CMD TOUCH EN Enable disable Ce touch FS FAT CFG CMD UMOUNT EN Enable disable Ce umount FS_FAT CFG CMD WC_EN Enable disable fs_we 560 Appendix Bibliography Labrosse Jean J 2009 pC OS I The Real Time Kernel Micrium Press 2009 ISBN 978 0 98223375 3 0 L gar Christian 2010 wC TCP IP The Embedded Protocol Stack Micrium Press 2010 ISBN 978 0 98223375 0 9 POSIX 2008 The Open Group Base Specifications Issue 7 IEEE Standard 1003 1 2008 Programming Lauguages C ISO IEC 9899 1999 The Motor Industry Software Reliability Association MISRA C 2004 Guidelines for the Use of the C Language in Critical System
365. y resources acquired in the Open function ARGUMENTS D dev Pointer to device to close RETURNED VALUE None NOTES WARNINGS 1 Tracking whether a device is open is not necessary because this should ONLY be called when a device is open 2 This will be called EVERY time the device is closed 3 The device driver Close function is called while the caller holds the device lock 400 LUC FS Porting Manual C 4 5 Rd static void FSDev_ Rd FS_DEV p dev void p dest FS_SEC_NBR start FS_SEC QTY cnt FS_ERR p err File Called from Code enabled by fs_dev_ Hf c FSDev_RdLocked N A The device driver Rd function should read from a device and store data in a buffer If an error is returned the file system suite assumes that no data is read if not all data can be read an error MUST be returned ARGUMENTS D dev Pointer to device to read from p dest Pointer to destination buffer start Start sector of read cnt Number of sectors to read p err Pointer to variable that will receive the return error code from this function FS_ERR_NONE Sector s read FS_ERR_DEV_INVALID UNIT_NBR Device unit number is invalid FS_ERR_DEV_IO Device I O error PG ERR DEV MO ODEN Device is not open PG ERR DEV MO PRESENT Device is not present FS_ERR_DEV_ TIMEOUT Device timeout RETURNED VALUE None 401 LUC FS Porting Manual NOTES WARNINGS 1 Tracking whether a device is open is not necessary becau
366. y data Pointer to NAND phy data p err Pointer to variable that will receive the return error code from this function RETURNED VALUE None NOTES WARNINGS Several members of p phy data may need to be used assigned 1 UnitNbr is the unit number of the NAND device 2 BlkCnt and BlkSize MUST be assigned the block count and block size of the device respectively A block is the device erase unit e g the smallest area of the device that can be erased at any time 3 PageSize MUST be assigned the page size of the device A page is the device program unit i e the smallest area of the device that can be programmed at any time 4 BlkSize MUST be a multiple of PageSize 5 PageSize MUST be a multiple of SecSize 6 SpareSize MUST be assigned the size in bytes of the spare arear per sector 429 LUC FS Porting Manual 7 MaxClkFreq specifies the maximum SPI clock frequency 8 BusWidth specify the bus configuration 430 LUC FS Porting Manual C 6 2 Close void Close FS _DEV_NAND PHY DATA p phy data File Called from Code enabled by NAND physical layer driver FSDev_NAND_Close N A Close uninitialize a NAND device instance ARGUMENTS p phy data Pointer to NAND phy data RETURNED VALUE None NOTES WARNINGS None 431 LUC FS Porting Manual C 6 3 RdPage void RdPage FS_DEV_NAND PHY DATA p phy data void p dest void p dest_spare FS_SEC_NBR sec_nbr_ phy FS_ERR p

µC/FS User`s Manual v4.04

Contents

Download Pdf Manuals

Related Search

Related Contents

&micro;C/FS User`s Manual v4.04

Contents

Download Pdf Manuals

Related Search

Related Contents

µC/FS User`s Manual v4.04