SEGGER emFile for ModusToolbox User Guide

Overview

emFile is a fail-safe filesystem designed for embedded systems by SEGGER Microcontroller GmbH that can be used with different types of storage devices. It is a high-performance library optimized for high speed, versatility, and a minimal memory footprint of both RAM and ROM. Cypress has licensed emFile from SEGGER and offers it for free to its customers. This middleware library provides emFile in the form of pre-built libraries and supports FAT 12/16/32 file systems.

Quick Start

The following step-by-step instructions show how to perform simple filesystem operations on an SD card for the CY8CPROTO-062-4343W kit. Adapt the instructions for your target kit as required.

Open the Project Creator tool in ModusToolbox™ by clicking the New Application menu in Quick Panel
Choose CY8CPROTO-062-4343W under PSoC 6 BSPs and click Next
Select Empty PSoC6 App under Template Applications and click Create. Close the window after the application has been created.
Open the Library Manager tool from the Quick Panel.
Select emFile under PSoC 6 Middleware and retarget-io under Board Utils and click Update. Close the window after the libraries have been added.
Copy the following files from the emFile directory into the application directory:
- Sample/FS/Application/FS_Start.c - Implements a starter application that performs simple read and write operations
- Either of the following files depending on the storage device you want to use
  - Config/FS_ConfigNOR_BM_SPIFI.c - For working with the NOR flash. Most of the PSoC 6 MCU development kits have an on-board NOR flash.
  - Config/FS_ConfigMMC_CM_HS.c - For working with an SD card
Add COMPONENTS=EMFILE_FAT32 and DEFINES=CY_RETARGET_IO_CONVERT_LF_TO_CRLF in the Makefile.
Add #include "cy_retarget_io.h" to main.c.
Add void MainTask(void); above the main() function.

Add the following code in main() after the line __enable_irq();

/* Initialize retarget-io to use the debug UART port */
cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, CY_RETARGET_IO_BAUDRATE);

/* Call the function that performs emFile operations */
MainTask();

Open a serial terminal.
Build the application and program the kit.

Output on the serial terminal appears as follows:

Configuration Considerations

Picking an emFile Library Variant

This middleware provides emFile as pre-built libraries in 12 variants. These libraries are available under the FS/<lib_path> directory where <lib_path> is constructed as follows: COMPONENT_<config>/COMPONENT_<cpu>/COMPONENT_<vfp_select>/TOOLCHAIN_<toolchain>/. The table below lists the options for each field and the related make variable. You can pick a variant by correctly configuring the make variables.

Field	Options	Make Variable
config	`EMFILE_FAT32`, `EMFILE_FAT16`	`COMPONENTS`
cpu	`CM4`	`CORE`
vfp_select	`HARDFP`, `SOFTFP`	`VFP_SELECT`
toolchain	`GCC_ARM`, `IAR`, `ARM`	`TOOLCHAIN`

The header file FS_ConfCommon.h under the FS directory contains the common configuration used in generating the libraries. Similarly, FS_Conf.h under each COMPONENT_<config> directory contains the configuration specific to the set of library variants.

Using emFile in an RTOS Environment

The OS layer and the HW layer implementations use the abstraction-rtos library for implementing RTOS functionalities. Therefore, emFile can be used with the RTOSes supported by the abstraction-rtos library. Do the following to configure your application for using emFile with FreeRTOS.

Open Library Manager and add FreeRTOS to your project.
Copy FreeRTOSConfig.h from <freertos_dir>/Source/portable/COMPONENT_CM4 into the application directory and configure it.
Add COMPONENTS=FREERTOS RTOS_AWARE in the Makefile.

Configuring the HW Layer for the Block Map NOR Driver (NOR_BM)

Configure the HW layer for the Block Map NOR driver in FS_X_AddDevices() before adding the driver using FS_AddDevice(). See the FS_ConfigNOR_BM_SPIFI.c file that shows how to configure the HW layer.

Create an instance (for example: QspiConfig) of the configuration structure FS_NOR_HW_SPIFI_Config_t and assign the values. See the FS_NOR_HW_SPIFI.h file for the structure documentation.
Call FS_NOR_HW_SPIFI_Configure() to configure the HW layer. For example: FS_NOR_HW_SPIFI_Configure(&QspiConfig);.

Note: The NOR HW layer supports up to four memories using four slave select pins but all the memories need to be connected to the same data lines.
Add the driver using FS_AddDevice() and proceed with the rest of the initialization.

Configuring the HW Layer for the Card Mode SD/MMC Driver (MMC_CM)

Configure the HW layer for the SD/MMC driver in FS_X_AddDevices() before adding the driver using FS_AddDevice(). See the FS_ConfigMMC_CM_HS.c file that shows how to configure the HW layer.

Create an instance (for example: SDConfig) of the configuration structure FS_MMC_HW_CM_SDHostConfig_t and assign the values. See the FS_MMC_HW_CM.h file for the structure documentation.

Note:
- In the configuration structure, you must set the isEmmc member of cyhal_sdhc_config_t to true if you are using an eMMC card instead of an SD card.
Call FS_MMC_HW_CM_Configure() to configure the HW layer. For example: FS_MMC_HW_CM_Configure(0, &SDConfig);.

The first argument is the HW/driver instance number. Up to 2 instances are supported.
Add the driver using FS_AddDevice() and proceed with the rest of the initialization.

emFile Package Structure

Config: Contains the sample configuration files for the various drivers and *FS_ConfigRAMDisk.c* that allows using RAM as a storage device.

Doc: Contains this user guide, SEGGER-provided emFile user guide and release notes.

Driver: Contains the HW layer implementations for the various drivers.

FS: Contains the header files and the pre-built emFile libraries. See Picking an emFile Library Variant for details.

OS: Contains the OS layer implementation.

Sample/FS/Application: Contains the readily-usable sample emFile applications provided by SEGGER. You can copy any of the files into your application directory and call MainTask() in the main() function to run the application.

Note: The folders Config and Sample have been added to the .cyignore file and hence will be excluded from the build.

emfile/Doc/User_Guide.md