ISF  1.1
Intelligent Sensing Framework
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_i2c.h File Reference

isf_i2c.h describes the definitions and types for the ISF I2C component. More...

#include <isf_types.h>
#include "isf.h"
#include <isf_comm.h>

Go to the source code of this file.

Data Structures

struct  i2c_BusConfig_struct
 This structure defines the user-specified parameters for bus configuration. More...
struct  i2c_MessageBuffer_struct
 This structure defines a buffer to hold data read from or written to the I2C bus. More...
struct  i2c_Command_struct
 This structure defines the data of a command transferred over the I2C bus. More...
struct  i2c_BusHandle_struct
 This structure defines the data bus handle. More...
struct  i2c_SlaveHandle_struct
 This structure defines a slave handler. More...

Defines

#define I2C_SIZED_BUFFER(bufSize)   struct { uint16 size; uint8 buffer[(bufSize)]; }
#define I2C_FIND_FIRST_SLAVE   { 0, NULL}
#define I2C_CMD_DEFN(cmdLen)   struct { uint16 nWrite; uint16 nRead; uint8 cmdWords[(cmdLen)]; }
#define I2C_10BITADDRESS_BITMASK   0x8000
#define I2C_MAKE_10BITADDRESS(addr)   (addr | I2C_10BITADDRESS_BITMASK)

Typedefs

typedef comm_Id_t i2c_BusId_t
typedef uint8 i2c_BusConfigFlags_t
typedef comm_State_t i2c_BusState_t
typedef comm_Address_t i2c_AddrHint_t
typedef comm_Flags_t i2c_readFlags_t
typedef comm_Flags_t i2c_writeFlags_t
typedef struct i2c_BusConfig_struct i2c_BusConfig_t
 This structure defines the user-specified parameters for bus configuration.
typedef struct
i2c_MessageBuffer_struct 
i2c_MessageBuffer_t
 This structure defines a buffer to hold data read from or written to the I2C bus.
typedef struct i2c_Command_struct i2c_Command_t
 This structure defines the data of a command transferred over the I2C bus.
typedef struct i2c_BusHandle_struct i2c_BusHandle_t
 This structure defines the data bus handle.
typedef struct
i2c_SlaveHandle_struct 
i2c_SlaveHandle_t
 This structure defines a slave handler.

Enumerations

enum  i2c_BusConfigFlag_vals { I2C_CONFIG_MASTER = 0x1 }
 These are I2C bus configuration parameters. More...
enum  i2c_writeFlags_vals { I2C_WRITE_FLAGS_DEFAULT = 0x0 }
 These are flags for modifying the behavior of a write. More...
enum  i2c_readFlags_vals { I2C_READ_FLAGS_DEFAULT = 0x0 }
 These are flags for modifying the behavior of a read. More...
enum  i2c_HWSpecificReg_Config { HWSPECIFIC_REG_FREQUENCY = 0, HWSPECIFIC_REG_CTRL_1 = 1, HWSPECIFIC_MAX = 2 }
 These are hardware-specific configuration parameters for devices similar to the FXLC95000CL and should not be modified. More...
enum  i2c_Speed {
  I2C_SPEED_START = 0, I2C_SPEED_600_KHZ = I2C_SPEED_START, I2C_SPEED_400_KHZ = 1, I2C_SPEED_200_KHZ = 2,
  I2C_SPEED_END = 3
}
 These values establish the i2C bus speed. The user can specify other valid speeds by configuring the frequency register via the hwSpecificCfg parameter in the i2c_BusConfig_t structure. More...

Functions

isf_status_t i2c_bus_init (i2c_BusId_t aBusId, i2c_BusHandle_t *apBusHandle)
 This function initializes the I2C bus.
isf_status_t i2c_bus_configure (i2c_BusHandle_t *apBusHandle, i2c_BusConfig_t *apBusConfig)
 This function configures or reconfigures an already initialized bus.
i2c_BusState_t i2c_get_bus_state (i2c_BusHandle_t *apBusHandle)
 This function returns the bus state.
isf_status_t i2c_get_bus_config (i2c_BusHandle_t *apBusHandle, i2c_BusConfig_t *apBusConfig)
 This function returns the current bus configuration.
isf_status_t i2c_get_slave_at (i2c_BusHandle_t *apBusHandle, i2c_AddrHint_t aSlaveAddr, i2c_SlaveHandle_t *apSlaveHandle)
 This function creates a slave handle for a device at a specified bus address.
isf_status_t i2c_bus_enumerate (i2c_BusHandle_t *apBusHandle, i2c_SlaveHandle_t *apPrevSlaveHandle, i2c_SlaveHandle_t *apNextSlaveHandle)
 This function searches for a slave device on the bus.
isf_status_t i2c_bus_start (i2c_BusHandle_t *apBusHandle)
 This function starts a bus.
isf_status_t i2c_bus_stop (i2c_BusHandle_t *apBusHandle, isf_duration_t aTimeout)
 This function stops a bus.
isf_status_t i2c_bus_acquire_lock (i2c_BusHandle_t *apBusHandle, isf_duration_t aTimeout)
 This function locks the bus for exclusive access.
isf_status_t i2c_bus_release_lock (i2c_BusHandle_t *apBusHandle)
 This function releases exclusive access to the bus.
isf_status_t i2c_read (i2c_SlaveHandle_t *apSlaveHandle, i2c_Command_t *apReadCmd, i2c_MessageBuffer_t *apReadBuffer, i2c_readFlags_t aFlags)
 This function reads from an I2C device.
isf_status_t i2c_write (i2c_SlaveHandle_t *apSlaveHandle, i2c_Command_t *apWriteCmd, i2c_writeFlags_t aFlags)
 This function writes to an I2C device.
i2c_BusHandle_ti2c_get_bus_handle (i2c_SlaveHandle_t *apSlaveHandle)
 This function retrieves the bus handle from a slaveHandle.

Detailed Description

isf_i2c.h describes the definitions and types for the ISF I2C component.

File: isf_i2c.h

Copyright (c) 2012, Freescale Semiconductor, Inc.

Definition in file isf_i2c.h.


Define Documentation

#define I2C_10BITADDRESS_BITMASK   0x8000

Macro used to add a flag to distinguish an address as 10-bit,creating an address understandable by the I2C driver.

Definition at line 39 of file isf_i2c.h.

#define I2C_CMD_DEFN (   cmdLen)    struct { uint16 nWrite; uint16 nRead; uint8 cmdWords[(cmdLen)]; }

Macro used for storing the created concretely sized typdedefs compatible with i2c_Command_t.

Definition at line 35 of file isf_i2c.h.

#define I2C_FIND_FIRST_SLAVE   { 0, NULL}

A macro used with * i2c_bus_enumerate() to specify a full search for slave devices.

Definition at line 31 of file isf_i2c.h.

#define I2C_MAKE_10BITADDRESS (   addr)    (addr | I2C_10BITADDRESS_BITMASK)

Macro used for 10-bit addressing. As an example, for an actual 10-bit address of 0x120, I2C_MAKE_10BITADDRESS(0x120) is called to make it acceptable to the I2C module.

Definition at line 42 of file isf_i2c.h.

#define I2C_SIZED_BUFFER (   bufSize)    struct { uint16 size; uint8 buffer[(bufSize)]; }

Properly sized buffer for reads and writes.

Definition at line 25 of file isf_i2c.h.


Typedef Documentation

This item holds an I2C device bus address that can contain both 7-bit and 10-bit addresses.

Definition at line 104 of file isf_i2c.h.

This structure defines the user-specified parameters for bus configuration.

An effort has been made to keep the contents of this type generic, hiding any specific I2C peripheral details in the pHWSpecificCfg field.

This item contains configuration flags used to configure an I2C bus.

Definition at line 96 of file isf_i2c.h.

This structure defines the data bus handle.

This is a numeric bus identifier used to index into an array of buses.

Definition at line 93 of file isf_i2c.h.

This item contains an enumerated value describing the state of an I2C bus.

Definition at line 100 of file isf_i2c.h.

This structure defines the data of a command transferred over the I2C bus.

This structure defines a buffer to hold data read from or written to the I2C bus.

This is a bit array of flags governing I2C read behavior.

Definition at line 109 of file isf_i2c.h.

This structure defines a slave handler.

This is a bit array of flags governing I2C write behavior.

Definition at line 113 of file isf_i2c.h.


Enumeration Type Documentation

These are I2C bus configuration parameters.

Enumerator:
I2C_CONFIG_MASTER 

Configure as Bus Master.

Definition at line 53 of file isf_i2c.h.

These are hardware-specific configuration parameters for devices similar to the FXLC95000CL and should not be modified.

Enumerator:
HWSPECIFIC_REG_FREQUENCY 

The frequency register.

HWSPECIFIC_REG_CTRL_1 

The control one register.

HWSPECIFIC_MAX 

The maximum number of registers.

Definition at line 73 of file isf_i2c.h.

These are flags for modifying the behavior of a read.

Enumerator:
I2C_READ_FLAGS_DEFAULT 

The default read flag values are used.

Definition at line 65 of file isf_i2c.h.

enum i2c_Speed

These values establish the i2C bus speed. The user can specify other valid speeds by configuring the frequency register via the hwSpecificCfg parameter in the i2c_BusConfig_t structure.

Enumerator:
I2C_SPEED_START 

The start of the speed range.

I2C_SPEED_600_KHZ 

The speed at 600 KHz.

I2C_SPEED_400_KHZ 

The speed at 400 KHz.

I2C_SPEED_200_KHZ 

The speed at 200 KHz.

I2C_SPEED_END 

The end of the speed range. It is 200 KHz now.

Definition at line 82 of file isf_i2c.h.

These are flags for modifying the behavior of a write.

Enumerator:
I2C_WRITE_FLAGS_DEFAULT 

The default write flag values are used.

Definition at line 59 of file isf_i2c.h.


Function Documentation

This function locks the bus for exclusive access.

i2c_bus_acquire_lock() serializes multi-client access to the bus. Each bus user should acquire a bus lock prior to sending messages on the bus. While holding the bus lock, no other clients may perform any bus messaging. For this reason, it is important to release the bus lock as soon as practical.

Parameters:
[in]apBusHandleThe handle of the bus to be locked.
[in]aTimeoutThe length of time to wait before returning without the lock. The timeout parameter may be set to 0 to wait forever, or as long as necessary to get the lock.
Returns:
i2c_bus_acquire_lock() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned if the lock was acquired.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized bus.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_bus_configure ( i2c_BusHandle_t apBusHandle,
i2c_BusConfig_t apBusConfig 
)

This function configures or reconfigures an already initialized bus.

A bus may be configured during initialization or it may be configured separately after initialization. Calls made to i2c_bus_configure() after initialization overrides any previous configuration values, and must be made while the bus state is STOPPED.

Parameters:
[in]apBusHandleThe handle of the bus to be configured.
[in]apBusConfigThe configuration parameters to be used during configuration.
Returns:
i2c_bus_configure() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
COMM_ERROR_STOPis returned when the bus was not in a STOPPED state.
COMM_ERROR_INITis returned when the bus is not initialized.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout interval.
COMM_ERROR_LOCKis returned when the request could not be completed as there is a invalid lock associated with the bus.
Constraints:
The following constraints must be observed when using this function:
  • The bus must be initialized and have a valid bus handle.
  • It must be called when the bus is STOPPED.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_bus_enumerate ( i2c_BusHandle_t apBusHandle,
i2c_SlaveHandle_t apPrevSlaveHandle,
i2c_SlaveHandle_t apNextSlaveHandle 
)

This function searches for a slave device on the bus.

To enumerate a bus, i2c_bus_enumerate() is called repeatedly until all the desired slaves are found. The slave handle found on the preceding call is passed in the subsequent call to find the next slave. If all slave addresses are known, bus enumeration is not required and i2c_get_slave_at() may be used to acquire all the slave handles.

Parameters:
[in]apBusHandleThe handle of the bus to be queried.
[in]apPrevSlaveHandleThe known address of a slave device.
[out]apNextSlaveHandleThe known address of the next slave device.
Returns:
i2c_bus_enumerate() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when another slave device was found.
COMM_ERROR_NOEXISTis returned when no more slave devices are found.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized bus.
COMM_ERROR_STOPis returned when the bus is not started.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period provided during the bus configuration.
COMM_ERROR_LOCKis returned when the internal lock request fails due to an invalid lock on the bus handle.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_bus_init ( i2c_BusId_t  aBusId,
i2c_BusHandle_t apBusHandle 
)

This function initializes the I2C bus.

Any I2C bus must be initialized prior to use. Initialization creates and initializes the data structures required to manage the bus. The bus is implicitly locked during initialization.

Parameters:
[in]aBusIdThe ID of the bus to initialize. This is an index into the array of known buses that can be used.
[out]apBusHandleThe bus handle of the bus to be configured.
Returns:
i2c_bus_init() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful. function call.
Return values:
COMM_ERROR_NOEXISTis returned when the supplied bus identifier does not exist.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
COMM_ERROR_INITis returned when the bus could not be initialized.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when the lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
  • aBusId must be in the range of known bus identifiers.
  • apBusConfig must point to a valid i2c_BusConfig_t object for the bus being initialized.
Reentrant: Yes
Link Libraries:
isf_core.lib

This function releases exclusive access to the bus.

i2c_bus_release_lock() relinquishes the bus.

Parameters:
[in]apBusHandleThe handle of the bus to be released.
Returns:
i2c_bus_release_lock() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned if the bus was successfully released.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized bus.
COMM_ERROR_LOCKis returned when there is no lock held on the specified bus.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib

This function starts a bus.

. i2c_bus_start() enables an initialized bus to begin communications. This call enables the hardware peripherals associated with the bus.

Parameters:
[in]apBusHandleThe handle of the bus to be started.
Returns:
i2c_bus_start() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the bus is started.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized bus.
COMM_ERROR_NULL_PTRis returned when a NULL parameter is passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period provided during the bus configuration.
COMM_ERROR_LOCKis returned when the internal lock request fails due to an invalid lock on the bus handle.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_bus_stop ( i2c_BusHandle_t apBusHandle,
isf_duration_t  aTimeout 
)

This function stops a bus.

i2c_bus_stop() disables an initialized bus and stops communications. This call disables the hardware peripherals associated with the bus.

Parameters:
[in]apBusHandleThe handle of the bus to be started.
[in]aTimeoutThe length of time to wait before returning without the stop. The timeout parameter may be set to 0 to wait forever, or as long as necessary to stop.
Returns:
i2c_bus_stop() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the bus is stopped.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized bus.
COMM_ERROR_NULL_PTRis returned when a NULL parameter is passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period provided when the bus was configured.
COMM_ERROR_LOCKis returned when the internal lock request fails due to an invalid lock on the bus handle.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_get_bus_config ( i2c_BusHandle_t apBusHandle,
i2c_BusConfig_t apBusConfig 
)

This function returns the current bus configuration.

A bus may be queried for the current configuration in use.

Parameters:
[in]apBusHandleThe handle of the bus to be queried.
[out]apBusConfigThe address of the configuration of the bus queried.
Returns:
i2c_get_bus_config() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
COMM_ERROR_NULL_PTRis returned when an invalid bus handle was provided to the function.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib

This function retrieves the bus handle from a slaveHandle.

i2c_get_bus_handle() returns the busHandle associated with the bus where the slave resides.

Parameters:
[in]apSlaveHandleHandle of slave device containing the bus handle of interest.
Returns:
i2c_get_bus_handle() returns a value of type i2c_BusHandle_t containing the bus handle.
Return values:
NULLis returned when the specified slave is invalid.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib

This function returns the bus state.

A bus may be queried for its current state.

Parameters:
[in]apBusHandleThe handle of the bus to be queried.
Returns:
i2c_get_bus_state() returns a value of type :: i2c_BusState_t indicating the current state of the bus.
Return values:
COMM_ERROR_NULL_PTRA NULL parameter was passed into the function.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_get_slave_at ( i2c_BusHandle_t apBusHandle,
i2c_AddrHint_t  aSlaveAddr,
i2c_SlaveHandle_t apSlaveHandle 
)

This function creates a slave handle for a device at a specified bus address.

The i2c_get_slave_at() function obtains the handle to a slave device at a known bus address.

Parameters:
[in]apBusHandleThe handle of the bus to be queried.
[in]aSlaveAddrThe known address of a slave device.
[out]apSlaveHandleThe address of the slave handle provided for the slave device on the given bus.
Returns:
i2c_get_slave_at() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when a slave with the given address is found.
COMM_ERROR_NOEXISTis returned when a slave does not exist at the specified address.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized bus.
COMM_ERROR_STOPis returned when the bus has not been started.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period made during the bus configuration.
COMM_ERROR_LOCKis returned when the internal lock request fails due to an invalid lock on the bus handle.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_read ( i2c_SlaveHandle_t apSlaveHandle,
i2c_Command_t apReadCmd,
i2c_MessageBuffer_t apReadBuffer,
i2c_readFlags_t  aFlags 
)

This function reads from an I2C device.

i2c_read() reads data from the specified I2C slave device. The supplied command is sent to the slave device which triggers the device to return some data. Any data returned by the slave is read and placed in the provided read buffer.

Parameters:
[in]apSlaveHandleThe handle to the slave device from which to read.
[in]apReadCmdThe read command to transmit to the device.
[out]apReadBufferAddress of the buffer in which to place the read data.
[in]aFlagsA set of bit flags controlling the behavior of the read.
Returns:
i2c_read() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned if the read is completed successfully.
COMM_ERROR_INITis returned when the specified slave device is on an uninitialized bus.
COMM_ERROR_BUF_SIZEis returned when either the the number of bytes to read is zero or the provided buffer is too small to hold all the data returned. If the provided buffer is too small to hold all the data returned, no data is written to the buffer.
COMM_ERROR_STOPis returned when the read is invoked on a STOPPED bus.
COMM_ERROR_NO_ACKis returned when no acknowledgment has been received from the slave device.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when the request could not be completed as there is a invalid lock associated with bus.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t i2c_write ( i2c_SlaveHandle_t apSlaveHandle,
i2c_Command_t apWriteCmd,
i2c_writeFlags_t  aFlags 
)

This function writes to an I2C device.

i2c_write() writes data to the specified i2c slave device. The supplied command writes to the slave device.

Parameters:
[in]apSlaveHandleThe handle to which the slave device is to write.
[in]apWriteCmdThe command to send to the device.
[in]aFlagsA set of bit flags controlling the behavior of the write.
Returns:
i2c_write() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the write command completes successfully.
COMM_ERROR_INITis returned when the specified slave device is on an uninitialized bus.
COMM_ERROR_STOPis returned when the write is invoked on a STOPPED bus.
COMM_ERROR_NO_ACKis returned when no acknowledgment has been received from the slave device.
COMM_ERROR_NULL_PTRis returned when a NULL parameter was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when the request could not be completed as there is a invalid lock associated with the bus.
Constraints:
None
Reentrant: Yes
Link Libraries:
isf_core.lib