 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Block Media Framework module can implement the SD/MMC bus protocol for reading from, writing to and the control of SD cards and eMMC embedded devices through the SDHI (SD Host Interface) peripheral and the SD/MMC media driver. The driver has all the functionality needed to interface with a file system through a block media interface.
The Block Media Framework defines APIs for opening, reading from, writing to, controlling and closing the SDMMC. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
Block Media SDMMC Framework Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| open | g_sf_block_media_sdmmc_api->open(g_sf_block_media_sdmmc.p_ctrl, g_sf_block_media_sdmmc.p_cfg);Open device for read/write and control. |
| read | g_sf_block_media_sdmmc_api->read(g_sf_block_media_sdmmc.p_ctrl, &destination, startsector, sectorcount);Read data from SD/MMC. |
| write | g_sf_block_media_sdmmc_api->write(g_sf_block_media_sdmmc.p_ctrl, &source, startsector, sectorcount);Write data to SDMMC channel. |
| ioctl | g_sf_block_media_sdmmc_api->ioctl(g_sf_block_media_sdmmc.p_ctrl, command, &data);Send control commands to the SD/MMC port and receive the status of the SD/MMC port. |
| close | g_sf_block_media_sdmmc_api->close(g_sf_block_media_sdmmc.p_ctrl);Close open device port. |
| versionGet | g_sf_block_media_sdmmc_api->versionGet(&version);Get version of Block Media SD/MMC driver. |
Status Return Values
| Name | Description |
|---|---|
| SSP_SUCCESS | API Call Successful. |
| SSP_ERR_INVALID_ARGUMENT | Parameter has invalid value. |
| SSP_ERR_IN_USE | The channel specified has already been opened. No configurations were changed. Call the associated Close function or use associated control commands to reconfigure the channel. |
| SSP_ERR_ASSERTION | The parameter p_ctrl or p_sample is NULL. |
| SSP_ERR_WRITE_PROTECTED | SD or MMC card is Write Protected. |
| SF_INFO_NOT_AVAILABLE | Information is not available possibly because card has been removed or is defective. |
| SSP_ERR_NOT_OPEN | The channel is not opened. |
The Block Media Framework Interface is simply an abstract interface using function pointers instead of direct function calls. Functions are called between FileX and the SSP block media drivers, such as the SDMMC and the SPI Flash. The interface remains the same for any media driver, so all media drivers appear functionally identical at the file I/O layer and can be interchanged with one another without changing code. Device adaptation drivers, such as sf_block_media_sdmmc, are accessed through the Block Media Framework Interface and provide device specific code needed to perform media I/O operations. Configuration and control structures passed through block media function calls are generally device specific as well.
This section describes how to include the Block Media SDMMC Framework Module in an application using the SSP configurator.
To add the Block Media SDMMC Framework to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Block Media SDMMC Framework is g_sf_block_media_sdmmc0. This name can be changed in the associated Properties window.)
Block Media SDMMC Framework Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_sf_block_media_sdmmc0 Block Media Framework on sf_block_media_sdmmc | Threads | New Stack> Framework> File system> Block Media Framework |
When the Block Media SDMMC Framework on sf_block_media_sdmmc 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; these are either optional or recommended. (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 Block Media SDMMC Framework Module must be configured by the user for the desired operation. 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. 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 Block Media SDMMC Framework Module 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 | The name to be used for sf_block_media_sdmmc module control block instance. |
| Block size of media in bytes | 512 | Media Block size. |
Typically, only a small number of settings must be modified from the default for 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 will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module.
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, 1 Default: 1 | Channel of SD/MMC peripheral, channel 0 or 1. |
| 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) Default: Disabled | Card interrupt priority selection. |
| DMA Request Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | DMA request interrupt priority selection. |
Configuration Settings for the Transfer Driver on r_dmac Software Activation
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled (Default: BSP) | Selects if code for parameter checking is to be included in the build. |
| Name | g_transfer0 | Module name. |
| Channel | 0 | |
| Mode | Normal | Mode selection. |
| Transfer Size | 1 Byte | Transfer size selection. |
| Destination Address Mode | Fixed | Destination address mode selection. |
| Source Address Mode | Incremented | Source address mode selection. |
| Repeat Area (Unused in Normal Mode | Source | Repeat area selection. |
| Destination Pointer | NULL | Destination pointer selection. |
| Source Pointer | NULL | Source pointer selection. |
| Number of Transfers | 0 | Number of transfers selection. |
| Number of Blocks (Valid only in Block Mode) | 0 | Number of blocks selection. |
| Activation Source (Must enable IRQ) | Software Activation | Activation source selection. |
| Auto Enable | False | Auto enable selection. |
| Callback (Only valid with Software start) | NULL | Callback selection. |
| Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | Interrupt priority selection. |
Configuration Settings for the Transfer Driver on r_dtc Software Activation 1
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Selects if code for parameter checking is to be included in the build. |
| Software Start | Enabled, Disabled Default: Disabled | Software start selection. |
| Linker section to keep DTC vector table | .ssp_dtc_vector_table | Linker section to keep DTC vector table selection. |
| Name | g_transfer0 | Module name. |
| Mode | Normal | Mode selection. |
| Transfer Size | 1 Byte | Transfer size selection. |
| Destination Address Mode | Fixed | Destination address mode selection. |
| Source Address Mode | Incremented | Source address mode selection. |
| Repeat Area (Unused in Normal Mode | Source | Repeat area selection. |
| Interrupt Frequency | After all transfers have completed | Interrupt frequency selection. |
| Destination Pointer | NULL | Destination pointer selection. |
| Source Pointer | NULL | Source pointer selection. |
| Number of Transfers | 0 | Number of transfers selection. |
| Number of Blocks (Valid only in Block Mode) | 0 | Number of blocks selection. |
| Activation Source (Must enable IRQ) | Software Activation 1 | Activation source selection. |
| Auto Enable | False | Auto enable selection. |
| Callback (Only valid with Software start) | NULL | Callback selection. |
| ELC Software Event Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | ELC Software Event interrupt priority selection. |
The SDHI block (used to implement SDMMC and SDIO functions) 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 SDMMC peripheral. 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 illustrates an example selection for the pins.
Pin Selection for the Block Media SDMMC Framework Module on sf_block_media_sdmmc
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| SDHI | Pins | Select Peripherals> Storage:SHDI> SDHI0 |
Pin Configuration Settings for the Block Media SDMMC Framework Module on sf_block_media _sdmmc
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, SD_MMC 1 bit SD_MMC 4 bit MMC 8 bit | Select mode as per application. |
| CLK | None, P413 Default: None | Clock Pin. |
| CMD | None, P412 Default: None | Command Pin. |
| DAT0-7 | None, PXXX Default: None | Data Pin. |
The read and write media and extended read and write SDIO functions are non-blocking and require interrupts and a transfer function, either DMAC or DTC. The read and write functions return SSP_SUCCESS to indicate that the initial operations have started successfully. However, the user application must wait for the user callback and check for event SDMMC_EVENT_TRANSFER_COMPLETE or SDMMC_EVENT_TRANSFER_ERROR to indicate completion of the read or write.
The steps in using the Block Media SDMMC Framework module on sf_block_media_sdmmc in a typical application are:
These common steps are illustrated in a typical operational flow diagram in the following figure:
The typical steps for using the sf_block_media_sdmmc using the sf_el_fx in an application are:
fx_system_initialize (sf_el_fx calls it automatically)fx_media_format (sf_el_fx calls it automatically if "Format media during initialization" property is set to Enabled)fx_media_open (sf_el_fx opens the media automatically)fx_media_read(), fx_file_read()fx_media_write(), fx_file_write().fx_media_open call, all FileX APIs can be used (not only read and write).