MCUXpresso SDK API Reference Manual
Rev. 0
NXP Semiconductors
|
Data Structures | |
struct | i2c_master_config_t |
Structure with settings to initialize the I2C master module. More... | |
struct | i2c_master_transfer_t |
Non-blocking transfer descriptor structure. More... | |
struct | i2c_master_handle_t |
Driver handle for master non-blocking APIs. More... | |
Typedefs | |
typedef void(* | i2c_master_transfer_callback_t )(I2C_Type *base, i2c_master_handle_t *handle, status_t completionStatus, void *userData) |
Master completion callback function pointer type. More... | |
Enumerations | |
enum | _i2c_master_flags { kI2C_MasterPendingFlag = I2C_STAT_MSTPENDING_MASK, kI2C_MasterArbitrationLostFlag, kI2C_MasterStartStopErrorFlag } |
I2C master peripheral flags. More... | |
enum | i2c_direction_t { kI2C_Write = 0U, kI2C_Read = 1U } |
Direction of master and slave transfers. More... | |
enum | _i2c_master_transfer_flags { kI2C_TransferDefaultFlag = 0x00U, kI2C_TransferNoStartFlag = 0x01U, kI2C_TransferRepeatedStartFlag = 0x02U, kI2C_TransferNoStopFlag = 0x04U } |
Transfer option flags. More... | |
enum | _i2c_transfer_states |
States for the state machine used by transactional APIs. More... | |
Initialization and deinitialization | |
void | I2C_MasterGetDefaultConfig (i2c_master_config_t *masterConfig) |
Provides a default configuration for the I2C master peripheral. More... | |
void | I2C_MasterInit (I2C_Type *base, const i2c_master_config_t *masterConfig, uint32_t srcClock_Hz) |
Initializes the I2C master peripheral. More... | |
void | I2C_MasterDeinit (I2C_Type *base) |
Deinitializes the I2C master peripheral. More... | |
uint32_t | I2C_GetInstance (I2C_Type *base) |
Returns an instance number given a base address. More... | |
static void | I2C_MasterReset (I2C_Type *base) |
Performs a software reset. More... | |
static void | I2C_MasterEnable (I2C_Type *base, bool enable) |
Enables or disables the I2C module as master. More... | |
Status | |
static uint32_t | I2C_GetStatusFlags (I2C_Type *base) |
Gets the I2C status flags. More... | |
static void | I2C_MasterClearStatusFlags (I2C_Type *base, uint32_t statusMask) |
Clears the I2C master status flag state. More... | |
Interrupts | |
static void | I2C_EnableInterrupts (I2C_Type *base, uint32_t interruptMask) |
Enables the I2C master interrupt requests. More... | |
static void | I2C_DisableInterrupts (I2C_Type *base, uint32_t interruptMask) |
Disables the I2C master interrupt requests. More... | |
static uint32_t | I2C_GetEnabledInterrupts (I2C_Type *base) |
Returns the set of currently enabled I2C master interrupt requests. More... | |
Bus operations | |
void | I2C_MasterSetBaudRate (I2C_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz) |
Sets the I2C bus frequency for master transactions. More... | |
static bool | I2C_MasterGetBusIdleState (I2C_Type *base) |
Returns whether the bus is idle. More... | |
status_t | I2C_MasterStart (I2C_Type *base, uint8_t address, i2c_direction_t direction) |
Sends a START on the I2C bus. More... | |
status_t | I2C_MasterStop (I2C_Type *base) |
Sends a STOP signal on the I2C bus. More... | |
static status_t | I2C_MasterRepeatedStart (I2C_Type *base, uint8_t address, i2c_direction_t direction) |
Sends a REPEATED START on the I2C bus. More... | |
status_t | I2C_MasterWriteBlocking (I2C_Type *base, const void *txBuff, size_t txSize, uint32_t flags) |
Performs a polling send transfer on the I2C bus. More... | |
status_t | I2C_MasterReadBlocking (I2C_Type *base, void *rxBuff, size_t rxSize, uint32_t flags) |
Performs a polling receive transfer on the I2C bus. More... | |
status_t | I2C_MasterTransferBlocking (I2C_Type *base, i2c_master_transfer_t *xfer) |
Performs a master polling transfer on the I2C bus. More... | |
Non-blocking | |
void | I2C_MasterTransferCreateHandle (I2C_Type *base, i2c_master_handle_t *handle, i2c_master_transfer_callback_t callback, void *userData) |
Creates a new handle for the I2C master non-blocking APIs. More... | |
status_t | I2C_MasterTransferNonBlocking (I2C_Type *base, i2c_master_handle_t *handle, i2c_master_transfer_t *xfer) |
Performs a non-blocking transaction on the I2C bus. More... | |
status_t | I2C_MasterTransferGetCount (I2C_Type *base, i2c_master_handle_t *handle, size_t *count) |
Returns number of bytes transferred so far. More... | |
status_t | I2C_MasterTransferAbort (I2C_Type *base, i2c_master_handle_t *handle) |
Terminates a non-blocking I2C master transmission early. More... | |
IRQ handler | |
void | I2C_MasterTransferHandleIRQ (I2C_Type *base, i2c_master_handle_t *handle) |
Reusable routine to handle master interrupts. More... | |
struct i2c_master_config_t |
This structure holds configuration settings for the I2C peripheral. To initialize this structure to reasonable defaults, call the I2C_MasterGetDefaultConfig() function and pass a pointer to your configuration structure instance.
The configuration structure can be made constant so it resides in flash.
Data Fields | |
bool | enableMaster |
Whether to enable master mode. More... | |
uint32_t | baudRate_Bps |
Desired baud rate in bits per second. More... | |
bool | enableTimeout |
Enable internal timeout function. More... | |
bool i2c_master_config_t::enableMaster |
uint32_t i2c_master_config_t::baudRate_Bps |
bool i2c_master_config_t::enableTimeout |
struct _i2c_master_transfer |
I2C master transfer typedef.
This structure is used to pass transaction parameters to the I2C_MasterTransferNonBlocking() API.
Data Fields | |
uint32_t | flags |
Bit mask of options for the transfer. More... | |
uint8_t | slaveAddress |
The 7-bit slave address. More... | |
i2c_direction_t | direction |
Either kI2C_Read or kI2C_Write. More... | |
uint32_t | subaddress |
Sub address. More... | |
size_t | subaddressSize |
Length of sub address to send in bytes. More... | |
void * | data |
Pointer to data to transfer. More... | |
size_t | dataSize |
Number of bytes to transfer. More... | |
uint32_t i2c_master_transfer_t::flags |
See enumeration _i2c_master_transfer_flags for available options. Set to 0 or kI2C_TransferDefaultFlag for normal transfers.
uint8_t i2c_master_transfer_t::slaveAddress |
i2c_direction_t i2c_master_transfer_t::direction |
uint32_t i2c_master_transfer_t::subaddress |
Transferred MSB first.
size_t i2c_master_transfer_t::subaddressSize |
Maximum size is 4 bytes.
void* i2c_master_transfer_t::data |
size_t i2c_master_transfer_t::dataSize |
struct _i2c_master_handle |
I2C master handle typedef.
Data Fields | |
uint8_t | state |
Transfer state machine current state. More... | |
uint32_t | transferCount |
Indicates progress of the transfer. | |
uint32_t | remainingBytes |
Remaining byte count in current state. More... | |
uint8_t * | buf |
Buffer pointer for current state. More... | |
i2c_master_transfer_t | transfer |
Copy of the current transfer info. More... | |
i2c_master_transfer_callback_t | completionCallback |
Callback function pointer. More... | |
void * | userData |
Application data passed to callback. More... | |
uint8_t i2c_master_handle_t::state |
uint32_t i2c_master_handle_t::remainingBytes |
uint8_t* i2c_master_handle_t::buf |
i2c_master_transfer_t i2c_master_handle_t::transfer |
i2c_master_transfer_callback_t i2c_master_handle_t::completionCallback |
void* i2c_master_handle_t::userData |
typedef void(* i2c_master_transfer_callback_t)(I2C_Type *base, i2c_master_handle_t *handle, status_t completionStatus, void *userData) |
This callback is used only for the non-blocking master transfer API. Specify the callback you wish to use in the call to I2C_MasterTransferCreateHandle().
base | The I2C peripheral base address. |
completionStatus | Either kStatus_Success or an error code describing how the transfer completed. |
userData | Arbitrary pointer-sized value passed from the application. |
enum _i2c_master_flags |
enum i2c_direction_t |
enum _i2c_transfer_states |
void I2C_MasterGetDefaultConfig | ( | i2c_master_config_t * | masterConfig | ) |
This function provides the following default configuration for the I2C master peripheral:
After calling this function, you can override any settings in order to customize the configuration, prior to initializing the master driver with I2C_MasterInit().
[out] | masterConfig | User provided configuration structure for default values. Refer to i2c_master_config_t. |
void I2C_MasterInit | ( | I2C_Type * | base, |
const i2c_master_config_t * | masterConfig, | ||
uint32_t | srcClock_Hz | ||
) |
This function enables the peripheral clock and initializes the I2C master peripheral as described by the user provided configuration. A software reset is performed prior to configuration.
base | The I2C peripheral base address. |
masterConfig | User provided peripheral configuration. Use I2C_MasterGetDefaultConfig() to get a set of defaults that you can override. |
srcClock_Hz | Frequency in Hertz of the I2C functional clock. Used to calculate the baud rate divisors, filter widths, and timeout periods. |
void I2C_MasterDeinit | ( | I2C_Type * | base | ) |
This function disables the I2C master peripheral and gates the clock. It also performs a software reset to restore the peripheral to reset conditions.
base | The I2C peripheral base address. |
uint32_t I2C_GetInstance | ( | I2C_Type * | base | ) |
If an invalid base address is passed, debug builds will assert. Release builds will just return instance number 0.
base | The I2C peripheral base address. |
|
inlinestatic |
Restores the I2C master peripheral to reset conditions.
base | The I2C peripheral base address. |
|
inlinestatic |
base | The I2C peripheral base address. |
enable | Pass true to enable or false to disable the specified I2C as master. |
|
inlinestatic |
A bit mask with the state of all I2C status flags is returned. For each flag, the corresponding bit in the return value is set if the flag is asserted.
base | The I2C peripheral base address. |
|
inlinestatic |
The following status register flags can be cleared:
Attempts to clear other flags has no effect.
base | The I2C peripheral base address. |
statusMask | A bitmask of status flags that are to be cleared. The mask is composed of _i2c_master_flags enumerators OR'd together. You may pass the result of a previous call to I2C_GetStatusFlags(). |
|
inlinestatic |
base | The I2C peripheral base address. |
interruptMask | Bit mask of interrupts to enable. See _i2c_master_flags for the set of constants that should be OR'd together to form the bit mask. |
|
inlinestatic |
base | The I2C peripheral base address. |
interruptMask | Bit mask of interrupts to disable. See _i2c_master_flags for the set of constants that should be OR'd together to form the bit mask. |
|
inlinestatic |
base | The I2C peripheral base address. |
void I2C_MasterSetBaudRate | ( | I2C_Type * | base, |
uint32_t | baudRate_Bps, | ||
uint32_t | srcClock_Hz | ||
) |
The I2C master is automatically disabled and re-enabled as necessary to configure the baud rate. Do not call this function during a transfer, or the transfer is aborted.
base | The I2C peripheral base address. |
srcClock_Hz | I2C functional clock frequency in Hertz. |
baudRate_Bps | Requested bus frequency in bits per second. |
|
inlinestatic |
Requires the master mode to be enabled.
base | The I2C peripheral base address. |
true | Bus is busy. |
false | Bus is idle. |
status_t I2C_MasterStart | ( | I2C_Type * | base, |
uint8_t | address, | ||
i2c_direction_t | direction | ||
) |
This function is used to initiate a new master mode transfer by sending the START signal. The slave address is sent following the I2C START signal.
base | I2C peripheral base pointer |
address | 7-bit slave device address. |
direction | Master transfer directions(transmit/receive). |
kStatus_Success | Successfully send the start signal. |
kStatus_I2C_Busy | Current bus is busy. |
status_t I2C_MasterStop | ( | I2C_Type * | base | ) |
kStatus_Success | Successfully send the stop signal. |
kStatus_I2C_Timeout | Send stop signal failed, timeout. |
|
inlinestatic |
base | I2C peripheral base pointer |
address | 7-bit slave device address. |
direction | Master transfer directions(transmit/receive). |
kStatus_Success | Successfully send the start signal. |
kStatus_I2C_Busy | Current bus is busy but not occupied by current I2C master. |
status_t I2C_MasterWriteBlocking | ( | I2C_Type * | base, |
const void * | txBuff, | ||
size_t | txSize, | ||
uint32_t | flags | ||
) |
Sends up to txSize number of bytes to the previously addressed slave device. The slave may reply with a NAK to any byte in order to terminate the transfer early. If this happens, this function returns kStatus_I2C_Nak.
base | The I2C peripheral base address. |
txBuff | The pointer to the data to be transferred. |
txSize | The length in bytes of the data to be transferred. |
flags | Transfer control flag to control special behavior like suppressing start or stop, for normal transfers use kI2C_TransferDefaultFlag |
kStatus_Success | Data was sent successfully. |
kStatus_I2C_Busy | Another master is currently utilizing the bus. |
kStatus_I2C_Nak | The slave device sent a NAK in response to a byte. |
kStatus_I2C_ArbitrationLost | Arbitration lost error. |
status_t I2C_MasterReadBlocking | ( | I2C_Type * | base, |
void * | rxBuff, | ||
size_t | rxSize, | ||
uint32_t | flags | ||
) |
base | The I2C peripheral base address. |
rxBuff | The pointer to the data to be transferred. |
rxSize | The length in bytes of the data to be transferred. |
flags | Transfer control flag to control special behavior like suppressing start or stop, for normal transfers use kI2C_TransferDefaultFlag |
kStatus_Success | Data was received successfully. |
kStatus_I2C_Busy | Another master is currently utilizing the bus. |
kStatus_I2C_Nak | The slave device sent a NAK in response to a byte. |
kStatus_I2C_ArbitrationLost | Arbitration lost error. |
status_t I2C_MasterTransferBlocking | ( | I2C_Type * | base, |
i2c_master_transfer_t * | xfer | ||
) |
base | I2C peripheral base address. |
xfer | Pointer to the transfer structure. |
kStatus_Success | Successfully complete the data transmission. |
kStatus_I2C_Busy | Previous transmission still not finished. |
kStatus_I2C_Timeout | Transfer error, wait signal timeout. |
kStatus_I2C_ArbitrationLost | Transfer error, arbitration lost. |
kStataus_I2C_Nak | Transfer error, receive NAK during transfer. |
void I2C_MasterTransferCreateHandle | ( | I2C_Type * | base, |
i2c_master_handle_t * | handle, | ||
i2c_master_transfer_callback_t | callback, | ||
void * | userData | ||
) |
The creation of a handle is for use with the non-blocking APIs. Once a handle is created, there is not a corresponding destroy handle. If the user wants to terminate a transfer, the I2C_MasterTransferAbort() API shall be called.
base | The I2C peripheral base address. | |
[out] | handle | Pointer to the I2C master driver handle. |
callback | User provided pointer to the asynchronous callback function. | |
userData | User provided pointer to the application callback data. |
status_t I2C_MasterTransferNonBlocking | ( | I2C_Type * | base, |
i2c_master_handle_t * | handle, | ||
i2c_master_transfer_t * | xfer | ||
) |
base | The I2C peripheral base address. |
handle | Pointer to the I2C master driver handle. |
xfer | The pointer to the transfer descriptor. |
kStatus_Success | The transaction was started successfully. |
kStatus_I2C_Busy | Either another master is currently utilizing the bus, or a non-blocking transaction is already in progress. |
status_t I2C_MasterTransferGetCount | ( | I2C_Type * | base, |
i2c_master_handle_t * | handle, | ||
size_t * | count | ||
) |
base | The I2C peripheral base address. | |
handle | Pointer to the I2C master driver handle. | |
[out] | count | Number of bytes transferred so far by the non-blocking transaction. |
kStatus_Success | |
kStatus_I2C_Busy |
status_t I2C_MasterTransferAbort | ( | I2C_Type * | base, |
i2c_master_handle_t * | handle | ||
) |
base | The I2C peripheral base address. |
handle | Pointer to the I2C master driver handle. |
kStatus_Success | A transaction was successfully aborted. |
kStatus_I2C_Timeout | Timeout during polling for flags. |
void I2C_MasterTransferHandleIRQ | ( | I2C_Type * | base, |
i2c_master_handle_t * | handle | ||
) |
base | The I2C peripheral base address. |
handle | Pointer to the I2C master driver handle. |