Intel® Quark™ Microcontroller Software Interface
1.4.0
Intel® Quark™ Microcontroller BSP
|
I2C. More...
Data Structures | |
struct | qm_i2c_config_t |
I2C configuration type. More... | |
struct | qm_i2c_transfer_t |
I2C transfer type. More... | |
Functions | |
int | qm_i2c_set_config (const qm_i2c_t i2c, const qm_i2c_config_t *const cfg) |
Set I2C configuration. More... | |
int | qm_i2c_set_speed (const qm_i2c_t i2c, const qm_i2c_speed_t speed, const uint16_t lo_cnt, const uint16_t hi_cnt) |
Set I2C speed. More... | |
int | qm_i2c_get_status (const qm_i2c_t i2c, qm_i2c_status_t *const status) |
Retrieve I2C bus status. More... | |
int | qm_i2c_master_write (const qm_i2c_t i2c, const uint16_t slave_addr, const uint8_t *const data, uint32_t len, const bool stop, qm_i2c_status_t *const status) |
Master write on I2C. More... | |
int | qm_i2c_master_read (const qm_i2c_t i2c, const uint16_t slave_addr, uint8_t *const data, uint32_t len, const bool stop, qm_i2c_status_t *const status) |
Master read of I2C. More... | |
int | qm_i2c_master_irq_transfer (const qm_i2c_t i2c, const qm_i2c_transfer_t *const xfer, const uint16_t slave_addr) |
Interrupt based master transfer on I2C. More... | |
int | qm_i2c_slave_irq_transfer (const qm_i2c_t i2c, volatile const qm_i2c_transfer_t *const xfer) |
Interrupt based slave transfer on I2C. More... | |
int | qm_i2c_slave_irq_transfer_update (const qm_i2c_t i2c, volatile const qm_i2c_transfer_t *const xfer) |
I2C interrupt based slave transfer buffer update. More... | |
int | qm_i2c_irq_transfer_terminate (const qm_i2c_t i2c) |
Terminate I2C IRQ transfer. More... | |
int | qm_i2c_dma_channel_config (const qm_i2c_t i2c, const qm_dma_t dma_controller_id, const qm_dma_channel_id_t channel_id, const qm_dma_channel_direction_t direction) |
Configure a DMA channel with a specific transfer direction. More... | |
int | qm_i2c_master_dma_transfer (const qm_i2c_t i2c, qm_i2c_transfer_t *const xfer, const uint16_t slave_addr) |
Perform a DMA based master transfer on the I2C bus. More... | |
int | qm_i2c_slave_dma_transfer (const qm_i2c_t i2c, const qm_i2c_transfer_t *const xfer) |
Perform a DMA based slave transfer on the I2C bus. More... | |
int | qm_i2c_dma_transfer_terminate (const qm_i2c_t i2c) |
Terminate any DMA transfer going on on the controller. More... | |
int | qm_i2c_save_context (const qm_i2c_t i2c, qm_i2c_context_t *const ctx) |
Save I2C context. More... | |
int | qm_i2c_restore_context (const qm_i2c_t i2c, const qm_i2c_context_t *const ctx) |
Restore I2C context. More... | |
I2C.
enum qm_i2c_addr_t |
enum qm_i2c_mode_t |
enum qm_i2c_slave_stop_t |
enum qm_i2c_speed_t |
enum qm_i2c_status_t |
I2C status type.
int qm_i2c_dma_channel_config | ( | const qm_i2c_t | i2c, |
const qm_dma_t | dma_controller_id, | ||
const qm_dma_channel_id_t | channel_id, | ||
const qm_dma_channel_direction_t | direction | ||
) |
Configure a DMA channel with a specific transfer direction.
Configure a DMA channel with a specific transfer direction. The user is responsible for managing the allocation of the pool of DMA channels provided by each DMA core to the different peripheral drivers that require them. Note that a I2C controller cannot use different DMA cores to manage transfers in different directions.
This function configures DMA channel parameters that are unlikely to change between transfers, like transaction width, burst size, and handshake interface parameters. The user will likely only call this function once for the lifetime of an application unless the channel needs to be repurposed.
Note that qm_dma_init() must first be called before configuring a channel.
[in] | i2c | I2C controller identifier. |
[in] | dma_controller_id | DMA controller identifier. |
[in] | channel_id | DMA channel identifier. |
[in] | direction | DMA channel direction, either QM_DMA_MEMORY_TO_PERIPHERAL (TX transfer) or QM_DMA_PERIPHERAL_TO_MEMORY (RX transfer). |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 1490 of file qm_i2c.c.
References qm_dma_channel_config_t::callback_context, qm_dma_channel_config_t::channel_direction, qm_dma_channel_config_t::client_callback, qm_dma_channel_config_t::destination_burst_length, qm_dma_channel_config_t::destination_transfer_width, qm_dma_channel_config_t::handshake_interface, qm_dma_channel_config_t::handshake_polarity, QM_DMA_BURST_TRANS_LENGTH_4, QM_DMA_BURST_TRANS_LENGTH_8, QM_DMA_CHANNEL_NUM, qm_dma_channel_set_config(), QM_DMA_HANDSHAKE_POLARITY_HIGH, QM_DMA_MEMORY_TO_PERIPHERAL, QM_DMA_NUM, QM_DMA_PERIPHERAL_TO_MEMORY, QM_DMA_TRANS_WIDTH_8, QM_DMA_TYPE_SINGLE, qm_dma_channel_config_t::source_burst_length, qm_dma_channel_config_t::source_transfer_width, and qm_dma_channel_config_t::transfer_type.
int qm_i2c_dma_transfer_terminate | ( | const qm_i2c_t | i2c | ) |
Terminate any DMA transfer going on on the controller.
Calls the DMA driver to stop any ongoing DMA transfer and calls qm_i2c_irq_transfer_terminate.
[in] | i2c | Which I2C to terminate transfers from. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 1235 of file qm_i2c.c.
References qm_dma_transfer_terminate().
int qm_i2c_get_status | ( | const qm_i2c_t | i2c, |
qm_i2c_status_t *const | status | ||
) |
Retrieve I2C bus status.
[in] | i2c | Which I2C to read the status of. |
[out] | status | Current I2C status. This must not be NULL. |
The user may call this function before performing an I2C transfer in order to guarantee that the I2C interface is available.
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 903 of file qm_i2c.c.
References qm_i2c_reg_t::ic_status, qm_i2c_reg_t::ic_tx_abrt_source, QM_I2C_BUSY, and QM_I2C_IDLE.
Referenced by qm_i2c_master_read(), and qm_i2c_master_write().
int qm_i2c_irq_transfer_terminate | ( | const qm_i2c_t | i2c | ) |
Terminate I2C IRQ transfer.
Terminate the current IRQ or DMA transfer on the I2C bus. This will cause the user callback to be called with status QM_I2C_TX_ABRT_USER_ABRT.
[in] | i2c | I2C controller identifier. |
0 | on success. |
Negative | errno for possible error codes. |
int qm_i2c_master_dma_transfer | ( | const qm_i2c_t | i2c, |
qm_i2c_transfer_t *const | xfer, | ||
const uint16_t | slave_addr | ||
) |
Perform a DMA based master transfer on the I2C bus.
Perform a DMA based master transfer on the I2C bus. If the transfer is TX only, it will enable DMA operation for the controller and start the transfer.
If it's an RX only transfer, it will require 2 channels, one for writing the READ commands and another one for reading the bytes from the bus. Both DMA operations will start in parallel.
If this is a combined transaction, both TX and RX operations will be set up, but only TX will be started. On TX finish (callback), the TX channel will be used for writing the READ commands and the RX operation will start.
Note that qm_i2c_dma_channel_config() must first be called in order to configure all DMA channels needed for a transfer.
[in] | i2c | I2C controller identifier. |
[in] | xfer | Structure containing pre-allocated write and read data buffers and callback functions. This must not be NULL and must be kept valid until the transfer is complete. |
[in] | slave_addr | Address of slave to transfer data with. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 1542 of file qm_i2c.c.
References qm_dma_transfer_set_config(), qm_dma_transfer_start(), qm_i2c_transfer_t::rx, qm_i2c_transfer_t::rx_len, qm_i2c_transfer_t::stop, qm_i2c_transfer_t::tx, and qm_i2c_transfer_t::tx_len.
int qm_i2c_master_irq_transfer | ( | const qm_i2c_t | i2c, |
const qm_i2c_transfer_t *const | xfer, | ||
const uint16_t | slave_addr | ||
) |
Interrupt based master transfer on I2C.
Perform an interrupt based master transfer on the I2C bus. The function will replenish/empty TX/RX FIFOs on I2C empty/full interrupts.
[in] | i2c | Which I2C to transfer from. |
[in] | xfer | Transfer structure includes write / read buffers, length, user callback function and the callback context. The structure must not be NULL and must be kept valid until the transfer is complete. |
[in] | slave_addr | Address of slave to transfer data with. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 1073 of file qm_i2c.c.
References qm_i2c_reg_t::ic_intr_mask, qm_i2c_reg_t::ic_rx_tl, qm_i2c_reg_t::ic_tar, qm_i2c_reg_t::ic_tx_tl, and qm_i2c_transfer_t::rx_len.
int qm_i2c_master_read | ( | const qm_i2c_t | i2c, |
const uint16_t | slave_addr, | ||
uint8_t *const | data, | ||
uint32_t | len, | ||
const bool | stop, | ||
qm_i2c_status_t *const | status | ||
) |
Master read of I2C.
Perform a single byte master read from the I2C. This is a blocking call.
[in] | i2c | Which I2C to read from. |
[in] | slave_addr | Address of slave device to read from. |
[out] | data | Pre-allocated buffer to populate with data. This must not be NULL. |
[in] | len | Length of data to read from slave. |
[in] | stop | Generate a STOP condition at the end of rx. |
[out] | status | Get I2C status. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 999 of file qm_i2c.c.
References qm_i2c_reg_t::ic_clr_tx_abrt, qm_i2c_reg_t::ic_data_cmd, qm_i2c_reg_t::ic_raw_intr_stat, qm_i2c_reg_t::ic_status, qm_i2c_reg_t::ic_tar, qm_i2c_reg_t::ic_tx_abrt_source, and qm_i2c_get_status().
int qm_i2c_master_write | ( | const qm_i2c_t | i2c, |
const uint16_t | slave_addr, | ||
const uint8_t *const | data, | ||
uint32_t | len, | ||
const bool | stop, | ||
qm_i2c_status_t *const | status | ||
) |
Master write on I2C.
Perform a master write on the I2C bus. This is a blocking synchronous call.
[in] | i2c | Which I2C to write to. |
[in] | slave_addr | Address of slave to write to. |
[in] | data | Pre-allocated buffer of data to write. This must not be NULL. |
[in] | len | Length of data to write. |
[in] | stop | Generate a STOP condition at the end of tx. |
[out] | status | Get I2C status. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 924 of file qm_i2c.c.
References qm_i2c_reg_t::ic_clr_tx_abrt, qm_i2c_reg_t::ic_data_cmd, qm_i2c_reg_t::ic_status, qm_i2c_reg_t::ic_tar, qm_i2c_reg_t::ic_tx_abrt_source, and qm_i2c_get_status().
int qm_i2c_restore_context | ( | const qm_i2c_t | i2c, |
const qm_i2c_context_t *const | ctx | ||
) |
Restore I2C context.
Restore the configuration of the specified I2C peripheral after exiting sleep.
[in] | i2c | I2C port index. |
[in] | ctx | I2C context structure. This must not be NULL. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 1690 of file qm_i2c.c.
References qm_i2c_context_t::con, qm_i2c_context_t::enable, qm_i2c_context_t::fs_scl_hcnt, qm_i2c_context_t::fs_scl_lcnt, qm_i2c_context_t::fs_spklen, qm_i2c_reg_t::ic_con, qm_i2c_reg_t::ic_enable, qm_i2c_reg_t::ic_fs_scl_hcnt, qm_i2c_reg_t::ic_fs_scl_lcnt, qm_i2c_reg_t::ic_fs_spklen, qm_i2c_reg_t::ic_intr_mask, qm_i2c_context_t::ic_intr_mask, qm_i2c_reg_t::ic_rx_tl, qm_i2c_reg_t::ic_sar, qm_i2c_reg_t::ic_ss_scl_hcnt, qm_i2c_reg_t::ic_ss_scl_lcnt, qm_i2c_reg_t::ic_tx_tl, qm_i2c_context_t::sar, qm_i2c_context_t::ss_scl_hcnt, qm_i2c_context_t::ss_scl_lcnt, and qm_i2c_context_t::tx_tl.
int qm_i2c_save_context | ( | const qm_i2c_t | i2c, |
qm_i2c_context_t *const | ctx | ||
) |
Save I2C context.
Saves the configuration of the specified I2C peripheral before entering sleep. The slave operations need to be disabled before being able to save the context as otherwise we could be interrupted by an I2C transfer while saving registers.
[in] | i2c | I2C port index. |
[out] | ctx | I2C context structure. This must not be NULL. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 1668 of file qm_i2c.c.
References qm_i2c_context_t::con, qm_i2c_context_t::enable, qm_i2c_context_t::fs_scl_hcnt, qm_i2c_context_t::fs_scl_lcnt, qm_i2c_context_t::fs_spklen, qm_i2c_reg_t::ic_con, qm_i2c_reg_t::ic_enable, qm_i2c_reg_t::ic_fs_scl_hcnt, qm_i2c_reg_t::ic_fs_scl_lcnt, qm_i2c_reg_t::ic_fs_spklen, qm_i2c_reg_t::ic_intr_mask, qm_i2c_context_t::ic_intr_mask, qm_i2c_reg_t::ic_rx_tl, qm_i2c_reg_t::ic_sar, qm_i2c_reg_t::ic_ss_scl_hcnt, qm_i2c_reg_t::ic_ss_scl_lcnt, qm_i2c_reg_t::ic_tx_tl, qm_i2c_context_t::sar, qm_i2c_context_t::ss_scl_hcnt, qm_i2c_context_t::ss_scl_lcnt, and qm_i2c_context_t::tx_tl.
int qm_i2c_set_config | ( | const qm_i2c_t | i2c, |
const qm_i2c_config_t *const | cfg | ||
) |
Set I2C configuration.
[in] | i2c | Which I2C to set the configuration of. |
[out] | cfg | I2C configuration. This must not be NULL. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 749 of file qm_i2c.c.
References qm_i2c_config_t::address_mode, qm_i2c_reg_t::ic_con, qm_i2c_reg_t::ic_fs_scl_hcnt, qm_i2c_reg_t::ic_fs_scl_lcnt, qm_i2c_reg_t::ic_fs_spklen, qm_i2c_reg_t::ic_intr_mask, qm_i2c_reg_t::ic_sar, qm_i2c_reg_t::ic_ss_scl_hcnt, qm_i2c_reg_t::ic_ss_scl_lcnt, qm_i2c_config_t::mode, QM_I2C_MASTER, QM_I2C_SLAVE, QM_I2C_SLAVE_INTERRUPT_WHEN_ADDRESSED, QM_I2C_SPEED_FAST, QM_I2C_SPEED_FAST_PLUS, QM_I2C_SPEED_STD, qm_i2c_config_t::slave_addr, qm_i2c_config_t::speed, and qm_i2c_config_t::stop_detect_behaviour.
int qm_i2c_set_speed | ( | const qm_i2c_t | i2c, |
const qm_i2c_speed_t | speed, | ||
const uint16_t | lo_cnt, | ||
const uint16_t | hi_cnt | ||
) |
Set I2C speed.
Fine tune I2C clock speed. This will set the SCL low count and the SCL hi count cycles. To achieve any required speed.
[in] | i2c | I2C index. |
[in] | speed | Bus speed (Standard or Fast. Fast includes Fast+ mode). |
[in] | lo_cnt | SCL low count. |
[in] | hi_cnt | SCL high count. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 867 of file qm_i2c.c.
References qm_i2c_reg_t::ic_con, qm_i2c_reg_t::ic_fs_scl_hcnt, qm_i2c_reg_t::ic_fs_scl_lcnt, qm_i2c_reg_t::ic_fs_spklen, qm_i2c_reg_t::ic_ss_scl_hcnt, qm_i2c_reg_t::ic_ss_scl_lcnt, QM_I2C_SPEED_FAST, QM_I2C_SPEED_FAST_PLUS, and QM_I2C_SPEED_STD.
int qm_i2c_slave_dma_transfer | ( | const qm_i2c_t | i2c, |
const qm_i2c_transfer_t *const | xfer | ||
) |
Perform a DMA based slave transfer on the I2C bus.
Note that qm_i2c_dma_channel_config() must first be called in order to configure all DMA channels needed for a transfer.
[in] | i2c | I2C controller identifier. |
[in] | xfer | Structure containing pre-allocated write and read data buffers and callback functions. This pointer must be kept valid until the transfer is complete. |
0 | on success. |
Negative | errno for possible error codes. |
int qm_i2c_slave_irq_transfer | ( | const qm_i2c_t | i2c, |
volatile const qm_i2c_transfer_t *const | xfer | ||
) |
Interrupt based slave transfer on I2C.
Perform an interrupt based slave transfer on the I2C bus. The function will replenish/empty TX/RX FIFOs on I2C empty/full interrupts.
[in] | i2c | Which I2C to transfer from. |
[in] | xfer | Transfer structure includes write / read buffers, length, user callback function and the callback context. This must not be NULL. |
0 | on success. |
Negative | errno for possible error codes. |
Definition at line 1123 of file qm_i2c.c.
References qm_i2c_reg_t::ic_intr_mask, qm_i2c_reg_t::ic_rx_tl, and qm_i2c_reg_t::ic_tx_tl.
int qm_i2c_slave_irq_transfer_update | ( | const qm_i2c_t | i2c, |
volatile const qm_i2c_transfer_t *const | xfer | ||
) |
I2C interrupt based slave transfer buffer update.
Update transfer buffers location and size. The function will replenish/empty TX/RX FIFOs on I2C empty/full interrupts. This function must be called from callback function to update transfer buffers when requested by ISR.
It is strongly recommended to use this function for slave-based applications only, as slave controllers usually do not know how many frames an external master will send or request before starting the communication. Master controllers should not use this function as it will most likely corrupt the transaction.
[in] | i2c | Which I2C to transfer from. |
[in] | xfer | Transfer structure includes write / read buffers, length, user callback function and the callback context. This must not be NULL. |
0 | on success. |
Negative | errno for possible error codes. |