Detailed Description

SDSPI driver interface.

The SDSPI header file should be included in an application as follows:

Overview

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.

Usage

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.

SDSPI_Handle sdspiHandle;
SDSPI_Params sdspiParams;
UInt peripheralNum = 0;
UInt FatFsDriveNum = 0;
SDSPI_Params_init(&sdspiParams);
sdspiHandle = SDSPI_open(peripheralNum, FatFsDriveNum, &sdspiParams);
if (sdspiHandle == NULL) {
    System_abort("Error opening SDSPI\n");
}

Similarly, the SDSPI_close() function unmounts the FatFs volume and unregisters SDSPI disk functions.

SDSPI_close(sdspiHandle);

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.

SDSPI Driver Configuration

The SDSPI driver requires the application to initialize board-specific portions of the SDSPI and provide the SDSPI driver with the SDSPI_config structure.

Board-Specific Configuration

The SDSPI_init() initializes the SDSPI driver snd any board-specific SDSPI peripheral settings.

SDSPI_config Structure

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:

typedef struct SDSPI_Config_ {
    SDSPI_FxnTable const *fxnTablePtr;
    void                 *object;
    void           const *hwAttrs;
} SDSPI_Config;

Operation

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.

Opening the SDSPI driver

SDSPI_Handle handle;
SDSPI_Params params;
SDSPI_Params_init(&params);
params.bitRate = someNewBitRate;
handle = SDSPI_open(someSDSPI_configIndexValue, &params);
if (!handle) {
    System_printf("SDSPI did not open");
}

Implementation

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:

(SDSPI_FxnTable *) to a set of functions that implement a SDSPI peripheral
(void *) data object that is associated with the SDSPI_FxnTable
(void *) hardware attributes that are associated with the SDSPI_FxnTable

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 <ti/drivers/sdspi/SDSPIMSP432.h>

#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 Documentation

§ SDSPI_Handle

typedef struct SDSPI_Config_* SDSPI_Handle

A handle that is returned from a SDSPI_open() call.

§ SDSPI_Params

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().

See also: SDSPI_Params_init()

§ SDSPI_InitFxn

typedef void(* SDSPI_InitFxn) (SDSPI_Handle handle)

A function pointer to a driver specific implementation of SDSPI_init().

§ SDSPI_OpenFxn

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().

§ SDSPI_CloseFxn

typedef void(* SDSPI_CloseFxn) (SDSPI_Handle handle)

A function pointer to a driver specific implementation of SDSPI_close().

§ SDSPI_ControlFxn

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().

§ SDSPI_FxnTable

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.

§ SDSPI_Config

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.

See also: SDSPI_init()

Function Documentation

§ SDSPI_close()

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.

Precondition: SDSPI_open() had to be called first.

Parameters

handle A SDSPI handle returned from SDSPI_open

See also: SDSPI_open()

§ SDSPI_control()

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.

Precondition: SDSPI_open() has to be called first.

Parameters

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

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: SDSPI_open()

§ SDSPI_init()

void SDSPI_init ( void )

This function initializes the SDSPI driver module.

Precondition: The SDSPI_config structure must exist and be persistent before this function can be called. This function must also be called before any other SDSPI driver APIs. This function call does not modify any peripheral registers.

§ SDSPI_open()

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.

Precondition: SDSPI controller has been initialized using SDSPI_init()

Parameters

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).

Returns: A SDSPI_Handle on success or a NULL on an error or if it has been opened already.

See also: SDSPI_init(); SDSPI_close()

§ SDSPI_Params_init()

void SDSPI_Params_init ( SDSPI_Params * params )

Function to initialize the SDSPI_Params struct to its defaults.

Parameters

params An pointer to SDSPI_Params structure for initialization

Defaults values are: bitRate = 12500000 (Hz)

Detailed Description

Overview

Usage

SDSPI Driver Configuration

Board-Specific Configuration

SDSPI_config Structure

Operation

Opening the SDSPI driver

Implementation

Data Structures

Macros

Typedefs

Functions

Typedef Documentation

§ SDSPI_Handle

§ SDSPI_Params

§ SDSPI_InitFxn

§ SDSPI_OpenFxn

§ SDSPI_CloseFxn

§ SDSPI_ControlFxn

§ SDSPI_FxnTable

§ SDSPI_Config

Function Documentation

§ SDSPI_close()

§ SDSPI_control()

§ SDSPI_init()

§ SDSPI_open()

§ SDSPI_Params_init()