PSoC® Creator™ Component Data Sheet File System Library (emFile) 1.10 Features Up to four Secure Digital (SD) cards in SPI mode FAT12/16 or FAT32 format Optional integration with an Operating System (OS) Optional Long File Name (LFN) handling General Description The emFile component provides an interface to SD cards formatted with a FAT file system. The SD card specification includes multiple hardware interface options for communication with an SD card. This component uses the SPI interface method for communication. Up to four independent SPI interfaces can be used for communication with one SD card each. Both FAT12/16 and FAT32 file system formats are supported. This component provides the physical interface to the SD card and works with the emFile library licensed from SEGGER Microcontroller to provide a library of functions to manipulate a FAT file system. When to Use emFile Use the emFile component to access SD cards formatted using the FAT 12/16 or FAT32 file system formats. Getting Started Installing the emFile Library The emFile file system implementation consists of two parts. The first part is the emFile component which is shipped with PSoC Creator. The second part is the emFile file system library licensed from SEGGER Microcontroller. The library is delivered as a zip file that can be downloaded from the Cypress website emFile component page. To install the emFile library: 1. Open PSoC Creator and go to the Component Catalog window. Search for the emFile component. It is located under the Cypress tab at Communications > File System > emFile SPI Mode. Cypress Semiconductor Corporation • 198 Champion Court • San Jose, CA 95134-1709 • 408-943-2600 Document Number: 001-79211 Rev. *A Revised July 28, 2015 emFile PSoC® Creator™ Component Data Sheet 2. Right-click on the emFile component. The menu shown in Figure 1 will appear. Figure 1. emFile Open Component Web Page 3. Click on Open Component Web Page. It will direct you to the component landing page where the zip file with latest file system libraries is located. 4. Download the zip file and extract it to a folder of your choice, preserving the directory structure of the zip file. Make sure the files are not read-only after extracting. emFile Library Directory Organization The directory structure of the unzipped emFile library will be similar to that shown in Figure 2. Figure 2. emFile Directory Organization The Code directory contains the portion of the library that is provided in source code format. This directory has two subdirectories: Include and Source. The Include directory provides header files for the library. The Source directory provides the executable portion of the library that is delivered in source format. The Include section is divided into header files that are always applicable at the top level of the directory and header files in subdirectories that are used depending on the options chosen for the particular LinkLibrary. The names of the subdirectories are specified as emf<options>. All of the options are described in Table 1. Page 2 of 16 Document Number: 001-79211 Rev. *A PSoC® Creator™ Component Data Sheet emFile Table 1. Options Option Description 16 FAT 12/16 format 32 FAT 32 format os Operating System support nos No Operating System support lfn Long File Name support nlfn No Long File Name support Figure 3 shows files in the Code directory. This figure shows the directory organization of files for PSoC 3. PSoC 5 has a similar file organization. Document Number: 001-79211 Rev. *A Page 3 of 16 emFile PSoC® Creator™ Component Data Sheet Figure 3. emFile “Code” Directory File Listing The Documentation section contains the User Guide for the SEGGER Microcontroller emFile file system library. The LinkLibrary section is divided into PSoC 3 and PSoC 5 directories. Each directory contains a subdirectory for each of the supported tool chains. Within those directories are object libraries that provide the implementation of the file system for the specific options chosen. The library is Page 4 of 16 Document Number: 001-79211 Rev. *A PSoC® Creator™ Component Data Sheet emFile added to a project using the Build Settings options described later in this datasheet. The expanded PSoC 3/Keil PK51 section contains the object libraries shown in Figure 4. Figure 4. LinkLibrary Structure The naming convention for the LinkLibrary is: <prefix>emf<options>.<extension>. The options are the same options used for the include file directory names. The prefix and extension are specific to the tool chain used. See Table 2. Table 2. Naming Convention Toolchain Prefix Keil PK51 GCC Extension lib lib a ARM_MDK lib ARM_RVDS Lib The files in the unzipped emFile directory are changelog.pdf, emFile_License_Agreement.txt, and LFN-notice.txt. The changelog.pdf file contains the history on changes that were made in the library. The emFile_License_Agreement.txt file is an End User License Agreement that contains the terms of use of the emFile library. The LFN-notice.txt file is a notice about theuse of long file names. Document Number: 001-79211 Rev. *A Page 5 of 16 emFile PSoC® Creator™ Component Data Sheet Creating an emFile Project for a PSoC 3 Application To use the emFile library in a PSoC 3 project: 1. Decide which library you need. This decision is based on whether you need FAT12/16 or FAT32, whether your application uses an OS, and whether you need long file name support. This example uses emf32nosnlfn.lib (FAT32, no OS, and no long file name support). 2. Select the necessary include file directory. Go to Project > BuildSettings > Compiler > General. Click the “…” button in the Additional Include Directories property field. The Additional Include Directories dialog will display. Click the New button and select an include directory for PSoC 3 and an include directory for the specific options you want. When complete, the dialog should appear as shown in Figure 5. Figure 5. Adding include Directories 3. Select the Link library file you need. Go to Project > BuildSettings > Linker > General. Click the “…” button in the Additional Link Files property field. The Additional Link Files dialog will display. Click the New button and select the library file based on the specific options you want. When complete, the dialog should appear as shown in Figure 6. Page 6 of 16 Document Number: 001-79211 Rev. *A PSoC® Creator™ Component Data Sheet emFile Figure 6. Adding a Link Library 4. Add the source file FS_ConfigIO.c into the project. If you are using an OS, also add FS_X_OS.c. These files can be added directly into your project from the Code/Source/PSoC3 directory or copied first to your project directory and added from there. The files will usually be edited, so you need to decide whether to change the original files or a copy that is specific to the project. The files are added to the project using Project > Existing Item. The dialog shown in Figure 7 will open to allow you to select the files. Document Number: 001-79211 Rev. *A Page 7 of 16 emFile PSoC® Creator™ Component Data Sheet Figure 7. Adding Source Files The emFile library is now included in your project. Creating an emFile Project for a PSoC 5 Application The steps to create an emFile project for PSoC 5 are the same as for PSoC 3 except when using the GCC toolchain. When using the GCC toolchain, instead of adding the link library as a file, you must specify the directory where the library file is located. 1. Go to BuildSettings > Linker > General > Additional Library Directories. Click the “…” button in the Additional Library Directories property field. The Additional Library Directories dialog will display. 2. Click the New button and select the library directory for the GCC library. When complete, the dialog should appear as shown in Figure 8. Page 8 of 16 Document Number: 001-79211 Rev. *A PSoC® Creator™ Component Data Sheet emFile Figure 8. Adding Library Directory 3. Specify the library in the library directory. a. Go to BuildSettings > Linker > General > Additional Libraries. b. Type in the library name with the “lib” prefix and “.a” suffix excluded from the name. Assuming that you are using the libemf32nosnlfn.a library file, the library name should be emf32nosnlfn. Document Number: 001-79211 Rev. *A Page 9 of 16 emFile PSoC® Creator™ Component Data Sheet Input/Output Connections This section describes the various input and output connections for the emFile component. An asterisk (*) in the list of I/Os means that the I/O may be excluded from the component under the conditions listed in the description of that I/O. There are no visible connections for the component on the symbol. All connections shown are for pin connections that are included internal to the component. These pins will all appear in the Design-Wide Resources Pin Editor. They must be assigned to the appropriate physical pins using the Pin Editor. For each of the connections there are four pins named with indexes 0 to 3. These represent the four independent SD cards that the component can support. One to four of these pins will be present in the design, depending on the number of SD cards selected. The following is a description of these pins. SPI0_WP – SPI3_WP* Optional input pins based on SD Card [0-3] Write Protection options, which configure the write protect for SD cards [0-3]. These pins are present if these options are checked. The default state for these pins is not present, which indicates that the SD cards are not write protected. mosi0 – mosi3 Master Out Slave In pin of the SPI Master. This pin should be connected to the DI/CMD pin of the SD card. miso0 – miso3 Master In slave Out pin of the SPI Master. This pin should be connected to the DO/DAT0 pin of the SD card. sclk0 – sclk3 Serial Clock pin from the SPI Master. This pin should be connected to the clock pin of the SD card. SPI0_CS – SPI3_CS Card Select output pin. This pin should be connected to the nCS pin of the SD card. Page 10 of 16 Document Number: 001-79211 Rev. *A PSoC® Creator™ Component Data Sheet emFile Component Parameters Drag an emFile onto your design and double-click it to open the Configure dialog. The emFile provides the following parameters. Max SPI frequency Defines the maximum frequency at which the SPI Master components will clock an SD card. The value is specified in kHz. Possible values are in the range 400 to 25,000 kHz, the default setting is 4000. The range of frequencies is based on the specification for SD cards. Note that there are limitations for maximum frequency for the SPI Master (v2.20) component that is used in emFile. Refer to the SPI Master v2.20 datasheet "Timing Characteristics" for detailed information about the maximum frequency that this component can support. Number of SD cards Defines the number of SD cards in the emFile system. The value can be set between 1 and 4. The default setting is 1. Document Number: 001-79211 Rev. *A Page 11 of 16 PSoC® Creator™ Component Data Sheet emFile SD card n write protection Defines the write protect enable for each of n SD cards. It is disabled by default. Application Programming Interface Application Programming Interface (API) routines allow you to configure the component using software. The following table lists and describes the interface to each function. The subsequent sections cover each function in more detail. By default, PSoC Creator assigns the instance name “emFile_1” to the first instance of a component in a given design. You can rename it to any unique value that follows the syntactic rules for identifiers. The instance name becomes the prefix of every global function name, variable, and constant symbol. For readability, the instance name used in the following table is “emFile.” The emFile library routines automatically initialize and enable the emFile component. The only APIs provided for the emFile component are to support transitioning between power modes. This section does not include a description of file system APIs of the emFile library because these APIs are described in the emFile User Guide, Chapter 4. You must include the FS.h header file in your main.c file to use file system APIs. Note To use long file names (LFN) support on PSoC 5 devices, you must call FS_FAT_SupportLFN(). For PSoC 3 devices, this feature is enabled by default. Function Description emFile_Sleep() Prepares emFile to enter sleep mode. emFile_Wakeup() Restores emFile after coming out of sleep mode. emFile_SaveConfig() Saves the SPI Master configuration used by the HW driver. emFile_RestoreConfig() Restores the SPI Master configuration used by the HW Driver. void emFile_Sleep(void) Description: Prepares emFile to go to sleep. Parameters: None Return Value: None Side Effects: Page 12 of 16 None Document Number: 001-79211 Rev. *A PSoC® Creator™ Component Data Sheet emFile void emFile_Wakeup(void) Description: Restores emFile after coming out of sleep mode. Parameters: None Return Value: None Side Effects: Calling the emFile_Wakeup() function without first calling the emFile_Sleep() or emFile_SaveConfig() function may produce unexpected behavior. void emFile_SaveConfig(void) Description: Saves the SPI Master configuration used by the HW driver. This function is called by emFile_Sleep(). Parameters: None Return Value: None Side Effects: None void emFile_RestoreConfig(void) Description: Restores the SPI Master configuration used by the HW Driver. This function is called by emFile_Wakeup(). Parameters: None Return Value: None Side Effects: Calling this function without first calling the emFile_Sleep() or emFile_SaveConfig() function may produce unexpected behavior. Sample Firmware Source Code PSoC Creator provides many example projects that include schematics and example code in the Find Example Project dialog. For component-specific examples, open the dialog from the Component Catalog or an instance of the component in a schematic. For general examples, open the dialog from the Start Page or File menu. As needed, use the Filter Options in the dialog to narrow the list of projects available to select. Refer to the “Find Example Project” topic in the PSoC Creator Help for more information. Document Number: 001-79211 Rev. *A Page 13 of 16 PSoC® Creator™ Component Data Sheet emFile Functional Description File System Library Structure The emFile file system implementation consists of two parts: the emFile component and the emFile file system library licensed from SEGGER Microcontroller. A file system application will use the APIs provided in the emFile library. That library will use the emFile component to provide the physical interface to the SD card using a SPI interface. The structure of the emFile file system is shown in Figure 9. Figure 9. emFile Structure Application emFile Library emFile Component SD Card Placement The emFile component is placed throughout the UDB array and all placement information is provided to the API through the cyfitter.h file. Page 14 of 16 Document Number: 001-79211 Rev. *A PSoC® Creator™ Component Data Sheet emFile Performance and Resource Usage The performance of emFile depends on a set of parameters (CPU, compiler, optimization, size of payload data) and it is limited by the maximum speed of the SPI Master component. The following table contains read/write speed values depending on a variety of factors that affect emFile component performance. Performance (KBps) CPU Speed Device 1 Byte 256 Bytes 1 KB 8 KB SPI Clock Mode Write Read Write Read Write Read Write Read PSoC 3 24 MHz 12 MHz Release 0.02 0.09 4.46 20.00 15.38 47.17 22.04 47.34 PSoC 3 48 MHz 12 MHz Release 0.03 0.18 8.15 38.20 28.33 87.72 41.67 93.02 PSoC 3 24 MHz 8 MHz Release 0.02 0.09 4.46 19.69 15.38 47.17 22.04 47.33 PSoC 3 48 MHz 8 MHz Release 0.03 0.17 7.83 36.05 27.10 84.03 39.70 87.91 PSoC 3 24 MHz 4 MHz Release 0.02 0.10 4.27 19.40 14.70 44.64 16.70 44.94 PSoC 3 48 MHz 4 MHz Release 0.03 0.15 6.98 32.40 23.98 74.07 35.08 77.67 PSoC 5 24 MHz 12 MHz Release 0.06 0.43 14.10 111 37.73 213 90.30 212 PSoC 5 48 MHz 12 MHz Release 0.07 0.62 18.28 160 62.50 294 117 282 PSoC 5 24 MHz 8 MHz Release 0.05 0.43 13.80 109 47.50 208 88.10 207 PSoC 5 48 MHz 8 MHz Release 0.06 0.53 16.20 135 56.02 253 105 252 PSoC 5 24 MHz 4 MHz Release 0.04 0.30 10.07 76.41 34.72 147 63.40 148 PSoC 5 48 MHz 4 MHz Release 0.05 0.40 12.60 100 43.50 191 79.84 190 Memory Usage emFile component memory usage varies depending on the application. The documentation from SEGGER gives a detailed description of how to calculate the memory resources. The following table contains memory usage values for some commonly used features of the file system. All values are in bytes. Keil_PK51 Release emFile Module GCC-4.4.1 Debug Release Debug Flash SRAM Flash SRAM Flash SRAM Flash SRAM File system core (SPI driver) 28035 4762 28799 4849 10440 4272 12432 4272 Read file 2668 6 2672 3 824 0 832 0 Document Number: 001-79211 Rev. *A Page 15 of 16 PSoC® Creator™ Component Data Sheet emFile Keil_PK51 Release emFile Module GCC-4.4.1 Debug Release Debug Flash SRAM Flash SRAM Flash SRAM Flash SRAM Write file 1927 0 1932 0 808 0 816 0 Open directory 2714 47 2733 47 408 0 416 0 Create directory 898 0 898 0 464 0 480 0 Remove file 75 0 75 0 48 0 48 0 - - - - 2232 0 2232 0 Low-level format 769 0 769 0 240 0 232 0 Format SD card 6063 0 6063 0 2296 0 2304 0 Long file name support* * Long file name support code is included automatically as part of the file system core for PSoC 3. Component Changes Version Description of Changes 1.10.a Minor datasheet edit. 1.10 Updated Performance table values. Updated emFile Directory Organization diagram Reason for Changes / Impact The emFile File system library (.zip) was updated so this was reflected in the datasheet Updated emFile with the latest version of the SPI Master component 1.0 First release © Cypress Semiconductor Corporation, 2012-2015. The information contained herein is subject to change without notice. Cypress Semiconductor Corporation assumes no responsibility for the use of any circuitry other than circuitry embodied in a Cypress product. Nor does it convey or imply any license under patent or other rights. Cypress products are not warranted nor intended to be used for medical, life support, life saving, critical control or safety applications, unless pursuant to an express written agreement with Cypress. Furthermore, Cypress does not authorize its products for use as critical components in life-support systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress products in life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. PSoC® and CapSense® are registered trademarks, and SmartSense™, PSoC Creator™, and Programmable System-on-Chip™ are trademarks of Cypress Semiconductor Corp. All other trademarks or registered trademarks referenced herein are property of the respective corporations. Any Source Code (software and/or firmware) is owned by Cypress Semiconductor Corporation (Cypress) and is protected by and subject to worldwide patent protection (United States and foreign), United States copyright laws and international treaty provisions. Cypress hereby grants to licensee a personal, non-exclusive, non-transferable license to copy, use, modify, create derivative works of, and compile the Cypress Source Code and derivative works for the sole purpose of creating custom software and or firmware in support of licensee product to be used only in conjunction with a Cypress integrated circuit as specified in the applicable agreement. Any reproduction, modification, translation, compilation, or representation of this Source Code except as specified above is prohibited without the express written permission of Cypress. Disclaimer: CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress reserves the right to make changes without further notice to the materials described herein. Cypress does not assume any liability arising out of the application or use of any product or circuit described herein. Cypress does not authorize its products for use as critical components in lifesupport systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress’ product in a life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. Use may be limited by and subject to the applicable Cypress software license agreement. Page 16 of 16 Document Number: 001-79211 Rev. *A