Detailed Description

SD driver interface.

============================================================================

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

Operation

The SD driver is designed to serve as an interface to perform basic transfers directly to the SD card.

Opening the driver

SD_Handle handle;
handle = SD_open(Board_SD0, NULL);
if (handle == NULL) {
    //Error opening SD driver
    while (1);
}

Implementation

This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a SD_FxnTable.

The SD driver interface module is joined (at link time) to a NULL-terminated array of SD_Config data structures named SD_config. SD_config is implemented in the application with each entry being an instance of a SD peripheral. Each entry in SD_config contains a:

(SD_FxnTable *) to a set of functions that implement a SD peripheral
(uintptr_t) data object that is associated with the SD_FxnTable
(uintptr_t) hardware attributes that are associated to the SD_FxnTable

Instrumentation

The SD driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask	Log details
Diags_USER1	basic operations performed
Diags_USER2	detailed operations performed

#include <stdint.h>

Include dependency graph for SD.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	SD_Params_
	SD Parameters. More...

struct	SD_FxnTable_
	The definition of a SD function table that contains the required set of functions to control a specific SD driver implementation. More...

struct	SD_Config_
	SD Global configuration. More...

Macros
#define	SD_CMD_RESERVED (32)

#define	SD_STATUS_RESERVED (-32)

#define	SD_STATUS_SUCCESS (0)
	Successful status code returned by SD_control(). More...

#define	SD_STATUS_ERROR (-1)
	Generic error status code returned by SD_control(). More...

#define	SD_STATUS_UNDEFINEDCMD (-2)
	An error status code returned by SD_control() for undefined command codes. More...

Typedefs
typedef enum SD_CardType_	SD_CardType
	SD Card type inserted. More...

typedef struct SD_Config_ *	SD_Handle
	A handle that is returned from a SD_open() call. More...

typedef struct SD_Params_	SD_Params
	SD Parameters. More...

typedef void(*	SD_CloseFxn) (SD_Handle handle)
	A function pointer to a driver specific implementation of SD_CloseFxn(). More...

typedef int_fast16_t(*	SD_ControlFxn) (SD_Handle handle, uint_fast16_t cmd, void *arg)
	A function pointer to a driver specific implementation of SD_controlFxn(). More...

typedef uint_fast32_t(*	SD_getNumSectorsFxn) (SD_Handle handle)
	A function pointer to a driver specific implementation of SD_getNumSectorsFxn(). More...

typedef uint_fast32_t(*	SD_getSectorSizeFxn) (SD_Handle handle)
	A function pointer to a driver specific implementation of SD_getSectorSizeFxn(). More...

typedef void(*	SD_InitFxn) (SD_Handle handle)
	A function pointer to a driver specific implementation of SD_InitFxn(). More...

typedef int_fast16_t(*	SD_InitializeFxn) (SD_Handle handle)
	A function pointer to a driver specific implementation of SD_initializeFxn(). More...

typedef SD_Handle(*	SD_OpenFxn) (SD_Handle handle, SD_Params *params)
	A function pointer to a driver specific implementation of SD_OpenFxn(). More...

typedef int_fast16_t(*	SD_ReadFxn) (SD_Handle handle, void *buf, int_fast32_t sector, uint_fast32_t secCount)
	A function pointer to a driver specific implementation of SD_readFxn(). More...

typedef int_fast16_t(*	SD_WriteFxn) (SD_Handle handle, const void *buf, int_fast32_t sector, uint_fast32_t secCount)
	A function pointer to a driver specific implementation of SD_writeFxn(). More...

typedef struct SD_FxnTable_	SD_FxnTable
	The definition of a SD function table that contains the required set of functions to control a specific SD driver implementation. More...

typedef struct SD_Config_	SD_Config
	SD Global configuration. More...

Enumerations
enum	SD_CardType_ { SD_NOCARD = 0, SD_MMC = 1, SD_SDSC = 2, SD_SDHC = 3 }
	SD Card type inserted. More...

Functions
void	SD_close (SD_Handle handle)
	Function to close a SD peripheral specified by the SD handle. More...

int_fast16_t	SD_control (SD_Handle handle, uint_fast16_t cmd, void *arg)
	Function performs implementation specific features on a given SD_Handle. More...

uint_fast32_t	SD_getNumSectors (SD_Handle handle)
	A function pointer to a driver specific implementation of SD_getNumSectors(). Note: Total Card capacity is the (NumberOfSectors * SectorSize). More...

uint_fast32_t	SD_getSectorSize (SD_Handle handle)
	Function to obtain the sector size used to access the SD card. More...

void	SD_init (void)
	This function initializes the SD driver. More...

void	SD_Params_init (SD_Params *params)
	Function to initialize the SD_Params struct to its defaults. More...

int_fast16_t	SD_initialize (SD_Handle handle)
	A function pointer to a driver specific implementation of SD_initialize(). More...

SD_Handle	SD_open (uint_least8_t index, SD_Params *params)
	A function pointer to a driver specific implementation of SD_open(). More...

int_fast16_t	SD_read (SD_Handle handle, void *buf, int_fast32_t sector, uint_fast32_t secCount)
	A function pointer to a driver specific implementation of SD_read(). More...

int_fast16_t	SD_write (SD_Handle handle, const void *buf, int_fast32_t sector, uint_fast32_t secCount)
	A function pointer to a driver specific implementation of SD_write(). More...

Typedef Documentation

§ SD_CardType

typedef enum SD_CardType_ SD_CardType

SD Card type inserted.

§ SD_Handle

typedef struct SD_Config_* SD_Handle

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

§ SD_Params

typedef struct SD_Params_ SD_Params

SD Parameters.

SD Parameters are used to with the SD_open() call. Default values for these parameters are set using SD_Params_init().

See also: SD_Params_init()

§ SD_CloseFxn

typedef void(* SD_CloseFxn) (SD_Handle handle)

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

§ SD_ControlFxn

typedef int_fast16_t(* SD_ControlFxn) (SD_Handle handle, uint_fast16_t cmd, void *arg)

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

§ SD_getNumSectorsFxn

typedef uint_fast32_t(* SD_getNumSectorsFxn) (SD_Handle handle)

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

§ SD_getSectorSizeFxn

typedef uint_fast32_t(* SD_getSectorSizeFxn) (SD_Handle handle)

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

§ SD_InitFxn

typedef void(* SD_InitFxn) (SD_Handle handle)

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

§ SD_InitializeFxn

typedef int_fast16_t(* SD_InitializeFxn) (SD_Handle handle)

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

§ SD_OpenFxn

typedef SD_Handle(* SD_OpenFxn) (SD_Handle handle, SD_Params *params)

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

§ SD_ReadFxn

typedef int_fast16_t(* SD_ReadFxn) (SD_Handle handle, void *buf, int_fast32_t sector, uint_fast32_t secCount)

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

§ SD_WriteFxn

typedef int_fast16_t(* SD_WriteFxn) (SD_Handle handle, const void *buf, int_fast32_t sector, uint_fast32_t secCount)

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

§ SD_FxnTable

typedef struct SD_FxnTable_ SD_FxnTable

The definition of a SD function table that contains the required set of functions to control a specific SD driver implementation.

§ SD_Config

typedef struct SD_Config_ SD_Config

SD Global configuration.

The SD_Config structure contains a set of pointers used to characterize the SD driver implementation.

This structure needs to be defined before calling SD_init() and it must not be changed thereafter.

See also: SD_init()

Enumeration Type Documentation

§ SD_CardType_

enum SD_CardType_

SD Card type inserted.

Enumerator
SD_NOCARD	Unrecognized Card
SD_MMC	Multi-media Memory Card (MMC)
SD_SDSC	Standard SDCard (SDSC)
SD_SDHC	High Capacity SDCard (SDHC)

Function Documentation

§ SD_close()

void SD_close ( SD_Handle handle )

Function to close a SD peripheral specified by the SD handle.

Precondition: SD_open() had to be called first.

Parameters

handle A SD handle returned from SD_open

See also: SD_open()

§ SD_control()

int_fast16_t SD_control	(	SD_Handle	handle,
		uint_fast16_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given SD_Handle.

Commands for SD_control can originate from SD.h or from implementation specific SD*.h (SDHostCC32XX.h etc.. ) files. While commands from SD.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific SD*.h files add unique driver capabilities but are not API portable across all SD driver implementations.

Commands supported by SD.h follow a SD*_CMD naming convention.

Commands supported by SD*.h follow a SD*_CMD naming convention. Each control command defines arg differently. The types of arg are documented with each command.

See SD_control command codes for command codes.

See SD_control return status codes for status codes.

Precondition: SD_open() has to be called first.

Parameters

handle	A SD handle returned from SD_open().
cmd	SD.h or SD*.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: SD_open()

§ SD_getNumSectors()

uint_fast32_t SD_getNumSectors ( SD_Handle handle )

A function pointer to a driver specific implementation of SD_getNumSectors(). Note: Total Card capacity is the (NumberOfSectors * SectorSize).

Precondition: SD Card has been initialized using SD_initialize().

Parameters

handle A SD handle returned from SD_open().

Returns: The total number of sectors on the SD card, or 0 if an error occurred.

See also: SD_initialize()

§ SD_getSectorSize()

uint_fast32_t SD_getSectorSize ( SD_Handle handle )

Function to obtain the sector size used to access the SD card.

Precondition: SD Card has been initialized using SD_initialize().

Parameters

handle A SD handle returned from SD_open().

Returns: The sector size set for use during SD card read/write operations.

See also: SD_initialize()

§ SD_init()

void SD_init ( void )

This function initializes the SD driver.

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

§ SD_Params_init()

void SD_Params_init ( SD_Params * params )

Function to initialize the SD_Params struct to its defaults.

Parameters

params A pointer to SD_Params structure for initialization.

§ SD_initialize()

int_fast16_t SD_initialize ( SD_Handle handle )

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

Precondition: SD controller has been opened by calling SD_open().

Parameters

handle A SD handle returned from SD_open().

Returns: SD_STATUS_SUCCESS if no errors occurred during the initialization, SD_STATUS_ERROR otherwise.

§ SD_open()

SD_Handle SD_open	(	uint_least8_t	index,
		SD_Params *	params
	)

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

Precondition: SD controller has been initialized using SD_init().

Parameters

index	Logical peripheral number for the SD indexed into the SD_config table.
params	Pointer to a parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).

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

See also: SD_init(); SD_close()

§ SD_read()

int_fast16_t SD_read	(	SD_Handle	handle,
		void *	buf,
		int_fast32_t	sector,
		uint_fast32_t	secCount
	)

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

Precondition: SD controller has been opened and initialized by calling SD_open() followed by SD_initialize().

Parameters

handle	A SD handle returned from SD_open().
buf	Pointer to a buffer to read data into.
sector	Starting sector on the disk to read from.
secCount	Number of sectors to be read.

Returns: SD_STATUS_SUCCESS if no errors occurred during the write, SD_STATUS_ERROR otherwise.

See also: SD_initialize()

§ SD_write()

int_fast16_t SD_write	(	SD_Handle	handle,
		const void *	buf,
		int_fast32_t	sector,
		uint_fast32_t	secCount
	)

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

Precondition: SD controller has been opened and initialized by calling SD_open() followed by SD_initialize().

Parameters

handle	A SD handle returned from SD_open().
buf	Pointer to a buffer containing data to write to disk.
sector	Starting sector on the disk to write to.
secCount	Number of sectors to be written.

Returns: SD_STATUS_SUCCESS if no errors occurred during the write, SD_STATUS_ERROR otherwise.

See also: SD_initialize()

Detailed Description

Operation

Opening the driver

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

§ SD_CardType

§ SD_Handle

§ SD_Params

§ SD_CloseFxn

§ SD_ControlFxn

§ SD_getNumSectorsFxn

§ SD_getSectorSizeFxn

§ SD_InitFxn

§ SD_InitializeFxn

§ SD_OpenFxn

§ SD_ReadFxn

§ SD_WriteFxn

§ SD_FxnTable

§ SD_Config

Enumeration Type Documentation

§ SD_CardType_

Function Documentation

§ SD_close()

§ SD_control()

§ SD_getNumSectors()

§ SD_getSectorSize()

§ SD_init()

§ SD_Params_init()

§ SD_initialize()

§ SD_open()

§ SD_read()

§ SD_write()