FreeRTOS USART peripheral

control

FreeRTOS peripheral control functions for the USART peripheral

Modules
	Related Project(s)
	In this section you can find all the projects related to the FreeRTOS USART peripheral.

Macros
#define	freertos_usart_write_packet(p_usart, data, len, block_time_ticks)   freertos_usart_write_packet_async((p_usart), (data), (len), (block_time_ticks), (NULL))
	Initiate a multi-byte write operation on an USART peripheral. More...

Typedefs
typedef void *	freertos_usart_if
	Type returned from a call to freertos_usart_serial_init(), and then used to reference a USART port in calls to FreeRTOS peripheral control functions. More...

Functions
freertos_usart_if	freertos_usart_serial_init (Usart *p_usart, const sam_usart_opt_t *const uart_parameters, const freertos_peripheral_options_t *const freertos_driver_parameters)
	Initializes the FreeRTOS ASF USART driver for the specified USART port. More...
uint32_t	freertos_usart_serial_read_packet (freertos_usart_if p_usart, uint8_t *data, uint32_t len, portTickType block_time_ticks)
	Initiate a completely multi-byte read operation on a USART peripheral. More...
status_code_t	freertos_usart_write_packet_async (freertos_usart_if p_usart, const uint8_t *data, size_t len, portTickType block_time_ticks, xSemaphoreHandle notification_semaphore)
	Initiate a completely asynchronous multi-byte write operation on a USART peripheral. More...

#define freertos_usart_write_packet	(		p_usart,
			data,
			len,
			block_time_ticks
	)		freertos_usart_write_packet_async((p_usart), (data), (len), (block_time_ticks), (NULL))

Initiate a multi-byte write operation on an USART peripheral.

freertos_usart_write_packet() is an ASF specific FreeRTOS driver function. It configures the USART peripheral DMA controller (PDC) to transmit data on the USART port, then waits until the transmission is complete. Other RTOS tasks execute while the transmission is in progress.

freertos_usart_write_packet_async() is a version that does not wait for the transmission to complete before returning.

The FreeRTOS ASF USART driver is initialized using a call to freertos_usart_serial_init(). The freertos_driver_parameters.options_flags parameter passed into the initialization function defines the driver behavior. freertos_usart_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 USART PDC interrupts. Users do not need to concern themselves with interrupt handling, and must not install their own interrupt handler.

Parameters

p_usart	The handle to the USART port returned by the freertos_usart_serial_init() call used to initialise the port.
data	A pointer to the data to be transmitted.
len	The number of bytes to transmit.
block_time_ticks	The FreeRTOS ASF USART driver is initialized using a call to freertos_usart_serial_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 USART 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.

Returns

ERR_INVALID_ARG is returned if an input parameter is invalid. ERR_TIMEOUT is returned if block_time_ticks passed before exclusive access to the USART peripheral could be obtained. STATUS_OK is returned if the PDC was successfully configured to perform the USART write operation.

freertos_usart_if

Type returned from a call to freertos_usart_serial_init(), and then used to reference a USART port in calls to FreeRTOS peripheral control functions.

freertos_usart_if freertos_usart_serial_init	(	Usart *	p_usart,
		const sam_usart_opt_t *const	uart_parameters,
		const freertos_peripheral_options_t *const	freertos_driver_parameters
	)

Initializes the FreeRTOS ASF USART driver for the specified USART port.

freertos_usart_serial_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 USART port.

If freertos_driver_parameters->operation_mode equals USART_RS232 then freertos_usart_serial_init() will configure the USART port for standard RS232 operation. If freertos_driver_parameters->operation_mode equals any other value then freertos_usart_serial_init() will not take any action.

Other ASF USART functions can be called after freertos_usart_serial_init() has completed successfully.

The FreeRTOS ASF driver both installs and handles the USART 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.

Parameters

p_usart	The USART peripheral being initialized.
uart_parameters	Structure that defines the USART bus and transfer parameters, such the baud rate and the number of data bits. sam_usart_opt_t is a standard ASF type (it is not FreeRTOS specific).
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.

Returns

If the initialization completes successfully then a handle that can be used with FreeRTOS USART read and write functions is returned. If the initialisation fails then NULL is returned.

References sam_usart_opt_t::baudrate, BITS_PER_5_MS, 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, freertos_pdc_rx_control::next_byte_to_read, NULL, freertos_peripheral_options::operation_mode, freertos_peripheral_options::options_flags, freertos_pdc_rx_control::past_rx_buffer_end_address, pdc_disable_transfer(), pdc_enable_transfer(), pdc_rx_init(), pmc_enable_periph_clk(), freertos_peripheral_options::receive_buffer, freertos_peripheral_options::receive_buffer_size, freertos_pdc_rx_control::rx_access_mutex, freertos_pdc_rx_control::rx_buffer_start_address, freertos_pdc_rx_control::rx_event_semaphore, RX_NOT_USED, freertos_pdc_rx_control::rx_pdc_parameters, sysclk_get_cpu_hz(), pdc_packet::ul_addr, pdc_packet::ul_size, usart_disable_interrupt(), usart_disable_rx(), usart_disable_tx(), usart_enable_interrupt(), usart_enable_rx(), usart_enable_tx(), usart_init_rs232(), USART_RS232, usart_set_rx_timeout(), usart_start_rx_timeout(), USE_RX_ACCESS_MUTEX, xSemaphoreCreateCounting, and xSemaphoreCreateMutex.

Referenced by create_usart_tasks().

uint32_t freertos_usart_serial_read_packet	(	freertos_usart_if	p_usart,
		uint8_t *	data,
		uint32_t	len,
		portTickType	block_time_ticks
	)

Initiate a completely multi-byte read operation on a USART peripheral.

The FreeRTOS ASF USART driver uses the PDC to transfer data from a peripheral to a circular buffer. Reception happens in the background, while the microcontroller is executing application code.* freertos_usart_read_packet() copies bytes from the DMA buffer into the buffer passed as a freertos_usart_read_packet() parameter.

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 USART PDC interrupts. Users do not need to concern themselves with interrupt handling, and must not install their own interrupt handler.

Parameters

p_usart	The handle to the USART port returned by the freertos_usart_serial_init() call used to initialise the port.
data	A pointer to the buffer into which received data is to be copied.
len	The number of bytes to copy.
block_time_ticks	Defines the maximum combined time the function will wait to get exclusive access to the peripheral and receive the requested number of bytes. Other tasks will execute during any waiting time.

The FreeRTOS ASF USART driver is initialized using a call to freertos_usart_serial_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 USART buffer 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.

If the number of bytes available is less than the number requested then freertos_usart_serial_read_packet() will wait for more bytes to become available. block_time_ticks specifies the maximum amount of time the driver will wait before returning fewer bytes than were requested.

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.

Returns

The number of bytes that were copied into data. This will be less than the requested number of bytes if a time out occurred.

References configASSERT, configure_rx_dma(), data_removed, freertos_copy_bytes_from_pdc_circular_buffer(), get_pdc_peripheral_details(), NULL, pdFALSE, pdTRUE, RX_NOT_USED, taskENTER_CRITICAL, taskEXIT_CRITICAL, vTaskSetTimeOutState(), xSemaphoreGive, xSemaphoreTake, and xTaskCheckForTimeOut().

Referenced by run_usart_test().

status_code_t freertos_usart_write_packet_async	(	freertos_usart_if	p_usart,
		const uint8_t *	data,
		size_t	len,
		portTickType	block_time_ticks,
		xSemaphoreHandle	notification_semaphore
	)

Initiate a completely asynchronous multi-byte write operation on a USART peripheral.

freertos_usart_write_packet_async() is an ASF specific FreeRTOS driver function. It configures the USART peripheral DMA controller (PDC) to transmit data on the USART port, then returns. freertos_usart_write_packet_async() does not wait for the transmission to complete before returning.

The FreeRTOS USART driver is initialized using a call to freertos_usart_serial_init(). The freertos_driver_parameters.options_flags parameter passed into the initialization function defines the driver behavior. freertos_usart_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.

freertos_usart_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_usart_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 USART PDC interrupts. Users do not need to concern themselves with interrupt handling, and must not install their own interrupt handler.

Parameters

p_usart	The handle to the USART peripheral returned by the freertos_usart_serial_init() call used to initialise the peripheral.
data	A pointer to the data to be transmitted.
len	The number of bytes to transmit.
block_time_ticks	The FreeRTOS ASF USART driver is initialized using a call to freertos_usart_serial_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 USART 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.

Returns

ERR_INVALID_ARG is returned if an input parameter is invalid. ERR_TIMEOUT is returned if block_time_ticks passed before exclusive access to the USART peripheral could be obtained. STATUS_OK is returned if the PDC was successfully configured to perform the USART write operation.

References ERR_INVALID_ARG, freertos_obtain_peripheral_access_semphore(), freertos_optionally_wait_transfer_completion(), freertos_start_pdc_tx, get_pdc_peripheral_details(), STATUS_OK, and usart_enable_interrupt().

Referenced by usart_echo_tx_task().