Detailed Description

USBMSCHFatFs driver interface.

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

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

Operation

The USBMSCHFatFs 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.

This driver is designed to work with the USB Library. Because it is running in host mode, we need to add protection when accessing the USB Library. A gate was added to prevent the task servicing the USB library to preempt any other task accessing the USB Library.

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 driver

USBMSCHFatFs_Handle      handle;
USBMSCHFatFs_Params      params;
USBMSCHFatFs_Params_init(&params);
params.servicePriority  = somePriority;
handle = USBMSCHFatFs_open(someUSBMSCHFatFs_configIndexValue, &params);
if (!handle) {
    System_printf("USBMSCHFatFs did not open");
}

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

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

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

Instrumentation

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

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

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

Include dependency graph for USBMSCHFatFs.h:

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

Go to the source code of this file.

Data Structures
struct	USBMSCHFatFs_Params
	USBMSCHFatFs Parameters. More...

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

struct	USBMSCHFatFs_Config
	USBMSCHFatFs Global configuration. More...

Macros
#define	USBMSCHFatFs_CMD_RESERVED 32

#define	USBMSCHFatFs_STATUS_RESERVED -32

#define	USBMSCHFatFs_STATUS_SUCCESS 0
	Successful status code returned by USBMSCHFatFs_control(). More...

#define	USBMSCHFatFs_STATUS_ERROR -1
	Generic error status code returned by USBMSCHFatFs_control(). More...

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

Typedefs
typedef struct USBMSCHFatFs_Config *	USBMSCHFatFs_Handle
	USBMSCHFatFs Handler. More...

typedef struct USBMSCHFatFs_Params	USBMSCHFatFs_Params
	USBMSCHFatFs Parameters. More...

typedef void(*	USBMSCHFatFs_InitFxn) (USBMSCHFatFs_Handle handle)
	A function pointer to a driver specific implementation of USBMSCHFatFs_init(). More...

typedef USBMSCHFatFs_Handle(*	USBMSCHFatFs_OpenFxn) (USBMSCHFatFs_Handle handle, unsigned char drv, USBMSCHFatFs_Params *params)
	A function pointer to a driver specific implementation of USBMSCHFatFs_open(). More...

typedef void(*	USBMSCHFatFs_CloseFxn) (USBMSCHFatFs_Handle handle)
	A function pointer to a driver specific implementation of USBMSCHFatFs_close(). More...

typedef int(*	USBMSCHFatFs_ControlFxn) (USBMSCHFatFs_Handle handle, unsigned int cmd, void *arg)
	A function pointer to a driver specific implementation of USBMSCHFatFs_control(). More...

typedef bool(*	USBMSCHFatFs_waitForconnectFxn) (USBMSCHFatFs_Handle handle, unsigned int timeout)
	A function pointer to a driver specific implementation of USBMSCHFatFs_waitForConnect(). More...

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

typedef struct USBMSCHFatFs_Config	USBMSCHFatFs_Config
	USBMSCHFatFs Global configuration. More...

Functions
void	USBMSCHFatFs_close (USBMSCHFatFs_Handle handle)
	Function to closes a given USBMSCHFatFs peripheral specified by the USBMSCHFatFs handle. This function unmounts the file system mounted by USBMSCHFatFs_open and unregisters the USBMSCHFatFs driver from BIOS' FatFs module. More...

int	USBMSCHFatFs_control (USBMSCHFatFs_Handle handle, unsigned int cmd, void *arg)
	Function performs implementation specific features on a given USBMSCHFatFs_Handle. More...

void	USBMSCHFatFs_init (void)
	Function to initialize the USBMSCHFatFs module. More...

USBMSCHFatFs_Handle	USBMSCHFatFs_open (unsigned int index, unsigned char drv, USBMSCHFatFs_Params *params)
	This function registers the USBMSCHFatFs driver with BIOS' FatFs module and mounts the FatFs file system. More...

void	USBMSCHFatFs_Params_init (USBMSCHFatFs_Params *params)
	Function to initialize the USBMSCHFatFs_Params structure to its defaults. More...

bool	USBMSCHFatFs_waitForConnect (USBMSCHFatFs_Handle handle, unsigned int timeout)
	Function blocks task execution while no USB drive is enumerated. After the USBMSCHFatFs driver has been opened this functino is used to determine when a USB drive is has been enumerated. More...

Typedef Documentation

typedef struct USBMSCHFatFs_Config* USBMSCHFatFs_Handle

USBMSCHFatFs Handler.

typedef struct USBMSCHFatFs_Params USBMSCHFatFs_Params

USBMSCHFatFs Parameters.

USBMSCHFatFs parameters are used to with the USBMSCHFatFs_open() call. Default values for these parameters are set using USBMSCHFatFs_Params_init().

See also: USBMSCHFatFs_Params_init()

typedef void(* USBMSCHFatFs_InitFxn) (USBMSCHFatFs_Handle handle)

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

typedef USBMSCHFatFs_Handle(* USBMSCHFatFs_OpenFxn) (USBMSCHFatFs_Handle handle, unsigned char drv, USBMSCHFatFs_Params *params)

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

typedef void(* USBMSCHFatFs_CloseFxn) (USBMSCHFatFs_Handle handle)

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

typedef int(* USBMSCHFatFs_ControlFxn) (USBMSCHFatFs_Handle handle, unsigned int cmd, void *arg)

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

typedef bool(* USBMSCHFatFs_waitForconnectFxn) (USBMSCHFatFs_Handle handle, unsigned int timeout)

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

typedef struct USBMSCHFatFs_FxnTable USBMSCHFatFs_FxnTable

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

typedef struct USBMSCHFatFs_Config USBMSCHFatFs_Config

USBMSCHFatFs Global configuration.

The USBMSCHFatFs_Config structure contains a set of pointers used to characterize the USBMSCHFatFs driver implementation.

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

See also: USBMSCHFatFs_init()

Function Documentation

void USBMSCHFatFs_close ( USBMSCHFatFs_Handle handle )

Function to closes a given USBMSCHFatFs peripheral specified by the USBMSCHFatFs handle. This function unmounts the file system mounted by USBMSCHFatFs_open and unregisters the USBMSCHFatFs driver from BIOS' FatFs module.

Precondition: USBMSCHFatFs_open() had to be called first.

Postcondition: After calling this function, it is safe to remove the USB drive

Parameters

handle A USBMSCHFatFs_Handle returned from USBMSCHFatFs_open

See also: USBMSCHFatFs_open()

int USBMSCHFatFs_control	(	USBMSCHFatFs_Handle	handle,
		unsigned int	cmd,
		void *	arg
	)

Function performs implementation specific features on a given USBMSCHFatFs_Handle.

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

Commands supported by USBMSCHFatFs.h follow a USBMSCHFatFs_CMD_<cmd> naming convention.
Commands supported by USBMSCHFatFs*.h follow a USBMSCHFatFs*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See USBMSCHFatFs_control command codes for command codes.

See USBMSCHFatFs_control return status codes for status codes.

Precondition: USBMSCHFatFs_open() has to be called first.

Parameters

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

void USBMSCHFatFs_init ( void )

Function to initialize the USBMSCHFatFs module.

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

USBMSCHFatFs_Handle USBMSCHFatFs_open	(	unsigned int	index,
		unsigned char	drv,
		USBMSCHFatFs_Params *	params
	)

This function registers the USBMSCHFatFs driver with BIOS' FatFs module and mounts the FatFs file system.

Precondition: USBMSCHFatFs_Params_init() has been called

Parameters

index	Logical peripheral number for the USBMSCHFatFs indexed into the USBMSCHFatFs_config table
drv	Drive number to be associated with the USBMSCHFatFs 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 pointer to a USBMSCHFatFs_Handle on success or a NULL it was already opened

See also: USBMSCHFatFs_init(); USBMSCHFatFs_close()

void USBMSCHFatFs_Params_init ( USBMSCHFatFs_Params * params )

Function to initialize the USBMSCHFatFs_Params structure to its defaults.

Parameters

params An pointer to USBMSCHFatFs_Params structure for initialization

Defaults values are: servicePriority = Task_numPriorities - 1;

bool USBMSCHFatFs_waitForConnect	(	USBMSCHFatFs_Handle	handle,
		unsigned int	timeout
	)

Function blocks task execution while no USB drive is enumerated. After the USBMSCHFatFs driver has been opened this functino is used to determine when a USB drive is has been enumerated.

Parameters

handle	A USBMSCHFatFs handle
timeout	Timeout period in system ticks for the task to block

Returns

status:

true: Successful
false: timed out

Detailed Description

Operation

Opening the driver

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Functions

Typedef Documentation

Function Documentation