TI-RTOS Drivers
tidrivers_cc13xx_cc26xx_2_16_00_08
|
I2S driver interface.
============================================================================
The I2S header file should be included in an application as follows:
The I2S driver simplifies reading and writing to any of the McASP peripherals on the board with Receive and Transmit support. These include blocking, non-blocking, read and write characters on the McASP peripheral. The board's I2S peripheral and pins must be configured before initializing the I2S driver. The application initializes the I2S driver by calling I2S_init() and is then ready to open a I2S by calling I2S_open() and passing in a I2S parameters data structure.
The APIs in this driver serve as an interface to a typical OSAL application. The specific peripheral implementations are responsible to create all the OSAL specific primitives to allow for thread-safe operation.
This module serves as the main interface for OSAL applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a I2S_FxnTable.
The I2S driver interface module is joined (at link time) to a NULL-terminated array of I2S_Config data structures named I2S_config. I2S_config is implemented in the application with each entry being an instance of a I2S peripheral. Each entry in I2S_config contains a:
Go to the source code of this file.
Data Structures | |
struct | I2S_BufDesc |
I2S buffer descriptor for issue/reclaim mode. More... | |
struct | I2S_Params |
Basic I2S Parameters. More... | |
struct | I2S_FxnTable |
The definition of a I2S function table that contains the required set of functions to control a specific I2S driver implementation. More... | |
struct | I2S_Config |
I2S Global configuration. More... | |
Macros | |
#define | I2S_CMD_RESERVED 32 |
#define | I2S_STATUS_RESERVED -32 |
#define | I2S_STATUS_SUCCESS 0 |
Successful status code returned by I2S_control(). More... | |
#define | I2S_STATUS_ERROR -1 |
Generic error status code returned by I2S_control(). More... | |
#define | I2S_STATUS_UNDEFINEDCMD -2 |
An error status code returned by I2S_control() for undefined command codes. More... | |
#define | I2S_ERROR I2S_STATUS_ERROR |
#define | I2S_WAIT_FOREVER ~(0) |
Wait forever define. More... | |
Typedefs | |
typedef struct I2S_Config * | I2S_Handle |
A handle that is returned from a I2S_open() call. More... | |
typedef struct I2S_BufDesc | I2S_BufDesc |
I2S buffer descriptor for issue/reclaim mode. More... | |
typedef void(* | I2S_Callback) (I2S_Handle, I2S_BufDesc *desc) |
The definition of a callback function used by the I2S driver when used in I2S_MODE_CALLBACK. More... | |
typedef enum I2S_DataMode | I2S_DataMode |
I2S mode settings. More... | |
typedef enum I2S_OpMode | I2S_OpMode |
I2S mode settings. More... | |
typedef enum I2S_SerInActiveConfig | I2S_SerInActiveConfig |
I2S Serializer InActive state settings. More... | |
typedef enum I2S_PinMode | I2S_PinMode |
I2S serial pin mode. More... | |
typedef struct I2S_Params | I2S_Params |
Basic I2S Parameters. More... | |
typedef void(* | I2S_CloseFxn) (I2S_Handle handle) |
A function pointer to a driver specific implementation of I2S_CloseFxn(). More... | |
typedef int(* | I2S_ControlFxn) (I2S_Handle handle, unsigned int cmd, void *arg) |
A function pointer to a driver specific implementation of I2S_control(). More... | |
typedef void(* | I2S_InitFxn) (I2S_Handle handle) |
A function pointer to a driver specific implementation of I2S_init(). More... | |
typedef I2S_Handle(* | I2S_OpenFxn) (I2S_Handle handle, I2S_Params *params) |
A function pointer to a driver specific implementation of I2S_OpenFxn(). More... | |
typedef int(* | I2S_IssueFxn) (I2S_Handle handle, I2S_BufDesc *desc) |
A function pointer to a driver specific implementation of I2S_IssueFxn(). More... | |
typedef size_t(* | I2S_ReclaimFxn) (I2S_Handle handle, I2S_BufDesc **desc) |
A function pointer to a driver specific implementation of I2S_ReclaimFxn(). More... | |
typedef struct I2S_FxnTable | I2S_FxnTable |
The definition of a I2S function table that contains the required set of functions to control a specific I2S driver implementation. More... | |
typedef struct I2S_Config | I2S_Config |
I2S Global configuration. More... | |
Enumerations | |
enum | I2S_DataMode { I2S_MODE_CALLBACK, I2S_MODE_ISSUERECLAIM } |
I2S mode settings. More... | |
enum | I2S_OpMode { I2S_OPMODE_TX_ONLY, I2S_OPMODE_RX_ONLY, I2S_OPMODE_TX_RX_SYNC } |
I2S mode settings. More... | |
enum | I2S_SerInActiveConfig { I2S_SERCONFIG_INACT_TRI_STATE, I2S_SERCONFIG_INACT_LOW_LEVEL, I2S_SERCONFIG_INACT_HIGH_LEVEL } |
I2S Serializer InActive state settings. More... | |
enum | I2S_PinMode { I2S_PINMODE_RX, I2S_PINMODE_TX, I2S_PINMODE_INACTIVE } |
I2S serial pin mode. More... | |
Functions | |
void | I2S_close (I2S_Handle handle) |
Function to close a given I2S peripheral specified by the I2S handle. More... | |
int | I2S_control (I2S_Handle handle, unsigned int cmd, void *arg) |
Function performs implementation specific features on a given I2S_Handle. More... | |
void | I2S_init (void) |
Function to initializes the I2S module. More... | |
I2S_Handle | I2S_open (unsigned int index, I2S_Params *params) |
Function to initialize a given I2S peripheral specified by the particular index value. The parameter specifies which mode the I2S will operate. More... | |
void | I2S_Params_init (I2S_Params *params) |
Function to initialize the I2S_Params struct to its defaults. More... | |
int | I2S_read (I2S_Handle handle, I2S_BufDesc *desc) |
Function to queue a buffer of data to the I2S in callback mode for reading. More... | |
int | I2S_readIssue (I2S_Handle handle, I2S_BufDesc *desc) |
Function to queue a buffer of data to the I2S in Issue/Reclaim mode for reading. More... | |
size_t | I2S_readReclaim (I2S_Handle handle, I2S_BufDesc **pDesc) |
Function to retrieve a full buffer of data read by the I2S. More... | |
int | I2S_write (I2S_Handle handle, I2S_BufDesc *desc) |
Function to queue a buffer of data to the I2S in callback mode for writing. More... | |
int | I2S_writeIssue (I2S_Handle handle, I2S_BufDesc *desc) |
Function to queue a buffer of data to the I2S in Issue/Reclaim mode for writing. More... | |
size_t | I2S_writeReclaim (I2S_Handle handle, I2S_BufDesc **pDesc) |
Function to retrieve a buffer that the I2S has finished writing. More... | |
#define I2S_ERROR I2S_STATUS_ERROR |
#define I2S_WAIT_FOREVER ~(0) |
Wait forever define.
typedef struct I2S_Config* I2S_Handle |
A handle that is returned from a I2S_open() call.
typedef struct I2S_BufDesc I2S_BufDesc |
I2S buffer descriptor for issue/reclaim mode.
typedef void(* I2S_Callback) (I2S_Handle, I2S_BufDesc *desc) |
The definition of a callback function used by the I2S driver when used in I2S_MODE_CALLBACK.
I2S_Handle | I2S_Handle |
buf | Pointer to read/write buffer |
count | Number of elements read/written |
typedef enum I2S_DataMode I2S_DataMode |
I2S mode settings.
This enum defines the read and write modes for the configured I2S.
typedef enum I2S_OpMode I2S_OpMode |
I2S mode settings.
This enumeration defines the mode for I2S operation.
typedef enum I2S_SerInActiveConfig I2S_SerInActiveConfig |
I2S Serializer InActive state settings.
This enumeration defines the Serializer configuration in inactive state.
typedef enum I2S_PinMode I2S_PinMode |
I2S serial pin mode.
This enumeration defines the Serial pin configuration
typedef struct I2S_Params I2S_Params |
Basic I2S Parameters.
I2S parameters are used to with the I2S_open() call. Default values for these parameters are set using I2S_Params_init().
typedef void(* I2S_CloseFxn) (I2S_Handle handle) |
A function pointer to a driver specific implementation of I2S_CloseFxn().
typedef int(* I2S_ControlFxn) (I2S_Handle handle, unsigned int cmd, void *arg) |
A function pointer to a driver specific implementation of I2S_control().
typedef void(* I2S_InitFxn) (I2S_Handle handle) |
A function pointer to a driver specific implementation of I2S_init().
typedef I2S_Handle(* I2S_OpenFxn) (I2S_Handle handle, I2S_Params *params) |
A function pointer to a driver specific implementation of I2S_OpenFxn().
typedef int(* I2S_IssueFxn) (I2S_Handle handle, I2S_BufDesc *desc) |
A function pointer to a driver specific implementation of I2S_IssueFxn().
typedef size_t(* I2S_ReclaimFxn) (I2S_Handle handle, I2S_BufDesc **desc) |
A function pointer to a driver specific implementation of I2S_ReclaimFxn().
typedef struct I2S_FxnTable I2S_FxnTable |
The definition of a I2S function table that contains the required set of functions to control a specific I2S driver implementation.
typedef struct I2S_Config I2S_Config |
I2S Global configuration.
The I2S_Config structure contains a set of pointers used to characterize the I2S driver implementation.
This structure needs to be defined before calling I2S_init() and it must not be changed thereafter.
enum I2S_DataMode |
I2S mode settings.
This enum defines the read and write modes for the configured I2S.
Enumerator | |
---|---|
I2S_MODE_CALLBACK |
Non-blocking and will return immediately. When the transfer by the intr is finished the configured callback function is called. |
I2S_MODE_ISSUERECLAIM |
Use I2S_readIssue, I2S_writeIssue calls to queue buffers to the I2S. I2S_readReclaim() blocks until a buffer of data is available. I2S_writeReclaim() blocks until a buffer of data has been written and the descriptor can be returned back to the caller. |
enum I2S_OpMode |
enum I2S_PinMode |
void I2S_close | ( | I2S_Handle | handle | ) |
Function to close a given I2S peripheral specified by the I2S handle.
handle | A I2S_Handle returned from I2S_open |
int I2S_control | ( | I2S_Handle | handle, |
unsigned int | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given I2S_Handle.
Commands for I2S_control can originate from I2S.h or from implementation specific I2S*.h (I2SCC3200.h, etc.. ) files. While commands from I2S.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific I2S*.h files add unique driver capabilities but are not API portable across all I2S driver implementations.
Commands supported by I2S.h follow a I2S_CMD_<cmd> naming convention.
Commands supported by I2S*.h follow a I2S*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See I2S_control command codes for command codes.
See I2S_control return status codes for status codes.
handle | A I2S handle returned from I2S_open() |
cmd | I2S.h or I2S*.h commands. |
arg | An optional R/W (read/write) command argument accompanied with cmd |
void I2S_init | ( | void | ) |
Function to initializes the I2S module.
I2S_Handle I2S_open | ( | unsigned int | index, |
I2S_Params * | params | ||
) |
Function to initialize a given I2S peripheral specified by the particular index value. The parameter specifies which mode the I2S will operate.
index | Logical peripheral number for the I2S indexed into the I2S_config table |
params | Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only). |
void I2S_Params_init | ( | I2S_Params * | params | ) |
Function to initialize the I2S_Params struct to its defaults.
params | An pointer to I2S_Params structure for initialization |
Defaults values are: params.operationMode = I2S_MODE_TX_RX_SYNC; params.samplingFrequency = 16000; params.slotLength = 16; params.bitsPerSample = 16; params.numChannels = 2; params.readMode = I2S_MODE_ISSUERECLAIM; params.readCallback = NULL; params.readTimeout = I2S_WAIT_FOREVER; params.writeMode = I2S_MODE_ISSUERECLAIM; params.writeCallback = NULL; params.writeTimeout = I2S_WAIT_FOREVER; params.customParams = NULL;
params | Parameter structure to initialize |
int I2S_read | ( | I2S_Handle | handle, |
I2S_BufDesc * | desc | ||
) |
Function to queue a buffer of data to the I2S in callback mode for reading.
handle | A I2S_Handle |
desc | A pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function. |
int I2S_readIssue | ( | I2S_Handle | handle, |
I2S_BufDesc * | desc | ||
) |
Function to queue a buffer of data to the I2S in Issue/Reclaim mode for reading.
handle | A I2S_Handle |
desc | A pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function. |
size_t I2S_readReclaim | ( | I2S_Handle | handle, |
I2S_BufDesc ** | pDesc | ||
) |
Function to retrieve a full buffer of data read by the I2S.
handle | A I2S_Handle |
pDesc | A pointer to a I2S_BufDesc pointer. |
int I2S_write | ( | I2S_Handle | handle, |
I2S_BufDesc * | desc | ||
) |
Function to queue a buffer of data to the I2S in callback mode for writing.
handle | A I2S_Handle |
desc | A pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function. |
int I2S_writeIssue | ( | I2S_Handle | handle, |
I2S_BufDesc * | desc | ||
) |
Function to queue a buffer of data to the I2S in Issue/Reclaim mode for writing.
handle | A I2S_Handle |
desc | A pointer to a I2S_BufDesc object. The bufPtr and bufSize fields must be set to a buffer and the size of the buffer before passing to this function. |
size_t I2S_writeReclaim | ( | I2S_Handle | handle, |
I2S_BufDesc ** | pDesc | ||
) |
Function to retrieve a buffer that the I2S has finished writing.
handle | A I2S_Handle |
pDesc | A pointer to a I2S_BufDesc pointer. |