Detailed Description

I2CSlave driver interface.

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

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

Operation

The I2CSlave driver operates as a slave on an I2C bus in either I2CSLAVE_MODE_BLOCKING or I2CSLAVE_MODE_CALLBACK. In blocking mode, the task's execution is blocked during the I2CSlave read/write transfer. When the transfer has completed, code execution will resume. In callback mode, the task's execution is not blocked, allowing for other transactions to be queued up or to process some other code. When the transfer has completed, the I2CSlave driver will call a user-specified callback function (from a HWI context).

The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the SYS/BIOS specific primitives to allow for thread-safe operation.

Opening the driver

I2CSlave_Handle      handle;
I2CSlave_Params      params;
I2CSlave_Params_init(&params);
params.transferMode  = I2CSLAVE_MODE_CALLBACK;
params.transferCallbackFxn = someI2CSlaveCallbackFunction;
handle = I2CSlave_open(Board_I2CSLAVE0, &params);
if (handle == NULL) {
    // I2C Slave failed to open
    while (1);
}

Transferring data

A I2CSlave transaction with a I2CSlave peripheral is started by calling I2CSlave_read() or I2CSlave_write(). Each transfer is performed atomically with the I2CSlave peripheral.

ret = I2CSlave_read(i2cSlave, buffer, 5)
if (!ret) {
    //Unsuccessful I2CSlave read
}
I2CSlave_write(i2cSlave, buffer, 3);
if (!ret) {
    //Unsuccessful I2CSlave write
}

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

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

(I2CSlave_FxnTable *) to a set of functions that implement an I2CSlave
(void *) data object that is associated with the I2CSlave_FxnTable
(void *) hardware attributes that are associated to the I2CSlave_FxnTable

Instrumentation

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

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

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

Include dependency graph for I2CSlave.h:

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

Go to the source code of this file.

Data Structures
struct	I2CSlave_Params_
	I2CSlave Parameters. More...

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

struct	I2CSlave_Config_
	I2CSlave Global configuration. More...

Macros
#define	I2CSLAVE_CMD_RESERVED (32)

#define	I2CSLAVE_STATUS_RESERVED (-32)

#define	I2CSLAVE_STATUS_SUCCESS (0)
	Successful status code returned by I2CSlave_control(). More...

#define	I2CSLAVE_STATUS_ERROR (-1)
	Generic error status code returned by I2CSlave_control(). More...

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

Typedefs
typedef struct I2CSlave_Config_ *	I2CSlave_Handle
	A handle that is returned from a I2CSlave_open() call. More...

typedef enum I2CSlave_Mode_	I2CSlave_Mode
	I2CSlave mode. More...

typedef enum I2CSlave_TransferMode_	I2CSlave_TransferMode
	I2CSlave transfer mode. More...

typedef void(*	I2CSlave_CallbackFxn) (I2CSlave_Handle handle, bool status)
	I2CSlave callback function. More...

typedef struct I2CSlave_Params_	I2CSlave_Params
	I2CSlave Parameters. More...

typedef void(*	I2CSlave_CloseFxn) (I2CSlave_Handle handle)
	A function pointer to a driver specific implementation of I2CSlave_close(). More...

typedef int_fast16_t(*	I2CSlave_ControlFxn) (I2CSlave_Handle handle, uint_fast16_t cmd, void *arg)
	A function pointer to a driver specific implementation of I2CSlave_control(). More...

typedef void(*	I2CSlave_InitFxn) (I2CSlave_Handle handle)
	A function pointer to a driver specific implementation of I2CSlave_init(). More...

typedef I2CSlave_Handle(*	I2CSlave_OpenFxn) (I2CSlave_Handle handle, I2CSlave_Params *params)
	A function pointer to a driver specific implementation of I2CSlave_open(). More...

typedef bool(*	I2CSlave_WriteFxn) (I2CSlave_Handle handle, const void *buffer, size_t size)
	A function pointer to a driver specific implementation of I2CSlave_WriteTransaction(). More...

typedef bool(*	I2CSlave_ReadFxn) (I2CSlave_Handle handle, void *buffer, size_t size)
	A function pointer to a driver specific implementation of I2CSlave_ReadFxn(). More...

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

typedef struct I2CSlave_Config_	I2CSlave_Config
	I2CSlave Global configuration. More...

Enumerations
enum	I2CSlave_Mode_ { I2CSLAVE_IDLE_MODE = 0, I2CSLAVE_WRITE_MODE = 1, I2CSLAVE_READ_MODE = 2, I2CSLAVE_START_MODE = 3, I2CSLAVE_ERROR = 0xFF }
	I2CSlave mode. More...

enum	I2CSlave_TransferMode_ { I2CSLAVE_MODE_BLOCKING, I2CSLAVE_MODE_CALLBACK }
	I2CSlave transfer mode. More...

Functions
void	I2CSlave_close (I2CSlave_Handle handle)
	Function to close a I2CSlave peripheral specified by the I2CSlave handle. More...

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

void	I2CSlave_init (void)
	Function to initializes the I2CSlave module. More...

I2CSlave_Handle	I2CSlave_open (uint_least8_t index, I2CSlave_Params *params)
	Function to initialize a given I2CSlave peripheral specified by the particular index value. The parameter specifies which mode the I2CSlave will operate. More...

void	I2CSlave_Params_init (I2CSlave_Params *params)
	Function to initialize the I2CSlave_Params struct to its defaults. More...

bool	I2CSlave_read (I2CSlave_Handle handle, void *buffer, size_t size)
	Function that handles the I2CSlave read for SYS/BIOS. More...

bool	I2CSlave_write (I2CSlave_Handle handle, const void *buffer, size_t size)
	Function that handles the I2CSlave write for SYS/BIOS. More...

Typedef Documentation

§ I2CSlave_Handle

typedef struct I2CSlave_Config_* I2CSlave_Handle

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

§ I2CSlave_Mode

typedef enum I2CSlave_Mode_ I2CSlave_Mode

I2CSlave mode.

This enum defines the state of the I2CSlave driver's state-machine. Do not modify.

§ I2CSlave_TransferMode

typedef enum I2CSlave_TransferMode_ I2CSlave_TransferMode

I2CSlave transfer mode.

I2CSLAVE_MODE_BLOCKING block task execution a I2CSlave transfer is in progress. I2CSLAVE_MODE_CALLBACK does not block task execution; but calls a callback function when the I2CSlave transfer has completed

§ I2CSlave_CallbackFxn

typedef void(* I2CSlave_CallbackFxn) (I2CSlave_Handle handle, bool status)

I2CSlave callback function.

User definable callback function prototype. The I2CSlave driver will call the defined function and pass in the I2CSlave driver's handle, and the return value of I2CSlave_read/I2CSlave_write.

Parameters

I2CSlave_Handle	I2CSlave_Handle
bool	Results of the I2CSlave transaction

§ I2CSlave_Params

typedef struct I2CSlave_Params_ I2CSlave_Params

I2CSlave Parameters.

I2CSlave parameters are used to with the I2CSlave_open() call. Default values for these parameters are set using I2CSlave_Params_init().

If I2CSlave_TransferMode is set to I2CSLAVE_MODE_BLOCKING then I2CSlave_read or I2CSlave_write function calls will block thread execution until the transaction has completed.

If I2CSlave_TransferMode is set to I2CSLAVE_MODE_CALLBACK then I2CSlave read/write will not block thread execution and it will call the function specified by transferCallbackFxn. (regardless of error state).

See also: I2CSlave_Params_init()

§ I2CSlave_CloseFxn

typedef void(* I2CSlave_CloseFxn) (I2CSlave_Handle handle)

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

§ I2CSlave_ControlFxn

typedef int_fast16_t(* I2CSlave_ControlFxn) (I2CSlave_Handle handle, uint_fast16_t cmd, void *arg)

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

§ I2CSlave_InitFxn

typedef void(* I2CSlave_InitFxn) (I2CSlave_Handle handle)

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

§ I2CSlave_OpenFxn

typedef I2CSlave_Handle(* I2CSlave_OpenFxn) (I2CSlave_Handle handle, I2CSlave_Params *params)

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

§ I2CSlave_WriteFxn

typedef bool(* I2CSlave_WriteFxn) (I2CSlave_Handle handle, const void *buffer, size_t size)

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

§ I2CSlave_ReadFxn

typedef bool(* I2CSlave_ReadFxn) (I2CSlave_Handle handle, void *buffer, size_t size)

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

§ I2CSlave_FxnTable

typedef struct I2CSlave_FxnTable_ I2CSlave_FxnTable

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

§ I2CSlave_Config

typedef struct I2CSlave_Config_ I2CSlave_Config

I2CSlave Global configuration.

The I2CSlave_Config structure contains a set of pointers used to characterize the I2CSlave driver implementation.

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

See also: I2CSlave_init()

Enumeration Type Documentation

§ I2CSlave_Mode_

enum I2CSlave_Mode_

I2CSlave mode.

This enum defines the state of the I2CSlave driver's state-machine. Do not modify.

Enumerator
I2CSLAVE_IDLE_MODE	I2CSlave is not performing a transaction
I2CSLAVE_WRITE_MODE	I2CSlave is currently performing write
I2CSLAVE_READ_MODE	I2CSlave is currently performing read
I2CSLAVE_START_MODE	I2CSlave received a START from a master
I2CSLAVE_ERROR	I2CSlave error has occurred, exit gracefully

§ I2CSlave_TransferMode_

enum I2CSlave_TransferMode_

I2CSlave transfer mode.

I2CSLAVE_MODE_BLOCKING block task execution a I2CSlave transfer is in progress. I2CSLAVE_MODE_CALLBACK does not block task execution; but calls a callback function when the I2CSlave transfer has completed

Enumerator
I2CSLAVE_MODE_BLOCKING	I2CSlave read/write blocks execution
I2CSLAVE_MODE_CALLBACK	I2CSlave read/wrire queues transactions and does not block

Function Documentation

§ I2CSlave_close()

void I2CSlave_close ( I2CSlave_Handle handle )

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

Precondition: I2CSlave_open() had to be called first.

Parameters

handle A I2CSlave_Handle returned from I2CSlave_open

See also: I2CSlave_open()

§ I2CSlave_control()

int_fast16_t I2CSlave_control	(	I2CSlave_Handle	handle,
		uint_fast16_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given I2CSlave_Handle.

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

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

See I2CSlave_control command codes for command codes.

See I2CSlave_control return status codes for status codes.

Precondition: I2CSlave_open() has to be called first.

Parameters

handle	A I2CSlave handle returned from I2CSlave_open()
cmd	A command value defined by the driver specific implementation
arg	An optional R/W (read/write) argument that is accompanied with cmd

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

See also: I2CSlave_open()

§ I2CSlave_init()

void I2CSlave_init ( void )

Function to initializes the I2CSlave module.

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

§ I2CSlave_open()

I2CSlave_Handle I2CSlave_open	(	uint_least8_t	index,
		I2CSlave_Params *	params
	)

Function to initialize a given I2CSlave peripheral specified by the particular index value. The parameter specifies which mode the I2CSlave will operate.

Precondition: I2CSlave controller has been initialized

Parameters

index	Logical peripheral number for the I2CSlave indexed into the I2CSlave_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).

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

See also: I2CSlave_init(); I2CSlave_close()

§ I2CSlave_Params_init()

void I2CSlave_Params_init ( I2CSlave_Params * params )

Function to initialize the I2CSlave_Params struct to its defaults.

Parameters

params An pointer to I2CSlave_Params structure for initialization

Defaults values are: transferMode = I2CSLAVE_MODE_BLOCKING transferCallbackFxn = NULL

§ I2CSlave_read()

bool I2CSlave_read	(	I2CSlave_Handle	handle,
		void *	buffer,
		size_t	size
	)

Function that handles the I2CSlave read for SYS/BIOS.

This function will start a I2CSlave read and can only be called from a Task context when in I2CSLAVE_MODE_BLOCKING. The I2CSlave read procedure starts with evaluating how many bytes are to be readby the I2CSlave peripheral.

The data written by the I2CSlave is synchronized with the START and STOP from the master.

In I2CSLAVE_MODE_BLOCKING, I2CSlave read/write will block task execution until the transaction has completed.

In I2CSLAVE_MODE_CALLBACK, I2CSlave read/write does not block task execution and calls a callback function specified by transferCallbackFxn. If a transfer is already taking place, the transaction is put on an internal queue. The queue is serviced in a first come first served basis.

Parameters

handle	A I2CSlave_Handle
buffer	A RO (read-only) pointer to an empty buffer in which received data should be written to.
size	The number of bytes to be written into buffer

Returns: true on successful transfer, false on an error

See also: I2CSlave_open

§ I2CSlave_write()

bool I2CSlave_write	(	I2CSlave_Handle	handle,
		const void *	buffer,
		size_t	size
	)

Function that handles the I2CSlave write for SYS/BIOS.

This function will start a I2CSlave write and can only be called from a Task context when in I2CSLAVE_MODE_BLOCKING. The I2CSlave transfer procedure starts with evaluating how many bytes are to be written.

The data written by the I2CSlave is synchronized with the START and STOP from the master. If slave does not have as many bytes requested by master it writes 0xFF. I2CSlave keeps sending 0xFF till master sends a STOP.

In I2CSLAVE_MODE_BLOCKING, I2CSlave read/write will block task execution until the transaction has completed.

In I2CSLAVE_MODE_CALLBACK, I2CSlave read/write does not block task execution and calls a callback function specified by transferCallbackFxn. If a transfer is already taking place, the transaction is put on an internal queue. The queue is serviced in a first come first served basis. The I2CSlave_Transaction structure must stay persistent until the I2CSlave read/write function has completed!

Parameters

handle	A I2CSlave_Handle
buffer	A WO (write-only) pointer to buffer containing data to be written to the master.
size	The number of bytes in buffer that should be written onto the master.

Returns: true on successful write false on an error

See also: I2CSlave_open

Detailed Description

Operation

Opening the driver

Transferring data

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

§ I2CSlave_Handle

§ I2CSlave_Mode

§ I2CSlave_TransferMode

§ I2CSlave_CallbackFxn

§ I2CSlave_Params

§ I2CSlave_CloseFxn

§ I2CSlave_ControlFxn

§ I2CSlave_InitFxn

§ I2CSlave_OpenFxn

§ I2CSlave_WriteFxn

§ I2CSlave_ReadFxn

§ I2CSlave_FxnTable

§ I2CSlave_Config

Enumeration Type Documentation

§ I2CSlave_Mode_

§ I2CSlave_TransferMode_

Function Documentation

§ I2CSlave_close()

§ I2CSlave_control()

§ I2CSlave_init()

§ I2CSlave_open()

§ I2CSlave_Params_init()

§ I2CSlave_read()

§ I2CSlave_write()