1 /*******************************************************************************
\r
2 * (c) Copyright 2007-2017 Microsemi SoC Products Group. All rights reserved.
\r
4 * This file contains the application programming interface for the CoreUARTapb
\r
7 * SVN $Revision: 9082 $
\r
8 * SVN $Date: 2017-04-28 11:51:36 +0530 (Fri, 28 Apr 2017) $
\r
10 /*=========================================================================*//**
\r
11 @mainpage CoreUARTapb Bare Metal Driver.
\r
13 @section intro_sec Introduction
\r
14 CoreUARTapb is an implementation of the Universal Asynchronous
\r
15 Receiver/Transmitter aimed at a minimal FPGA tile usage within an Microsemi
\r
16 FPGA. The CoreUARTapb bare metal software driver is designed for use in
\r
17 systems with no operating system.
\r
19 The CoreUARTapb driver provides functions for basic polled transmitting and
\r
20 receiving operations. It also provides functions allowing use of the
\r
21 CoreUARTapb in interrupt-driven mode, but leaves the management of interrupts
\r
22 to the calling application, as interrupt enabling and disabling cannot be
\r
23 controlled through the CoreUARTapb registers. The CoreUARTapb driver is
\r
24 provided as C source code.
\r
26 @section driver_configuration Driver Configuration
\r
27 Your application software should configure the CoreUARTapb driver, through
\r
28 calls to the UART_init() function for each CoreUARTapb instance in the
\r
29 hardware design. The configuration parameters include the CoreUARTapb
\r
30 hardware instance base address and other runtime parameters, such as baud
\r
31 rate, bit width, and parity. No CoreUARTapb hardware configuration parameters
\r
32 are needed by the driver, apart from the CoreUARTapb hardware instance base
\r
33 address. Hence, no additional configuration files are required to use the driver.
\r
35 A CoreUARTapb hardware instance can be generated with fixed baud value,
\r
36 character size and parity configuration settings as part of the hardware flow.
\r
37 The baud_value and line_config parameter values passed to the UART_init()
\r
38 function will not have any effect if fixed values were selected for the
\r
39 baud value, character size and parity in the hardware configuration of
\r
40 CoreUARTapb. When fixed values are selected for these hardware configuration
\r
41 parameters, the driver cannot overwrite the fixed values in the CoreUARTapb
\r
42 control registers, CTRL1 and CTRL2.
\r
44 @section theory_op Theory of Operation
\r
45 The CoreUARTapb software driver is designed to allow the control of multiple
\r
46 instances of CoreUARTapb. Each instance of CoreUARTapb in the hardware design
\r
47 is associated with a single instance of the UART_instance_t structure in the
\r
48 software. You need to allocate memory for one unique UART_instance_t
\r
49 structure instance for each CoreUARTapb hardware instance. The contents of
\r
50 these data structures are initialized during calls to function UART_init().
\r
51 A pointer to the structure is passed to subsequent driver functions in order
\r
52 to identify the CoreUARTapb hardware instance you wish to perform the
\r
53 requested operation on.
\r
55 Note: Do not attempt to directly manipulate the content of UART_instance_t
\r
56 structures. This structure is only intended to be modified by the driver
\r
59 The driver can be used to transmit and receive data once initialized.
\r
60 Transmit can be performed using the UART_send() function. This function
\r
61 is blocking, meaning that it will only return once the data passed to
\r
62 the function has been sent to the CoreUARTapb hardware. Data received
\r
63 by the CoreUARTapb hardware can be read by the user application using
\r
64 the UART_get_rx() function.
\r
66 The function UART_fill_tx_fifo() is also provided to be used as part of
\r
67 interrupt-driven transmit. This function fills the CoreUARTapb hardware
\r
68 transmit FIFO with the content of a data buffer passed as a parameter before
\r
69 returning. The control of the interrupts must be implemented outside the
\r
70 driver as the CoreUARTapb hardware does not provide the ability to enable
\r
71 or disable its interrupt sources.
\r
73 The function UART_polled_tx_string() is provided to transmit a NULL
\r
74 terminated string in polled mode. This function is blocking, meaning that it
\r
75 will only return once the data passed to the function has been sent to the
\r
76 CoreUARTapb hardware.
\r
78 The function UART_get_rx_status() returns the error status of the CoreUARTapb
\r
79 receiver. This can be used by applications to take appropriate action in case
\r
81 *//*=========================================================================*/
\r
82 #ifndef __CORE_UART_APB_H
\r
83 #define __CORE_UART_APB_H 1
\r
85 #include "cpu_types.h"
\r
91 /***************************************************************************//**
\r
92 * Data bits length defines:
\r
94 #define DATA_7_BITS 0x00u
\r
95 #define DATA_8_BITS 0x01u
\r
97 /***************************************************************************//**
\r
100 #define NO_PARITY 0x00u
\r
101 #define EVEN_PARITY 0x02u
\r
102 #define ODD_PARITY 0x06u
\r
104 /***************************************************************************//**
\r
105 * Error Status definitions:
\r
107 #define UART_APB_PARITY_ERROR 0x01u
\r
108 #define UART_APB_OVERFLOW_ERROR 0x02u
\r
109 #define UART_APB_FRAMING_ERROR 0x04u
\r
110 #define UART_APB_NO_ERROR 0x00u
\r
111 #define UART_APB_INVALID_PARAM 0xFFu
\r
113 /***************************************************************************//**
\r
116 * There should be one instance of this structure for each instance of CoreUARTapb
\r
117 * in your system. This structure instance is used to identify the various UARTs
\r
118 * in a system and should be passed as first parameter to UART functions to
\r
119 * identify which UART should perform the requested operation. The 'status'
\r
120 * element in the structure is used to provide sticky status information.
\r
124 addr_t base_address;
\r
128 /***************************************************************************//**
\r
129 * The function UART_init() initializes the UART with the configuration passed
\r
130 * as parameters. The configuration parameters are the baud_value used to
\r
131 * generate the baud rate and the line configuration (bit length and parity).
\r
133 * @param this_uart The this_uart parameter is a pointer to a UART_instance_t
\r
134 * structure which holds all data regarding this instance of
\r
135 * the CoreUARTapb. This pointer will be used to identify
\r
136 * the target CoreUARTapb hardware instance in subsequent
\r
137 * calls to the CoreUARTapb functions.
\r
138 * @param base_addr The base_address parameter is the base address in the
\r
139 * processor's memory map for the registers of the
\r
140 * CoreUARTapb instance being initialized.
\r
141 * @param baud_value The baud_value parameter is used to select the baud rate
\r
142 * for the UART. The baud value is calculated from the
\r
143 * frequency of the system clock in hertz and the desired
\r
144 * baud rate using the following equation:
\r
146 * baud_value = (clock /(baud_rate * 16)) - 1.
\r
148 * The baud_value parameter must be a value in the range 0
\r
149 * to 8191 (or 0x0000 to 0x1FFF).
\r
150 * @param line_config This parameter is the line configuration specifying the
\r
151 * bit length and parity settings. This is a logical OR of:
\r
157 * For example, 8 bits even parity would be specified as
\r
158 * (DATA_8_BITS | EVEN_PARITY).
\r
159 * @return This function does not return a value.
\r
162 * #define BAUD_VALUE_57600 25
\r
164 * #define COREUARTAPB0_BASE_ADDR 0xC3000000UL
\r
166 * UART_instance_t g_uart;
\r
169 * UART_init(&g_uart, COREUARTAPB0_BASE_ADDR,
\r
170 BAUD_VALUE_57600, (DATA_8_BITS | EVEN_PARITY));
\r
177 UART_instance_t * this_uart,
\r
179 uint16_t baud_value,
\r
180 uint8_t line_config
\r
183 /***************************************************************************//**
\r
184 * The function UART_send() is used to transmit data. It transfers the contents
\r
185 * of the transmitter data buffer, passed as a function parameter, into the
\r
186 * UART's hardware transmitter FIFO. It returns when the full content of the
\r
187 * transmitter data buffer has been transferred to the UART's transmitter FIFO.
\r
189 * Note: you cannot assume that the data you are sending using this function has
\r
190 * been received at the other end by the time this function returns. The actual
\r
191 * transmit over the serial connection will still be taking place at the time of
\r
192 * the function return. It is safe to release or reuse the memory used as the
\r
193 * transmit buffer once this function returns.
\r
195 * @param this_uart The this_uart parameter is a pointer to a
\r
196 * UART_instance_t structure which holds all data regarding
\r
197 * this instance of the CoreUARTapbUART.
\r
198 * @param tx_buffer The tx_buffer parameter is a pointer to a buffer
\r
199 * containing the data to be transmitted.
\r
200 * @param tx_size The tx_size parameter is the size, in bytes, of
\r
201 * the data to be transmitted.
\r
203 * @return This function does not return a value.
\r
207 * uint8_t testmsg1[] = {"\n\r\n\r\n\rUART_send() test message 1"};
\r
208 * UART_send(&g_uart,(const uint8_t *)&testmsg1,sizeof(testmsg1));
\r
214 UART_instance_t * this_uart,
\r
215 const uint8_t * tx_buffer,
\r
219 /***************************************************************************//**
\r
220 * The function UART_fill_tx_fifo() fills the UART's transmitter hardware FIFO
\r
221 * with the data found in the transmitter buffer that is passed in as a
\r
222 * function parameter. The function returns either when the FIFO is full or
\r
223 * when the complete contents of the transmitter buffer have been copied into
\r
224 * the FIFO. It returns the number of bytes copied into the UART's transmitter
\r
225 * hardware FIFO. This function is intended to be used as part of
\r
226 * interrupt-driven transmission.
\r
228 * Note: You cannot assume that the data you transmit using this function has
\r
229 * been received at the other end by the time this function returns.
\r
230 * The actual transmission over the serial connection will still be
\r
231 * taking place at the time of the function return.
\r
233 * @param this_uart The this_uart parameter is a pointer to a UART_instance_t
\r
234 * structure which holds all data regarding this instance of
\r
236 * @param tx_buffer The tx_buffer parameter is a pointer to a buffer
\r
237 * containing the data to be transmitted.
\r
238 * @param tx_size The tx_size parameter is the size in bytes, of the data
\r
239 * to be transmitted.
\r
240 * @return This function returns the number of bytes copied
\r
241 * into the UART's transmitter hardware FIFO.
\r
245 * void send_using_interrupt
\r
251 * size_t size_in_fifo;
\r
252 * size_in_fifo = UART_fill_tx_fifo( &g_uart, pbuff, tx_size );
\r
259 UART_instance_t * this_uart,
\r
260 const uint8_t * tx_buffer,
\r
264 /***************************************************************************//**
\r
265 * The function UART_get_rx() reads the content of the UART's receiver hardware
\r
266 * FIFO and stores it in the receiver buffer that is passed in as a function
\r
267 * parameter. It copies either the full contents of the FIFO into the receiver
\r
268 * buffer, or just enough data from the FIFO to fill the receiver buffer,
\r
269 * dependent upon the size of the receiver buffer. The size of the receiver
\r
270 * buffer is passed in as a function parameter. UART_get_rx() returns the number
\r
271 * of bytes copied into the receiver buffer. If no data was received at the time
\r
272 * the function is called, the function returns 0.
\r
274 * Note: This function reads and accumulates the receiver status of the
\r
275 * CoreUARTapb instance before reading each byte from the receiver's
\r
276 * data register/FIFO. This allows the driver to maintain a sticky
\r
277 * record of any receiver errors that occur as the UART receives each
\r
278 * data byte; receiver errors would otherwise be lost after each read
\r
279 * from the receiver's data register. A call to the UART_get_rx_status()
\r
280 * function returns any receiver errors accumulated during the execution
\r
281 * of the UART_get_rx() function.
\r
282 * Note: When FIFO mode is disabled in the CoreUARTapb hardware configuration,
\r
283 * the driver accumulates a sticky record of any parity errors, framing
\r
284 * errors or overflow errors. When FIFO mode is enabled, the driver
\r
285 * accumulates a sticky record of overflow errors only; in this case
\r
286 * interrupts must be used to handle parity errors or framing errors.
\r
288 * @param this_uart The this_uart parameter is a pointer to a UART_instance_t
\r
289 * structure which holds all data regarding this instance of
\r
291 * @param rx_buffer The rx_buffer parameter is a pointer to a buffer where the
\r
292 * received data will be copied.
\r
293 * @param buff_size The buff_size parameter is the size of the receive buffer
\r
295 * @return This function returns the number of bytes copied into the
\r
300 * #define MAX_RX_DATA_SIZE 256
\r
302 * uint8_t rx_data[MAX_RX_DATA_SIZE];
\r
303 * uint8_t rx_size = 0;
\r
305 * rx_size = UART_get_rx( &g_uart, rx_data, sizeof(rx_data) );
\r
311 UART_instance_t * this_uart,
\r
312 uint8_t * rx_buffer,
\r
316 /***************************************************************************//**
\r
317 * The function UART_polled_tx_string() is used to transmit a NULL ('\0')
\r
318 * terminated string. Internally, it polls for the transmit ready status and
\r
319 * transfers the text starting at the address pointed to by p_sz_string into
\r
320 * the UART's hardware transmitter FIFO. It is a blocking function and returns
\r
321 * only when the complete string has been transferred to the UART's transmit
\r
324 * Note: You cannot assume that the data you transmit using this function
\r
325 * has been received at the other end by the time this function
\r
326 * returns. The actual transmission over the serial connection will
\r
327 * still be taking place at the time of the function return.
\r
329 * @param this_uart The this_uart parameter is a pointer to a
\r
330 * UART_instance_t structure which holds
\r
331 * all data regarding this instance of the UART.
\r
332 * @param p_sz_string The p_sz_string parameter is a pointer to a buffer
\r
333 * containing the NULL ('\0') terminated string to be
\r
335 * @return This function does not return a value.
\r
339 * uint8_t testmsg1[] = {"\r\n\r\nUART_polled_tx_string() test message 1\0"};
\r
340 * UART_polled_tx_string(&g_uart,(const uint8_t *)&testmsg1);
\r
344 UART_polled_tx_string
\r
346 UART_instance_t * this_uart,
\r
347 const uint8_t * p_sz_string
\r
350 /***************************************************************************//**
\r
351 * The UART_get_rx_status() function returns the receiver error status of the
\r
352 * CoreUARTapb instance. It reads both the current error status of the receiver
\r
353 * and the accumulated error status from preceding calls to the UART_get_rx()
\r
354 * function and combines them using a bitwise OR. It returns the cumulative
\r
355 * parity, framing and overflow error status of the receiver, since the
\r
356 * previous call to UART_get_rx_status(), as an 8-bit encoded value.
\r
358 * Note: The UART_get_rx() function reads and accumulates the receiver status
\r
359 * of the CoreUARTapb instance before reading each byte from the
\r
360 * receiver's data register/FIFO. The driver maintains a sticky record
\r
361 * of the cumulative error status, which persists after the
\r
362 * UART_get_rx() function returns. The UART_get_rx_status() function
\r
363 * clears this accumulated record of receiver errors before returning.
\r
365 * @param this_uart The this_uart parameter is a pointer to a UART_instance_t
\r
366 * structure which holds all data regarding this instance
\r
368 * @return This function returns the UART receiver error status as
\r
369 * an 8-bit encoded value. The returned value is 0 if no
\r
370 * receiver errors occurred. The driver provides a set of
\r
371 * bit mask constants which should be compared with and/or
\r
372 * used to mask the returned value to determine the
\r
373 * receiver error status.
\r
374 * When the return value is compared to the following bit
\r
375 * masks, a non-zero result indicates that the
\r
376 * corresponding error occurred:
\r
377 * UART_APB_PARITY_ERROR (bit mask = 0x01)
\r
378 * UART_APB_OVERFLOW_ERROR (bit mask = 0x02)
\r
379 * UART_APB_FRAMING_ERROR (bit mask = 0x04)
\r
380 * When the return value is compared to the following bit
\r
381 * mask, a non-zero result indicates that no error occurred:
\r
382 * UART_APB_NO_ERROR (0x00)
\r
386 * UART_instance_t g_uart;
\r
387 * uint8_t rx_data[MAX_RX_DATA_SIZE];
\r
388 * uint8_t err_status;
\r
389 * err_status = UART_get_err_status(&g_uart);
\r
391 * if(UART_APB_NO_ERROR == err_status )
\r
393 * rx_size = UART_get_rx( &g_uart, rx_data, MAX_RX_DATA_SIZE );
\r
400 UART_instance_t * this_uart
\r
407 #endif /* __CORE_UART_APB_H */
\r
projects / freertos / blob