control
FreeRTOS peripheral control functions for the TWI peripheral
Modules | |
| Related Project(s) | |
| In this section you can find all the projects related to the FreeRTOS TWI peripheral. | |
Macros | |
| #define | freertos_twi_write_packet(p_twi, p_packet, block_time_ticks) freertos_twi_write_packet_async((p_twi), (p_packet), (block_time_ticks), (NULL)) |
| Initiate a multi-byte write operation on an TWI peripheral. More... | |
Typedefs | |
| typedef void * | freertos_twi_if |
| Type returned from a call to freertos_twi_master_init(), and then used to reference a TWI port in calls to FreeRTOS peripheral control functions. More... | |
Functions | |
| freertos_twi_if | freertos_twi_master_init (Twi *p_twi, const freertos_peripheral_options_t *const freertos_driver_parameters) |
| Initializes the FreeRTOS ASF TWI (I2C) master driver for the specified TWI port. More... | |
| status_code_t | freertos_twi_read_packet_async (freertos_twi_if p_twi, twi_packet_t *p_packet, portTickType block_time_ticks, xSemaphoreHandle notification_semaphore) |
| Initiate a completely asynchronous multi-byte read operation on an TWI peripheral. More... | |
| status_code_t | freertos_twi_write_packet_async (freertos_twi_if p_twi, twi_packet_t *p_packet, portTickType block_time_ticks, xSemaphoreHandle notification_semaphore) |
| Initiate a completely asynchronous multi-byte write operation on a TWI peripheral. More... | |
| #define freertos_twi_write_packet | ( | p_twi, | |
| p_packet, | |||
| block_time_ticks | |||
| ) | freertos_twi_write_packet_async((p_twi), (p_packet), (block_time_ticks), (NULL)) |
Initiate a multi-byte write operation on an TWI peripheral.
freertos_twi_write_packet() is an ASF specific FreeRTOS driver function. It configures the TWI peripheral DMA controller (PDC) to transmit data on the TWI port, then waits until the transmission is complete. Other RTOS tasks execute while the transmission is in progress.
freertos_twi_write_packet_async() is a version that does not wait for the transmission to complete before returning.
The FreeRTOS ASF TWI driver is initialized using a call to freertos_twi_master_init(). The freertos_driver_parameters.options_flags parameter passed into the initialization function defines the driver behavior. freertos_twi_write_packet() can only be used if the freertos_driver_parameters.options_flags parameter passed to the initialization function had the WAIT_TX_COMPLETE bit set.
Readers are recommended to also reference the application note and examples that accompany the FreeRTOS ASF drivers.
The FreeRTOS ASF driver both installs and handles the TWI PDC interrupts. Users do not need to concern themselves with interrupt handling, and must not install their own interrupt handler.
| p_twi | The handle to the TWI port returned by the freertos_twi_master_init() call used to initialise the port. |
| p_packet | Structure that defines the TWI transfer parameters, such as the I2C chip being addressed, the source data location, and the number of bytes to transmit. twi_packet_t is a standard ASF type (it is not FreeRTOS specific). |
| block_time_ticks | The FreeRTOS ASF TWI driver is initialized using a call to freertos_twi_master_init(). The freertos_driver_parameters.options_flags parameter passed to the initialization function defines the driver behavior. If freertos_driver_parameters.options_flags had the USE_TX_ACCESS_SEM bit set, then the driver will only write to the TWI peripheral if it has first gained exclusive access to it. block_time_ticks specifies the maximum amount of time the driver will wait to get exclusive access before aborting the write operation. Other tasks will execute during any waiting time. block_time_ticks is specified in RTOS tick periods. To specify a block time in milliseconds, divide the milliseconds value by portTICK_RATE_MS, and pass the result in block_time_ticks. portTICK_RATE_MS is defined by FreeRTOS. |
Type returned from a call to freertos_twi_master_init(), and then used to reference a TWI port in calls to FreeRTOS peripheral control functions.
| freertos_twi_if freertos_twi_master_init | ( | Twi * | p_twi, |
| const freertos_peripheral_options_t *const | freertos_driver_parameters | ||
| ) |
Initializes the FreeRTOS ASF TWI (I2C) master driver for the specified TWI port.
freertos_twi_master_init() is an ASF specific FreeRTOS driver function. It must be called before any other ASF specific FreeRTOS driver functions attempt to access the same TWI port.
If freertos_driver_parameters->operation_mode equals TWI_I2C_MASTER then freertos_twi_master_init() will configure the TWI port for master mode operation and enable the peripheral. If freertos_driver_parameters->operation_mode equals any other value then freertos_twi_master_init() will not take any action.
Other ASF TWI functions can be called after freertos_twi_master_init() has completed successfully.
The FreeRTOS ASF driver both installs and handles the TWI PDC interrupts. Users do not need to concern themselves with interrupt handling, and must not install their own interrupt handler.
This driver is provided with an application note, and an example project that demonstrates the use of this function.
| p_twi | The twi peripheral being initialized. |
| freertos_driver_parameters | Defines the driver behavior. See the freertos_peripheral_options_t documentation, and the application note that accompanies the ASF specific FreeRTOS functions. |
References check_requested_operating_mode(), configASSERT, configure_interrupt_controller(), create_peripheral_control_semaphores(), get_pdc_peripheral_details(), IER_ERROR_INTERRUPTS, freertos_peripheral_options::interrupt_priority, MASK_ALL_INTERRUPTS, NULL, freertos_peripheral_options::operation_mode, freertos_peripheral_options::options_flags, pdc_disable_transfer(), pmc_enable_periph_clk(), twi_disable_interrupt(), twi_enable_interrupt(), twi_enable_master_mode(), TWI_I2C_MASTER, and twi_reset().
| status_code_t freertos_twi_read_packet_async | ( | freertos_twi_if | p_twi, |
| twi_packet_t * | p_packet, | ||
| portTickType | block_time_ticks, | ||
| xSemaphoreHandle | notification_semaphore | ||
| ) |
Initiate a completely asynchronous multi-byte read operation on an TWI peripheral.
freertos_twi_read_packet_async() is an ASF specific FreeRTOS driver function. It configures the TWI peripheral DMA controller (PDC) to read data from the TWI port, then returns. freertos_twi_read_packet_async() does not wait for the reception to complete before returning.
The FreeRTOS ASF TWI driver is initialized using a call to freertos_twi_master_init(). The freertos_driver_parameters.options_flags parameter passed into the initialization function defines the driver behavior. freertos_twi_read_packet_async() can only be used if the freertos_driver_parameters.options_flags parameter passed to the initialization function had the WAIT_RX_COMPLETE bit clear. The function can also only be used if the length of the packet is more that two. If less, it will block until the transfer is done.
freertos_twi_read_packet_async() is an advanced function and readers are recommended to also reference the application note and examples that accompany the FreeRTOS ASF drivers. freertos_twi_read_packet() is a version that does not exit until the PDC transfer is complete, but still allows other RTOS tasks to execute while the transmission is in progress.
The FreeRTOS ASF driver both installs and handles the TWI PDC interrupts. Users do not need to concern themselves with interrupt handling, and must not install their own interrupt handler.
| p_twi | The handle to the TWI port returned by the freertos_twi_master_init() call used to initialise the port. |
| p_packet | Structure that defines the TWI transfer parameters, such as the I2C chip being addressed, the destination for the data being read, and the number of bytes to read. twi_packet_t is a standard ASF type (it is not FreeRTOS specific). |
| block_time_ticks | The FreeRTOS ASF TWI driver is initialized using a call to freertos_twi_master_init(). The freertos_driver_parameters.options_flags parameter passed to the initialization function defines the driver behavior. If freertos_driver_parameters.options_flags had the USE_RX_ACCESS_MUTEX bit set, then the driver will only read from the TWI peripheral if it has first gained exclusive access to it. block_time_ticks specifies the maximum amount of time the driver will wait to get exclusive access before aborting the read operation. Other tasks will execute during any waiting time. block_time_ticks is specified in RTOS tick periods. To specify a block time in milliseconds, divide the milliseconds value by portTICK_RATE_MS, and pass the result in block_time_ticks. portTICK_RATE_MS is defined by FreeRTOS. |
| notification_semaphore | The RTOS task that calls the receive function exits the receive function as soon as the reception starts. The data being received by the PDC cannot normally be processed until after the reception has completed. The PDC interrupt (handled internally by the FreeRTOS ASF driver) 'gives' the semaphore when the PDC transfer completes. The notification_semaphore therefore provides a mechanism for the calling task to know when the PDC has read the requested number of bytes. The calling task can call standard FreeRTOS functions to block on the semaphore until the PDC interrupt occurs. Other RTOS tasks will execute while the the calling task is in the Blocked state. The semaphore must be created using the FreeRTOS vSemaphoreCreateBinary() API function before it is used as a parameter. |
References twi_packet::addr, twi_packet::addr_length, buffer, twi_packet::buffer, twi_module::buffer, twi_packet::chip, cnt, ERR_BUSY, ERR_INVALID_ARG, ERR_TIMEOUT, freertos_obtain_peripheral_access_semphore(), freertos_optionally_wait_transfer_completion(), freertos_start_pdc_rx, get_pdc_peripheral_details(), IER_ERROR_INTERRUPTS, twi_packet::length, twi_module::length, freertos_peripheral_parameters::pdc_base_address, status, STATUS_OK, twi_disable_interrupt(), twi_enable_interrupt(), twi_read_byte(), TWI_TIMEOUT_COUNTER, twis, and xSemaphoreGive.
| status_code_t freertos_twi_write_packet_async | ( | freertos_twi_if | p_twi, |
| twi_packet_t * | p_packet, | ||
| portTickType | block_time_ticks, | ||
| xSemaphoreHandle | notification_semaphore | ||
| ) |
Initiate a completely asynchronous multi-byte write operation on a TWI peripheral.
freertos_twi_write_packet_async() is an ASF specific FreeRTOS driver function. It configures the TWI peripheral DMA controller (PDC) to transmit data on the TWI port, then returns. freertos_twi_write_packet_async() does not wait for the transmission to complete before returning.
The FreeRTOS TWI driver is initialized using a call to freertos_twi_master_init(). The freertos_driver_parameters.options_flags parameter passed into the initialization function defines the driver behavior. freertos_twi_write_packet_async() can only be used if the freertos_driver_parameters.options_flags parameter passed to the initialization function had the WAIT_TX_COMPLETE bit clear. It can also only be used if packet length is more than 1.
freertos_twi_write_packet_async() is an advanced function and readers are recommended to also reference the application note and examples that accompany the FreeRTOS ASF drivers. freertos_twi_write_packet() is a version that does not exit until the PDC transfer is complete, but still allows other RTOS tasks to execute while the transmission is in progress.
The FreeRTOS ASF driver both installs and handles the TWI PDC interrupts. Users do not need to concern themselves with interrupt handling, and must not install their own interrupt handler.
| p_twi | The handle to the TWI peripheral returned by the freertos_twi_master_init() call used to initialise the peripheral. |
| p_packet | Structure that defines the TWI transfer parameters, such as the I2C chip being addressed, the source data location, and the number of bytes to transmit. twi_packet_t is a standard ASF type (it is not FreeRTOS specific). |
| block_time_ticks | The FreeRTOS ASF TWI driver is initialized using a call to freertos_twi_master_init(). The freertos_driver_parameters.options_flags parameter passed to the initialization function defines the driver behavior. If freertos_driver_parameters.options_flags had the USE_TX_ACCESS_SEM bit set, then the driver will only write to the TWI peripheral if it has first gained exclusive access to it. block_time_ticks specifies the maximum amount of time the driver will wait to get exclusive access before aborting the write operation. Other tasks will execute during any waiting time. block_time_ticks is specified in RTOS tick periods. To specify a block time in milliseconds, divide the milliseconds value by portTICK_RATE_MS, and pass the result in block_time_ticks. portTICK_RATE_MS is defined by FreeRTOS. |
| notification_semaphore | The RTOS task that calls the transmit function exits the transmit function as soon as the transmission starts. The data being transmitted by the PDC must not be modified until after the transmission has completed. The PDC interrupt (handled internally by the FreeRTOS ASF driver) 'gives' the semaphore when the PDC transfer completes. The notification_semaphore therefore provides a mechanism for the calling task to know when the PDC has finished accessing the data. The calling task can call standard FreeRTOS functions to block on the semaphore until the PDC interrupt occurs. Other RTOS tasks will execute while the the calling task is in the Blocked state. The semaphore must be created using the FreeRTOS vSemaphoreCreateBinary() API function before it is used as a parameter. |
References twi_packet::addr, twi_packet::addr_length, twi_packet::buffer, twi_module::buffer, twi_packet::chip, ERR_BUSY, ERR_INVALID_ARG, ERR_TIMEOUT, freertos_obtain_peripheral_access_semphore(), freertos_optionally_wait_transfer_completion(), freertos_start_pdc_tx, get_pdc_peripheral_details(), IER_ERROR_INTERRUPTS, twi_packet::length, twi_module::length, freertos_peripheral_parameters::pdc_base_address, status, STATUS_OK, twi_disable_interrupt(), twi_enable_interrupt(), TWI_TIMEOUT_COUNTER, twis, and xSemaphoreGive.
1.8.5