/******************************************************************************* | |
* (c) Copyright 2007-2017 Microsemi SoC Products Group. All rights reserved. | |
* | |
* This file contains the application programming interface for the CoreUARTapb | |
* bare metal driver. | |
* | |
* SVN $Revision: 9082 $ | |
* SVN $Date: 2017-04-28 11:51:36 +0530 (Fri, 28 Apr 2017) $ | |
*/ | |
/*=========================================================================*//** | |
@mainpage CoreUARTapb Bare Metal Driver. | |
@section intro_sec Introduction | |
CoreUARTapb is an implementation of the Universal Asynchronous | |
Receiver/Transmitter aimed at a minimal FPGA tile usage within an Microsemi | |
FPGA. The CoreUARTapb bare metal software driver is designed for use in | |
systems with no operating system. | |
The CoreUARTapb driver provides functions for basic polled transmitting and | |
receiving operations. It also provides functions allowing use of the | |
CoreUARTapb in interrupt-driven mode, but leaves the management of interrupts | |
to the calling application, as interrupt enabling and disabling cannot be | |
controlled through the CoreUARTapb registers. The CoreUARTapb driver is | |
provided as C source code. | |
@section driver_configuration Driver Configuration | |
Your application software should configure the CoreUARTapb driver, through | |
calls to the UART_init() function for each CoreUARTapb instance in the | |
hardware design. The configuration parameters include the CoreUARTapb | |
hardware instance base address and other runtime parameters, such as baud | |
rate, bit width, and parity. No CoreUARTapb hardware configuration parameters | |
are needed by the driver, apart from the CoreUARTapb hardware instance base | |
address. Hence, no additional configuration files are required to use the driver. | |
A CoreUARTapb hardware instance can be generated with fixed baud value, | |
character size and parity configuration settings as part of the hardware flow. | |
The baud_value and line_config parameter values passed to the UART_init() | |
function will not have any effect if fixed values were selected for the | |
baud value, character size and parity in the hardware configuration of | |
CoreUARTapb. When fixed values are selected for these hardware configuration | |
parameters, the driver cannot overwrite the fixed values in the CoreUARTapb | |
control registers, CTRL1 and CTRL2. | |
@section theory_op Theory of Operation | |
The CoreUARTapb software driver is designed to allow the control of multiple | |
instances of CoreUARTapb. Each instance of CoreUARTapb in the hardware design | |
is associated with a single instance of the UART_instance_t structure in the | |
software. You need to allocate memory for one unique UART_instance_t | |
structure instance for each CoreUARTapb hardware instance. The contents of | |
these data structures are initialized during calls to function UART_init(). | |
A pointer to the structure is passed to subsequent driver functions in order | |
to identify the CoreUARTapb hardware instance you wish to perform the | |
requested operation on. | |
Note: Do not attempt to directly manipulate the content of UART_instance_t | |
structures. This structure is only intended to be modified by the driver | |
function. | |
The driver can be used to transmit and receive data once initialized. | |
Transmit can be performed using the UART_send() function. This function | |
is blocking, meaning that it will only return once the data passed to | |
the function has been sent to the CoreUARTapb hardware. Data received | |
by the CoreUARTapb hardware can be read by the user application using | |
the UART_get_rx() function. | |
The function UART_fill_tx_fifo() is also provided to be used as part of | |
interrupt-driven transmit. This function fills the CoreUARTapb hardware | |
transmit FIFO with the content of a data buffer passed as a parameter before | |
returning. The control of the interrupts must be implemented outside the | |
driver as the CoreUARTapb hardware does not provide the ability to enable | |
or disable its interrupt sources. | |
The function UART_polled_tx_string() is provided to transmit a NULL | |
terminated string in polled mode. This function is blocking, meaning that it | |
will only return once the data passed to the function has been sent to the | |
CoreUARTapb hardware. | |
The function UART_get_rx_status() returns the error status of the CoreUARTapb | |
receiver. This can be used by applications to take appropriate action in case | |
of receiver errors. | |
*//*=========================================================================*/ | |
#ifndef __CORE_UART_APB_H | |
#define __CORE_UART_APB_H 1 | |
#include "cpu_types.h" | |
#ifdef __cplusplus | |
extern "C" { | |
#endif | |
/***************************************************************************//** | |
* Data bits length defines: | |
*/ | |
#define DATA_7_BITS 0x00u | |
#define DATA_8_BITS 0x01u | |
/***************************************************************************//** | |
* Parity defines: | |
*/ | |
#define NO_PARITY 0x00u | |
#define EVEN_PARITY 0x02u | |
#define ODD_PARITY 0x06u | |
/***************************************************************************//** | |
* Error Status definitions: | |
*/ | |
#define UART_APB_PARITY_ERROR 0x01u | |
#define UART_APB_OVERFLOW_ERROR 0x02u | |
#define UART_APB_FRAMING_ERROR 0x04u | |
#define UART_APB_NO_ERROR 0x00u | |
#define UART_APB_INVALID_PARAM 0xFFu | |
/***************************************************************************//** | |
* UART_instance_t | |
* | |
* There should be one instance of this structure for each instance of CoreUARTapb | |
* in your system. This structure instance is used to identify the various UARTs | |
* in a system and should be passed as first parameter to UART functions to | |
* identify which UART should perform the requested operation. The 'status' | |
* element in the structure is used to provide sticky status information. | |
*/ | |
typedef struct | |
{ | |
addr_t base_address; | |
uint8_t status; | |
} UART_instance_t; | |
/***************************************************************************//** | |
* The function UART_init() initializes the UART with the configuration passed | |
* as parameters. The configuration parameters are the baud_value used to | |
* generate the baud rate and the line configuration (bit length and parity). | |
* | |
* @param this_uart The this_uart parameter is a pointer to a UART_instance_t | |
* structure which holds all data regarding this instance of | |
* the CoreUARTapb. This pointer will be used to identify | |
* the target CoreUARTapb hardware instance in subsequent | |
* calls to the CoreUARTapb functions. | |
* @param base_addr The base_address parameter is the base address in the | |
* processor's memory map for the registers of the | |
* CoreUARTapb instance being initialized. | |
* @param baud_value The baud_value parameter is used to select the baud rate | |
* for the UART. The baud value is calculated from the | |
* frequency of the system clock in hertz and the desired | |
* baud rate using the following equation: | |
* | |
* baud_value = (clock /(baud_rate * 16)) - 1. | |
* | |
* The baud_value parameter must be a value in the range 0 | |
* to 8191 (or 0x0000 to 0x1FFF). | |
* @param line_config This parameter is the line configuration specifying the | |
* bit length and parity settings. This is a logical OR of: | |
* - DATA_7_BITS | |
* - DATA_8_BITS | |
* - NO_PARITY | |
* - EVEN_PARITY | |
* - ODD_PARITY | |
* For example, 8 bits even parity would be specified as | |
* (DATA_8_BITS | EVEN_PARITY). | |
* @return This function does not return a value. | |
* Example: | |
* @code | |
* #define BAUD_VALUE_57600 25 | |
* | |
* #define COREUARTAPB0_BASE_ADDR 0xC3000000UL | |
* | |
* UART_instance_t g_uart; | |
* int main() | |
* { | |
* UART_init(&g_uart, COREUARTAPB0_BASE_ADDR, | |
BAUD_VALUE_57600, (DATA_8_BITS | EVEN_PARITY)); | |
* } | |
* @endcode | |
*/ | |
void | |
UART_init | |
( | |
UART_instance_t * this_uart, | |
addr_t base_addr, | |
uint16_t baud_value, | |
uint8_t line_config | |
); | |
/***************************************************************************//** | |
* The function UART_send() is used to transmit data. It transfers the contents | |
* of the transmitter data buffer, passed as a function parameter, into the | |
* UART's hardware transmitter FIFO. It returns when the full content of the | |
* transmitter data buffer has been transferred to the UART's transmitter FIFO. | |
* | |
* Note: you cannot assume that the data you are sending using this function has | |
* been received at the other end by the time this function returns. The actual | |
* transmit over the serial connection will still be taking place at the time of | |
* the function return. It is safe to release or reuse the memory used as the | |
* transmit buffer once this function returns. | |
* | |
* @param this_uart The this_uart parameter is a pointer to a | |
* UART_instance_t structure which holds all data regarding | |
* this instance of the CoreUARTapbUART. | |
* @param tx_buffer The tx_buffer parameter is a pointer to a buffer | |
* containing the data to be transmitted. | |
* @param tx_size The tx_size parameter is the size, in bytes, of | |
* the data to be transmitted. | |
* | |
* @return This function does not return a value. | |
* | |
* Example: | |
* @code | |
* uint8_t testmsg1[] = {"\n\r\n\r\n\rUART_send() test message 1"}; | |
* UART_send(&g_uart,(const uint8_t *)&testmsg1,sizeof(testmsg1)); | |
* @endcode | |
*/ | |
void | |
UART_send | |
( | |
UART_instance_t * this_uart, | |
const uint8_t * tx_buffer, | |
size_t tx_size | |
); | |
/***************************************************************************//** | |
* The function UART_fill_tx_fifo() fills the UART's transmitter hardware FIFO | |
* with the data found in the transmitter buffer that is passed in as a | |
* function parameter. The function returns either when the FIFO is full or | |
* when the complete contents of the transmitter buffer have been copied into | |
* the FIFO. It returns the number of bytes copied into the UART's transmitter | |
* hardware FIFO. This function is intended to be used as part of | |
* interrupt-driven transmission. | |
* | |
* Note: You cannot assume that the data you transmit using this function has | |
* been received at the other end by the time this function returns. | |
* The actual transmission over the serial connection will still be | |
* taking place at the time of the function return. | |
* | |
* @param this_uart The this_uart parameter is a pointer to a UART_instance_t | |
* structure which holds all data regarding this instance of | |
* the UART. | |
* @param tx_buffer The tx_buffer parameter is a pointer to a buffer | |
* containing the data to be transmitted. | |
* @param tx_size The tx_size parameter is the size in bytes, of the data | |
* to be transmitted. | |
* @return This function returns the number of bytes copied | |
* into the UART's transmitter hardware FIFO. | |
* | |
* Example: | |
* @code | |
* void send_using_interrupt | |
* ( | |
* uint8_t * pbuff, | |
* size_t tx_size | |
* ) | |
* { | |
* size_t size_in_fifo; | |
* size_in_fifo = UART_fill_tx_fifo( &g_uart, pbuff, tx_size ); | |
* } | |
* @endcode | |
*/ | |
size_t | |
UART_fill_tx_fifo | |
( | |
UART_instance_t * this_uart, | |
const uint8_t * tx_buffer, | |
size_t tx_size | |
); | |
/***************************************************************************//** | |
* The function UART_get_rx() reads the content of the UART's receiver hardware | |
* FIFO and stores it in the receiver buffer that is passed in as a function | |
* parameter. It copies either the full contents of the FIFO into the receiver | |
* buffer, or just enough data from the FIFO to fill the receiver buffer, | |
* dependent upon the size of the receiver buffer. The size of the receiver | |
* buffer is passed in as a function parameter. UART_get_rx() returns the number | |
* of bytes copied into the receiver buffer. If no data was received at the time | |
* the function is called, the function returns 0. | |
* | |
* Note: This function reads and accumulates the receiver status of the | |
* CoreUARTapb instance before reading each byte from the receiver's | |
* data register/FIFO. This allows the driver to maintain a sticky | |
* record of any receiver errors that occur as the UART receives each | |
* data byte; receiver errors would otherwise be lost after each read | |
* from the receiver's data register. A call to the UART_get_rx_status() | |
* function returns any receiver errors accumulated during the execution | |
* of the UART_get_rx() function. | |
* Note: When FIFO mode is disabled in the CoreUARTapb hardware configuration, | |
* the driver accumulates a sticky record of any parity errors, framing | |
* errors or overflow errors. When FIFO mode is enabled, the driver | |
* accumulates a sticky record of overflow errors only; in this case | |
* interrupts must be used to handle parity errors or framing errors. | |
* | |
* @param this_uart The this_uart parameter is a pointer to a UART_instance_t | |
* structure which holds all data regarding this instance of | |
* the UART. | |
* @param rx_buffer The rx_buffer parameter is a pointer to a buffer where the | |
* received data will be copied. | |
* @param buff_size The buff_size parameter is the size of the receive buffer | |
* in bytes. | |
* @return This function returns the number of bytes copied into the | |
* receive buffer. | |
* | |
* Example: | |
* @code | |
* #define MAX_RX_DATA_SIZE 256 | |
* | |
* uint8_t rx_data[MAX_RX_DATA_SIZE]; | |
* uint8_t rx_size = 0; | |
* | |
* rx_size = UART_get_rx( &g_uart, rx_data, sizeof(rx_data) ); | |
* @endcode | |
*/ | |
size_t | |
UART_get_rx | |
( | |
UART_instance_t * this_uart, | |
uint8_t * rx_buffer, | |
size_t buff_size | |
); | |
/***************************************************************************//** | |
* The function UART_polled_tx_string() is used to transmit a NULL ('\0') | |
* terminated string. Internally, it polls for the transmit ready status and | |
* transfers the text starting at the address pointed to by p_sz_string into | |
* the UART's hardware transmitter FIFO. It is a blocking function and returns | |
* only when the complete string has been transferred to the UART's transmit | |
* FIFO. | |
* | |
* Note: You cannot assume that the data you transmit using this function | |
* has been received at the other end by the time this function | |
* returns. The actual transmission over the serial connection will | |
* still be taking place at the time of the function return. | |
* | |
* @param this_uart The this_uart parameter is a pointer to a | |
* UART_instance_t structure which holds | |
* all data regarding this instance of the UART. | |
* @param p_sz_string The p_sz_string parameter is a pointer to a buffer | |
* containing the NULL ('\0') terminated string to be | |
* transmitted. | |
* @return This function does not return a value. | |
* | |
* Example: | |
* @code | |
* uint8_t testmsg1[] = {"\r\n\r\nUART_polled_tx_string() test message 1\0"}; | |
* UART_polled_tx_string(&g_uart,(const uint8_t *)&testmsg1); | |
* @endcode | |
*/ | |
void | |
UART_polled_tx_string | |
( | |
UART_instance_t * this_uart, | |
const uint8_t * p_sz_string | |
); | |
/***************************************************************************//** | |
* The UART_get_rx_status() function returns the receiver error status of the | |
* CoreUARTapb instance. It reads both the current error status of the receiver | |
* and the accumulated error status from preceding calls to the UART_get_rx() | |
* function and combines them using a bitwise OR. It returns the cumulative | |
* parity, framing and overflow error status of the receiver, since the | |
* previous call to UART_get_rx_status(), as an 8-bit encoded value. | |
* | |
* Note: The UART_get_rx() function reads and accumulates the receiver status | |
* of the CoreUARTapb instance before reading each byte from the | |
* receiver's data register/FIFO. The driver maintains a sticky record | |
* of the cumulative error status, which persists after the | |
* UART_get_rx() function returns. The UART_get_rx_status() function | |
* clears this accumulated record of receiver errors before returning. | |
* | |
* @param this_uart The this_uart parameter is a pointer to a UART_instance_t | |
* structure which holds all data regarding this instance | |
* of the UART. | |
* @return This function returns the UART receiver error status as | |
* an 8-bit encoded value. The returned value is 0 if no | |
* receiver errors occurred. The driver provides a set of | |
* bit mask constants which should be compared with and/or | |
* used to mask the returned value to determine the | |
* receiver error status. | |
* When the return value is compared to the following bit | |
* masks, a non-zero result indicates that the | |
* corresponding error occurred: | |
* UART_APB_PARITY_ERROR (bit mask = 0x01) | |
* UART_APB_OVERFLOW_ERROR (bit mask = 0x02) | |
* UART_APB_FRAMING_ERROR (bit mask = 0x04) | |
* When the return value is compared to the following bit | |
* mask, a non-zero result indicates that no error occurred: | |
* UART_APB_NO_ERROR (0x00) | |
* | |
* Example: | |
* @code | |
* UART_instance_t g_uart; | |
* uint8_t rx_data[MAX_RX_DATA_SIZE]; | |
* uint8_t err_status; | |
* err_status = UART_get_err_status(&g_uart); | |
* | |
* if(UART_APB_NO_ERROR == err_status ) | |
* { | |
* rx_size = UART_get_rx( &g_uart, rx_data, MAX_RX_DATA_SIZE ); | |
* } | |
* @endcode | |
*/ | |
uint8_t | |
UART_get_rx_status | |
( | |
UART_instance_t * this_uart | |
); | |
#ifdef __cplusplus | |
} | |
#endif | |
#endif /* __CORE_UART_APB_H */ |