SimpleLink MCU SDK Driver APIs
tidrivers_msp43x_3_01_01_03
|
SDSPI driver interface.
The SDSPI header file should be included in an application as follows:
The SDSPI FatFs driver is used to communicate with SD (Secure Digital) cards via SPI (Serial Peripheral Interface).
The SDSPI driver is a FatFs driver module for the FatFs middleware module. With the exception of the standard driver APIs - SDSPI_open(), SDSPI_close(), and SDSPI_init() - the SDSPI driver is exclusively used by FatFs module to handle the low-level hardware communications.
The SDSPI driver only supports one SSI (SPI) peripheral at a given time. It does not utilize interrupts.
The SDSPI driver is polling based for performance reasons and due to the relatively high SPI bus bit rate. This means it does not utilize the SPI's peripheral interrupts, and it consumes the entire CPU time when communicating with the SPI bus. Data transfers to or from the SD card are typically 512 bytes, which could take a significant amount of time to complete. During this time, only higher priority Tasks, Swis, and Hwis can preempt Tasks making calls that use the FatFs.
Before any FatFs or C I/O APIs can be used, the application needs to open the SDSPI driver. The SDSPI_open() function ensures that the SDSPI disk functions get registered with the FatFs module that subsequently mounts the FatFs volume to that particular drive.
Similarly, the SDSPI_close() function unmounts the FatFs volume and unregisters SDSPI disk functions.
Note that it is up to the application to ensure the no FatFs or C I/O APIs are called before the SDSPI driver has been opened or after the SDSPI driver has been closed.
The SDSPI driver requires the application to initialize board-specific portions of the SDSPI and provide the SDSPI driver with the SDSPI_config structure.
The SDSPI_init() initializes the SDSPI driver snd any board-specific SDSPI peripheral settings.
The <board>.c file declares the SDSPI_config structure. This structure must be provided to the SDSPI driver. It must be initialized before the SDSPI_init() function is called and cannot be changed afterwards.
The SDSPI driver interface defines a configuration data structure:
The SDSPI driver is a driver designed to hook into FatFs. It implements a set of functions that FatFs needs to call to perform basic block data transfers.
A SDSPI driver peripheral implementation doesn't require RTOS protection primitives due to the resource protection provided with FatFs. The only functions that can be called by the application are the standard driver framework functions (_open, _close, etc...).
Once the driver has been opened, the application may used the FatFs APIs or the standard C runtime file I/O calls (fopen, fclose, etc...). Once the driver has been closed, ensure the application does NOT make any file I/O calls.
The SDSPI driver interface module is joined (at link time) to an array of SDSPI_Config data structures named SDSPI_config. SDSPI_config is implemented in the application with each entry being an instance of a SDSPI peripheral. Each entry in SDSPI_config contains a:
The SDSPI APIs are redirected to the device specific implementations using the SDSPI_FxnTable pointer of the SDSPI_config entry. In order to use device specific functions of the SDSPI driver directly, link in the correct driver library for your device and include the device specific SDSPI driver header file (which in turn includes SDSPI.h). For example, for the MSP432 family of devices, you would include the following header file:
#include <stdint.h>
Go to the source code of this file.
Data Structures | |
struct | SDSPI_Params_ |
SDSPI Parameters. More... | |
struct | SDSPI_FxnTable_ |
The definition of a SDSPI function table that contains the required set of functions to control a specific SDSPI driver implementation. More... | |
struct | SDSPI_Config_ |
SDSPI Global configuration. More... | |
Macros | |
#define | SDSPI_CMD_RESERVED (32) |
#define | SDSPI_STATUS_RESERVED (-32) |
#define | SDSPI_STATUS_SUCCESS (0) |
Successful status code returned by SDSPI_control(). More... | |
#define | SDSPI_STATUS_ERROR (-1) |
Generic error status code returned by SDSPI_control(). More... | |
#define | SDSPI_STATUS_UNDEFINEDCMD (-2) |
An error status code returned by SDSPI_control() for undefined command codes. More... | |
Typedefs | |
typedef struct SDSPI_Config_ * | SDSPI_Handle |
A handle that is returned from a SDSPI_open() call. More... | |
typedef struct SDSPI_Params_ | SDSPI_Params |
SDSPI Parameters. More... | |
typedef void(* | SDSPI_InitFxn) (SDSPI_Handle handle) |
A function pointer to a driver specific implementation of SDSPI_init(). More... | |
typedef SDSPI_Handle(* | SDSPI_OpenFxn) (SDSPI_Handle handle, uint_least8_t drv, SDSPI_Params *params) |
A function pointer to a driver specific implementation of SDSPI_open(). More... | |
typedef void(* | SDSPI_CloseFxn) (SDSPI_Handle handle) |
A function pointer to a driver specific implementation of SDSPI_close(). More... | |
typedef int_fast16_t(* | SDSPI_ControlFxn) (SDSPI_Handle handle, uint_fast16_t cmd, void *arg) |
A function pointer to a driver specific implementation of SDSPI_control(). More... | |
typedef struct SDSPI_FxnTable_ | SDSPI_FxnTable |
The definition of a SDSPI function table that contains the required set of functions to control a specific SDSPI driver implementation. More... | |
typedef struct SDSPI_Config_ | SDSPI_Config |
SDSPI Global configuration. More... | |
Functions | |
void | SDSPI_close (SDSPI_Handle handle) |
Function to close a SDSPI peripheral specified by the SDSPI handle. This function unmounts the file system mounted by SDSPI_open and unregisters the SDSPI driver from BIOS' FatFs module. More... | |
int_fast16_t | SDSPI_control (SDSPI_Handle handle, uint_fast16_t cmd, void *arg) |
Function performs implementation specific features on a given SDSPI_Handle. More... | |
void | SDSPI_init (void) |
This function initializes the SDSPI driver module. More... | |
SDSPI_Handle | SDSPI_open (uint_least8_t index, uint_least8_t drv, SDSPI_Params *params) |
This function registers the SDSPI driver with BIOS' FatFs module and mounts the FatFs file system. More... | |
void | SDSPI_Params_init (SDSPI_Params *params) |
Function to initialize the SDSPI_Params struct to its defaults. More... | |
typedef struct SDSPI_Config_* SDSPI_Handle |
A handle that is returned from a SDSPI_open() call.
typedef struct SDSPI_Params_ SDSPI_Params |
SDSPI Parameters.
SDSPI Parameters are used to with the SDSPI_open() call. Default values for these parameters are set using SDSPI_Params_init().
typedef void(* SDSPI_InitFxn) (SDSPI_Handle handle) |
A function pointer to a driver specific implementation of SDSPI_init().
typedef SDSPI_Handle(* SDSPI_OpenFxn) (SDSPI_Handle handle, uint_least8_t drv, SDSPI_Params *params) |
A function pointer to a driver specific implementation of SDSPI_open().
typedef void(* SDSPI_CloseFxn) (SDSPI_Handle handle) |
A function pointer to a driver specific implementation of SDSPI_close().
typedef int_fast16_t(* SDSPI_ControlFxn) (SDSPI_Handle handle, uint_fast16_t cmd, void *arg) |
A function pointer to a driver specific implementation of SDSPI_control().
typedef struct SDSPI_FxnTable_ SDSPI_FxnTable |
The definition of a SDSPI function table that contains the required set of functions to control a specific SDSPI driver implementation.
typedef struct SDSPI_Config_ SDSPI_Config |
SDSPI Global configuration.
The SDSPI_Config structure contains a set of pointers used to characterize the SDSPI driver implementation.
This structure needs to be defined before calling SDSPI_init() and it must not be changed thereafter.
void SDSPI_close | ( | SDSPI_Handle | handle | ) |
Function to close a SDSPI peripheral specified by the SDSPI handle. This function unmounts the file system mounted by SDSPI_open and unregisters the SDSPI driver from BIOS' FatFs module.
handle | A SDSPI handle returned from SDSPI_open |
int_fast16_t SDSPI_control | ( | SDSPI_Handle | handle, |
uint_fast16_t | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given SDSPI_Handle.
Commands for SDSPI_control can originate from SDSPI.h or from implementation specific SDSPI*.h (SDSPICC26XX.h, SDSPIMSP432.h, etc.. ) files. While commands from SDSPI.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific SDSPI*.h files add unique driver capabilities but are not API portable across all SDSPI driver implementations.
Commands supported by SDSPI.h follow a SDSPI_CMD_<cmd> naming convention.
Commands supported by SDSPI*.h follow a SDSPI*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See SDSPI_control command codes for command codes.
See SDSPI_control return status codes for status codes.
handle | A SDSPI handle returned from SDSPI_open() |
cmd | SDSPI.h or SDSPI*.h commands. |
arg | An optional R/W (read/write) command argument accompanied with cmd |
void SDSPI_init | ( | void | ) |
This function initializes the SDSPI driver module.
SDSPI_Handle SDSPI_open | ( | uint_least8_t | index, |
uint_least8_t | drv, | ||
SDSPI_Params * | params | ||
) |
This function registers the SDSPI driver with BIOS' FatFs module and mounts the FatFs file system.
index | Logical peripheral number for the SDSPI indexed into the SDSPI_config table |
drv | Drive number to be associated with the SDSPI FatFs driver |
params | Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only). |
void SDSPI_Params_init | ( | SDSPI_Params * | params | ) |
Function to initialize the SDSPI_Params struct to its defaults.
params | An pointer to SDSPI_Params structure for initialization |
Defaults values are: bitRate = 12500000 (Hz)