 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The FileX Port on Media Framework module supports the Azure RTOS FileX system, a complete FAT and exFAT format media and a file management system for deeply embedded applications. FileX is highly optimized for both size and performance.
Single Partition (Uses total available memory size):
Multi Partition:
The FileX On Block Media Framework provides access to all the FileX APIs used to create the file system, access files and directories and manage the file system. The full set of FileX API functions, their parameters, operation and example use can be found in the FileX User's Manual. Some examples are shown below to provide some background for better understanding the rest of the descriptions of the FileX on Block media framework module.
FileX On Block Media Framework Module API Summary (Selected Examples Only)
| Function Name | Example API Call and Description |
|---|---|
| fx_directory_attributes_read | fx_directory_attributes_read(&my_media, "mydir", &attributes); Reads the directory's attributes from the specified media. |
| fx_file_open | fx_file_open(&my_media, &my_file, "myfile.txt", FX_OPEN_FOR_READ);Open "myfile.txt" file for read. |
| fx_file_create | fx_file_create(&my_media, "myfile.txt"); Create file with name "myfile.txt" |
| fx_media_read | fx_media_read(&my_media, 22, my_buffer); Read the logic sector (in this example from sector 22) from media specified by &my_media, and places it into the buffer my_buffer. |
For single partition:
For multiple partitions:
For Single Partition (Uses total available memory size):
The media must be formatted to either a FAT12, FAT16, FAT32 or exFAT file system before it can be opened, And media Format can be done prior to inserting the media (ie in a windows OS environment) or at project run time (using the "Format media" option in fileX properties in configurator).
For multi-partition:
For Single partition:
For Multiple partition:
Refer to the most recent SSP Release Notes for any additional operational limitations for this module.
This section describes how to include the FileX on Block Media Framework module in an application using the SSP configurator.
Following steps should be followed by the user for Single Partition (Used total available memory size): partitions:
To add the FileX on Block Media Framework module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
FileX On Block Media Framework Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_fx_media0FileXonBlock Media | Threads | New Stack> X-Ware > FileX on Block Media |
When the FileX on Block Media Framework module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
The Add Block Media Driver block must be filled in prior to generating the Synergy project code. There are multiple selections possible depending on the physical media targeted. Currently available media include RAM, LX NOR, QSPI, and SDMMC. Options may be different depending on what your target board and associated board support package (BSP) supports.
To enable the exFAT file system support in SSP, the user has to add the fileX source files to the project, and enable the “FileX Source" -> “exFAT support" option in the fileX source configurator properties, and re-build the FileX project.
The following steps should be followed by the user for multiple partitions on the same/different media type:
g_fx_media0 is created and it selects lx_nor media type.g_fx_media1 created. For example, g_fx_media0 and g_fx_media1 represent the two partitions.From the second instance and onward, selecting SF_EL_FX module instance gives two options New and Use.
Use: If the user selects Use, the partition will be made on the media previously selected by FileX media instance (g_sf_el_fx0 selected lx_nor). For example, g_fx_media0 and g_fx_media1 represent partitions on the same media type lx_nor.
New: If the user selects New, a new instance of SF_EL_FX is created. The user will have the choice to select the different media type. If the new instance of SF_EL_FX is chosen, a different media has to be selected for making the partition. For example: Select a third FileX media instance. Here g_fx_media2 is created. Here g_fx_media0 and g_fx_media1 have partitions on same media type with same instance of SF_EL_FX (g_sf_el_fx0). For g_fx_media2, a different instance of SF_EL_FX is selected (g_sf_el_fx1). g_fx_media2 selects a new instance of SF_EL_FX module (g_sf_el_fx1) which selects SDMMC block media framework. Here, g_fx_media0 and g_fx_media1 have partitions on media type qspi memory. g_fx_media2represents the partition on SDMMC framework.)
g_fx_media3, the user has the choice to select Use (for SF_EL_FX module) or New for a different media type.The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the FileX On Block Media Framework Module
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_fx_media0 | Module name. |
| Format media during initialization | Enable, Disable Default: Disabled | Select to automatically format the media during initialization. |
| File System is on block media | True, False Default: True | This setting will use code that reads sector size and count from the media device before formatting, if true. If set to false, the format function will use the sector size and count from configuration below. |
| Formatting Options | ||
| Volume Name | Volume 1 | This is the volume name to use when formatting the media device. It should be no longer than 11 characters. |
| Number of FATs | 1 | Number of File Allocation Tables. |
| Directory Entries | Default: 256 | Number of directory entries in the root directory. |
| Hidden Sectors | 0 | Number of hidden sectors. |
| Total Sectors | 3751936 | Total number of sectors in the media.
|
| Bytes per Sector | 512 | Sector size to format, when using the format function. "File System is on SDMMC" must be disabled for this value to be used.
|
| Sectors per Cluster | 1 | Sectors per cluster. This value is not used if "File System is on SDMMC" disabled. |
| Volume Serial Number | 12345 | Serial number to be used for this volume. Only used if Format media during initialization is enabled. Used in exFAT media format only. |
| Boundary unit | 128 | Physical data area alignment size, in number of sectors. Only used if Format media during initialization is enabled. Used in exFAT media format only. |
| Working media memory size | 512 | This is the number of bytes FileX uses to read and write to the media. It should be at least the size of one sector.
|
| Name of generated initialization function | fx_media_init0 | Name of the initialization function that is generated by SSP. |
| Auto Initialization | Enable, Disable Default: Enable | Select to enable or disable auto initialization. |
For Multi partitions:
sf_el_fx user configuration settings are require for multi-partition operation.
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_sf_el_fx0 | Module name. |
| Partition info callback | A callback can be NULL or the name of the user-defined function. | If partitions exist and the system got reset, user callback specifies the partition offset/base address. This callback is called while opening the partition. |
| Total partitions | >1 | The number of partitions users wanted to make on the media. |
Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the Block Media Framework on sf_block_media_sdmmc
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enable or disable the parameter checking. |
| Name | g_sf_block_media_sdmmc0 | Module name. |
| Block size of media in bytes | 512 | Specify the size of a block in bytes. |
Configuration Settings for the SDMMC HAL Module on r_sdmmc
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enable or disable parameter error checking. |
| Name | g_sdmmc0 | The name to be used for SDMMC module control block instance. This name is also used as the prefix of the other variable instances. |
| Channel | 0 | Select the channel. |
| Media Type | Embedded, Card Default: Embedded | Media is a card or an embedded device. This allows to firmware to know whether to look for card insertion/removal and write protect pins. |
| Bus Width | 1 Bit, 4 Bits, 8 Bits Default: 4 Bits | Data bus with as defined by hardware interface. (8 Bits for eMMC only) |
| Block Size | 512 | Block size selection. |
| Card Detection | Not Used, CD Pin Default: CD Pin | Card detection selection. |
| Callback | NULL | (Not required if using Filex) Set to name of user callback function. Provides event that caused interrupt: SDMMC_EVENT_CARD_REMOVED, SDMMC_EVENT_CARD_INSERTED, SDMMC_EVENT_ACCESS, SDMMC_EVENT_SDIO, SDMMC_EVENT_TRANSFER_COMPLETE, SDMMC_EVENT_TRANSFER_ERROR |
| Access Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12 | Access interrupt priority selection. |
| Card Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Card interrupt priority selection. |
| DTC Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | DTC interrupt priority selection. |
The SDHI uses the PCLKA for its clock source. There is no need to configure the clock specifically for the SDMMC peripheral unless you need to optimize the data rate. The SDMMC driver selects the appropriate built-in divider based on the PCLKA frequency and the maximum clock rate allowed by the SD, SDIO or eMMC device obtained at media device initialization.
Use the e2 studio pin configurator to configure the I/O pins for the target media peripheral. The following description applies to the SDHI peripheral used for SDMMC media. Other media will require similar pin settings, and these are easily determined using their associated pin selection sequence in the Synergy Configurator. Consult the appropriate HAL driver section in the SSP User's Manual for additional details.
For SDMMC media, the drive capacity for each pin should be set to "Medium" or "High" for most boards and high-speed memory and SDIO devices. The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table provides an example selection for the module pins.
Pin Selection Sequence for the SDHI Peripheral
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| SDHI | Pins | Select Peripherals> Storage:SHDI> SDHI0 |
Pin Configuration Settings for the SDHI Peripheral
| Pin Configuration Property | Settings | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, SD_MMC 1 bit SD_MMC 4 bit MMC 8 bit Default: Custom | Select mode as per application. |
| CLK | None, P413 Default: P413 | Clock pin. |
| CMD | None, P412 Default: P412 | Command pin. |
| DAT0-7 | None, PXXX Default: PXXX | Data pin. |
| CD | None, P903 Default: P903 | Card detection pin. |
| WP | None, P414 Default: P414 | Card write protection pin. |
The steps in using the FileX on Block Media Framework module in a typical application are:
fx_system_initialize (FileX on Block Media calls it automatically if Auto Initialization property is set to Enabled in FileX Common on fx)fx_media_open (FileX on Block Media opens the media automatically if its Auto Initialization property is set to Enabled)fx_file_create, fx_file_delete, fx_directory_create, fx_directory_delete)fx_file_read or fx_file_write)fx_media_read or fx_media_write)fx_media_closefx_media_open call, all FileX file and directory related APIs can be used. Refer to the FileX User Guide for documentation on all available functions.These common steps are illustrated in a typical operational flow in the following figure:
