nRF5 SDK v15.0.0
Modules | Data Structures | Macros | Typedefs | Functions
TWI transaction manager

Module for scheduling TWI transactions. More...

Modules

 TWI transaction manager configuration
 

Data Structures

struct  nrf_twi_mngr_transfer_t
 TWI transfer descriptor. More...
 
struct  nrf_twi_mngr_transaction_t
 TWI transaction descriptor. More...
 
struct  nrf_twi_mngr_cb_t
 TWI instance control block. More...
 
struct  nrf_twi_mngr_t
 TWI transaction manager instance. More...
 

Macros

#define NRF_TWI_MNGR_BUFFERS_IN_RAM   defined(TWIM_PRESENT)
 Macro checking if buffers should be stored in RAM.
 
#define NRF_TWI_MNGR_BUFFER_LOC_IND   const
 Modifier used in array declaration for TWI Manager. More...
 
#define NRF_TWI_MNGR_NO_STOP   0x01
 Flag indicating that a given transfer should not be ended with a stop condition. More...
 
#define NRF_TWI_MNGR_WRITE(address, p_data, length, flags)   NRF_TWI_MNGR_TRANSFER(NRF_TWI_MNGR_WRITE_OP(address), p_data, length, flags)
 Macro for creating a write transfer. More...
 
#define NRF_TWI_MNGR_READ(address, p_data, length, flags)   NRF_TWI_MNGR_TRANSFER(NRF_TWI_MNGR_READ_OP(address), p_data, length, flags)
 Macro for creating a read transfer. More...
 
#define NRF_TWI_MNGR_TRANSFER(_operation, _p_data, _length, _flags)
 Helper macro, should not be used directly. More...
 
#define NRF_TWI_MNGR_WRITE_OP(address)   (((address) << 1) | 0)
 Helper macro, should not be used directly.
 
#define NRF_TWI_MNGR_READ_OP(address)   (((address) << 1) | 1)
 Helper macro, should not be used directly.
 
#define NRF_TWI_MNGR_IS_READ_OP(operation)   ((operation) & 1)
 Helper macro, should not be used directly.
 
#define NRF_TWI_MNGR_OP_ADDRESS(operation)   ((operation) >> 1)
 Helper macro, should not be used directly.
 
#define NRF_TWI_MNGR_DEF(_nrf_twi_mngr_name, _queue_size, _twi_idx)
 Macro that simplifies defining a TWI transaction manager instance. More...
 

Typedefs

typedef void(* nrf_twi_mngr_callback_t )(ret_code_t result, void *p_user_data)
 TWI transaction callback prototype. More...
 

Functions

ret_code_t nrf_twi_mngr_init (nrf_twi_mngr_t const *p_nrf_twi_mngr, nrf_drv_twi_config_t const *p_default_twi_config)
 Function for initializing a TWI transaction manager instance. More...
 
void nrf_twi_mngr_uninit (nrf_twi_mngr_t const *p_nrf_twi_mngr)
 Function for uninitializing a TWI transaction manager instance. More...
 
ret_code_t nrf_twi_mngr_schedule (nrf_twi_mngr_t const *p_nrf_twi_mngr, nrf_twi_mngr_transaction_t const *p_transaction)
 Function for scheduling a TWI transaction. More...
 
ret_code_t nrf_twi_mngr_perform (nrf_twi_mngr_t const *p_nrf_twi_mngr, nrf_drv_twi_config_t const *p_config, nrf_twi_mngr_transfer_t const *p_transfers, uint8_t number_of_transfers, void(*user_function)(void))
 Function for scheduling a transaction and waiting until it is finished. More...
 
__STATIC_INLINE bool nrf_twi_mngr_is_idle (nrf_twi_mngr_t const *p_nrf_twi_mngr)
 Function for getting the current state of a TWI transaction manager instance. More...
 

Detailed Description

Module for scheduling TWI transactions.

Macro Definition Documentation

#define NRF_TWI_MNGR_BUFFER_LOC_IND   const

Modifier used in array declaration for TWI Manager.

Note
For TWI peripheral array can be const, for TWIM array has to be located in RAM.
#define NRF_TWI_MNGR_DEF (   _nrf_twi_mngr_name,
  _queue_size,
  _twi_idx 
)
Value:
_nrf_twi_mngr_name##_queue, \
(_queue_size), \
static nrf_twi_mngr_cb_t CONCAT_2(_nrf_twi_mngr_name, _cb); \
static const nrf_twi_mngr_t _nrf_twi_mngr_name = \
{ \
.p_nrf_twi_mngr_cb = &CONCAT_2(_nrf_twi_mngr_name, _cb), \
.p_queue = &_nrf_twi_mngr_name##_queue, \
.twi = NRF_DRV_TWI_INSTANCE(_twi_idx) \
}

Macro that simplifies defining a TWI transaction manager instance.

This macro allocates a static buffer for the transaction queue. Therefore, it should be used in only one place in the code for a given instance.

Note
The queue size is the maximum number of pending transactions not counting the one that is currently realized. This means that for an empty queue with size of, for example, 4 elements, it is possible to schedule up to 5 transactions.
Parameters
[in]_nrf_twi_mngr_nameName of instance to be created.
[in]_queue_sizeSize of the transaction queue (maximum number of pending transactions).
[in]_twi_idxIndex of hardware TWI instance to be used.
#define NRF_TWI_MNGR_NO_STOP   0x01

Flag indicating that a given transfer should not be ended with a stop condition.

Use this flag when a stop condition is undesirable between two transfers, for example, when the first transfer is a write that sets an address in the slave device and the second one is a read that fetches certain data using this address. In this case, the second transfer should follow directly after the first transfer, with a repeated start condition instead of a stop and then a new start condition.

#define NRF_TWI_MNGR_READ (   address,
  p_data,
  length,
  flags 
)    NRF_TWI_MNGR_TRANSFER(NRF_TWI_MNGR_READ_OP(address), p_data, length, flags)

Macro for creating a read transfer.

Parameters
addressSlave address.
[in]p_dataPointer to the buffer where received data should be placed.
lengthNumber of bytes to transfer.
flagsTransfer flags (see NRF_TWI_MNGR_NO_STOP).
#define NRF_TWI_MNGR_TRANSFER (   _operation,
  _p_data,
  _length,
  _flags 
)
Value:
{ \
.p_data = (uint8_t *)(_p_data), \
.length = _length, \
.operation = _operation, \
.flags = _flags \
}

Helper macro, should not be used directly.

#define NRF_TWI_MNGR_WRITE (   address,
  p_data,
  length,
  flags 
)    NRF_TWI_MNGR_TRANSFER(NRF_TWI_MNGR_WRITE_OP(address), p_data, length, flags)

Macro for creating a write transfer.

Parameters
[in]addressSlave address.
[in]p_dataPointer to the data to be sent.
[in]lengthNumber of bytes to transfer.
[in]flagsTransfer flags (see NRF_TWI_MNGR_NO_STOP).

Typedef Documentation

typedef void(* nrf_twi_mngr_callback_t)(ret_code_t result, void *p_user_data)

TWI transaction callback prototype.

Parameters
resultResult of operation (NRF_SUCCESS on success, otherwise a relevant error code).
[in]p_user_dataPointer to user data defined in transaction descriptor.

Function Documentation

ret_code_t nrf_twi_mngr_init ( nrf_twi_mngr_t const *  p_nrf_twi_mngr,
nrf_drv_twi_config_t const *  p_default_twi_config 
)

Function for initializing a TWI transaction manager instance.

Parameters
[in]p_nrf_twi_mngrPointer to the instance to be initialized.
[in]p_default_twi_configPointer to the TWI master driver configuration. This configuration will be used whenever the scheduled transaction will have p_twi_configuration set to NULL value.
Returns
Values returned by the nrf_drv_twi_init function.
__STATIC_INLINE bool nrf_twi_mngr_is_idle ( nrf_twi_mngr_t const *  p_nrf_twi_mngr)

Function for getting the current state of a TWI transaction manager instance.

Parameters
[in]p_nrf_twi_mngrPointer to the TWI transaction manager instance.
Return values
trueIf all scheduled transactions have been finished.
falseOtherwise.
ret_code_t nrf_twi_mngr_perform ( nrf_twi_mngr_t const *  p_nrf_twi_mngr,
nrf_drv_twi_config_t const *  p_config,
nrf_twi_mngr_transfer_t const *  p_transfers,
uint8_t  number_of_transfers,
void(*)(void)  user_function 
)

Function for scheduling a transaction and waiting until it is finished.

This function schedules a transaction that consists of one or more transfers and waits until it is finished.

Parameters
[in]p_nrf_twi_mngrPointer to the TWI transaction manager instance.
[in]p_configRequired TWI configuration.
[in]p_transfersPointer to an array of transfers to be performed.
number_of_transfersNumber of transfers to be performed.
user_functionUser-specified function to be called while waiting. NULL if such functionality is not needed.
Return values
NRF_SUCCESSIf the transfers have been successfully realized.
NRF_ERROR_BUSYIf some transfers are already being performed.
-Other error codes mean that the transaction has ended with the error that is specified in the error code.
ret_code_t nrf_twi_mngr_schedule ( nrf_twi_mngr_t const *  p_nrf_twi_mngr,
nrf_twi_mngr_transaction_t const *  p_transaction 
)

Function for scheduling a TWI transaction.

The transaction is enqueued and started as soon as the TWI bus is available, thus when all previously scheduled transactions have been finished (possibly immediately).

Note
If nrf_twi_mngr_transaction_t::p_required_twi_cfg is set to a non-NULL value the module will compare it with nrf_twi_mngr_cb_t::p_current_configuration and reinitialize hardware TWI instance with new parameters if any differences are found. If nrf_twi_mngr_transaction_t::p_required_twi_cfg is set to NULL then it will treat it as it would be set to nrf_twi_mngr_cb_t::default_configuration.
Parameters
[in]p_nrf_twi_mngrPointer to the TWI transaction manager instance.
[in]p_transactionPointer to the descriptor of the transaction to be scheduled.
Return values
NRF_SUCCESSIf the transaction has been successfully scheduled.
NRF_ERROR_NO_MEMIf the queue is full (Only if queue in NRF_QUEUE_MODE_NO_OVERFLOW).
void nrf_twi_mngr_uninit ( nrf_twi_mngr_t const *  p_nrf_twi_mngr)

Function for uninitializing a TWI transaction manager instance.

Parameters
[in]p_nrf_twi_mngrPointer to the instance to be uninitialized.

Documentation feedback | Developer Zone | Subscribe | Updated