1 /*******************************************************************************
2  * Copyright 2019-2020 Microchip FPGA Embedded Systems Solutions.
3  *
4  * SPDX-License-Identifier: MIT
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  *
24  *
25  * PolarFire SoC Microprocessor Subsystem MMUART bare metal software driver
26  * public API.
27  *
28  */
29 /*=========================================================================*//**
30   @mainpage PolarFire SoC MSS UART Bare Metal Driver.
31 
32   ==============================================================================
33   Introduction
34   ==============================================================================
35   The PolarFire SoC Microprocessor subsystem (MSS) includes five multi-mode UART
36   (MMUART) peripherals for serial communication. This driver provides a set of
37   functions for controlling the MSS MMUARTs as part of a bare metal system
38   where no operating system is available. These drivers can be adapted for use
39   as part of an operating system, but the implementation of the adaptation layer
40   between this driver and the operating system's driver model is outside the
41   scope of this driver.
42   Note: MSS UART is synonymous with MSS MMUART in this document.
43 
44   ==============================================================================
45   Hardware Flow Dependencies
46   ==============================================================================
47   The configuration of all features of the MSS MMUART peripherals is covered by
48   this driver with the exception of the PolarFire SoC IOMUX configuration.
49   PolarFire SoC allows multiple non-concurrent uses of some external pins
50   through IOMUX configuration. This feature allows optimization of external pin
51   usage by assigning external pins for use by either the microprocessor
52   subsystem or the FPGA fabric. The MSS MMUART serial signals are routed through
53   IOMUXs to the PolarFire SoC device external pins. The MSS MMUART serial
54   signals may also be routed through IOMUXs to the PolarFire SoC FPGA fabric.
55   For more information on IOMUX, refer to the I/O Configuration section of the
56   PolarFire SoC Microprocessor Subsystem (MSS) User's Guide.
57 
58   The IOMUXs are configured using the PolarFire SoC MSS configurator tool. You
59   must ensure that the MSS MMUART peripherals are enabled and configured in the
60   PolarFire SoC MSS configurator if you wish to use them. For more information
61   on IOMUXs, refer to the IOMUX section of the PolarFire SoC microprocessor
62   Subsystem (MSS) User's Guide.
63 
64   On PolarFire SoC an AXI switch forms a bus matrix interconnect among multiple
65   masters and multiple slaves. Five RISC-V CPUs connect to the Master ports
66   M10 to M14 of the AXI switch. By default, all the APB peripherals are
67   accessible on AXI-Slave 5 of the AXI switch via the AXI to AHB and AHB to APB
68   bridges (referred as main APB bus). However, to support logical separation in
69   the Asymmetric Multi-Processing (AMP) mode of operation, the APB peripherals
70   can alternatively be accessed on the AXI-Slave 6 via the AXI to AHB and AHB to
71   APB bridges (referred as the AMP APB bus).
72 
73   Application must make sure that the desired MMUART instance is appropriately
74   configured on one of the APB bus described above by configuring the PolarFire
75   SoC system registers (SYSREG) as per the application need and that the
76   appropriate data structures are provided to this driver as parameter to the
77   functions provided by this driver.
78 
79   The base address and register addresses are defined in this driver as
80   constants. The interrupt number assignment for the MSS MMUART peripherals are
81   defined as constants in the MPFS HAL. You must ensure that the latest MPFS HAL
82   is included in the project settings of the SoftConsole tool chain and that it
83   is generated into your project.
84 
85   ==============================================================================
86   Theory of Operation
87   ==============================================================================
88   The MSS MMUART driver functions are grouped into the following categories:
89     - Initialization and configuration functions
90     - Polled transmit and receive functions
91     - Interrupt driven transmit and receive functions
92 
93   --------------------------------
94   Initialization and Configuration
95   --------------------------------
96   The MSS MMUART supports the following four broad modes of operation:
97     - UART or USART mode
98     - LIN mode
99     - IrDA mode
100     - Smartcard or ISO 7816 mode
101 
102   The MSS MMUART driver provides the MSS_UART_init(), MSS_UART_lin_init(),
103   MSS_UART_irda_init() and MSS_UART_smartcard_init() functions to initialize the
104   MSS MMUARTs for operation in one of these modes. One of these initialization
105   functions must be called before any other MSS MMUART driver functions can be
106   called. The MSS MMUART operating modes are mutually exclusive; therefore only
107   one of the initialization functions must be called. The first parameter of the
108   initialization functions is a pointer to one of ten global data structures
109   used to store state information for each MSS MMUART. A pointer to these data
110   structures is also used as the first parameter to many of the driver functions
111   to identify which MSS MMUART will be used by the called function. The names of
112   these data structures are:
113     - g_mss_uart0_lo
114     - g_mss_uart1_lo
115     - g_mss_uart2_lo
116     - g_mss_uart3_lo
117     - g_mss_uart4_lo
118     - g_mss_uart0_hi
119     - g_mss_uart1_hi
120     - g_mss_uart2_hi
121     - g_mss_uart3_hi
122     - g_mss_uart4_hi
123 
124   Therefore, any call to an MSS MMUART function should be of the form
125   MSS_UART_function_name( &g_mss_uart0_lo, ... ) or
126   MSS_UART_function_name( &g_mss_uart1_hi, ... ).
127 
128   UART or USART Mode
129   For the UART or USART modes of operation, the MSS MMUART driver is initialized
130   through a call to the MSS_UART_init() function. This function takes the UART's
131   configuration as its parameters. The MSS_UART_init() function must be called
132   before any other MSS MMUART driver functions can be called.
133   The MSS_UART_init() function configures the baud rate based on the input baud
134   rate parameter and if possible uses a fractional baud rate for greater
135   precision. This function disables the LIN, IrDA and SmartCard modes.
136 
137   LIN mode
138   For the LIN mode of operation, the MSS MMUART driver is initialized through a
139   call to the MSS_UART_lin_init() function. This function takes the LIN node's
140   configuration as its parameters. The MSS_UART_lin_init() function must be
141   called before any other MSS MMUART driver functions can be called. The
142   MSS_UART_lin_init() function configures the baud rate based on the input baud
143   rate parameter and if possible uses a fractional baud rate for greater
144   precision. This function disables the IrDA and SmartCard modes.
145   The driver also provides the following LIN mode configuration functions:
146     - MSS_UART_set_break()
147     - MSS_UART_clear_break()
148     - MSS_UART_set_pidpei_handler()
149     - MSS_UART_set_linbreak_handler()
150     - MSS_UART_set_linsync_handler()
151 
152   Note: These LIN mode configuration functions can only be called after the
153   MSS_UART_lin_init() function is called.
154 
155   IrDA mode
156   For the IrDA mode of operation, the driver is initialized through a call to
157   the MSS_UART_irda_init() function. This function takes the IrDA node's
158   configuration as its parameters. The MSS_UART_irda_init() function must be
159   called before any other MSS MMUART driver functions can be called. The
160   MSS_UART_irda_init() function configures the baud rate based on the input baud
161   rate parameter and if possible uses a fractional baud rate for greater
162   precision. This function disables the LIN and SmartCard modes.
163 
164   Smartcard or ISO 7816 mode
165   For the Smartcard or ISO 7816 mode of operation, the driver is initialized
166   through a call to the MSS_UART_smartcard_init() function. This function takes
167   the smartcard configuration as its parameters. The MSS_UART_smartcard_init()
168   function must be called before any other MSS MMUART driver functions can be
169   called. The MSS_UART_smartcard_init() function configures the baud rate based
170   on the input baud rate parameter and if possible uses a fractional baud rate
171   for greater precision. This function disables the LIN and IrDA modes.
172   The driver also provides the following Smartcard mode configuration functions:
173     - MSS_UART_enable_halfduplex()
174     - MSS_UART_disable_halfduplex()
175     - MSS_UART_set_nack_handler()
176 
177   Note: These Smartcard mode configuration functions can only be called after
178   the MSS_UART_smartcard_init() function is called.
179 
180   Common Configuration Functions
181   The driver also provides the configuration functions that can be used with all
182   MSS MMUART operating modes. These common configuration functions are as
183   follows:
184     - MSS_UART_set_rx_endian()
185     - MSS_UART_set_tx_endian()
186     - MSS_UART_enable_afclear()
187     - MSS_UART_disable_afclear()
188     - MSS_UART_enable_rx_timeout()
189     - MSS_UART_disable_rx_timeout()
190     - MSS_UART_enable_tx_time_guard()
191     - MSS_UART_disable_tx_time_guard()
192     - MSS_UART_set_address()
193     - MSS_UART_set_ready_mode()
194     - MSS_UART_set_usart_mode()
195     - MSS_UART_set_filter_length()
196     - MSS_UART_enable_afm()
197     - MSS_UART_disable_afm()
198 
199   Note: These configuration functions can only be called after one of the
200         MSS_UART_init(), MSS_UART_lin_init(), MSS_UART_irda_init() or
201         MSS_UART_smartcard_init() functions is called.
202 
203   --------------------------------------
204   Polled Transmit and Receive Operations
205   --------------------------------------
206   The driver can be used to transmit and receive data once initialized.
207   Data is transmitted using the MSS_UART_polled_tx() function. This function is
208   blocking, meaning that it will only return once the data passed to the
209   function has been sent to the MSS MMUART hardware transmitter. Data received
210   by the MSS MMUART hardware receiver can be read by the MSS_UART_get_rx()
211   function.
212   The MSS_UART_polled_tx_string() function is provided to transmit a NUL ('\0')
213   terminated string in polled mode. This function is blocking, meaning that it
214   will only return once the data passed to the function has been sent to the MSS
215   MMUART hardware transmitter.
216   The MSS_UART_fill_tx_fifo() function fills the MSS MMUART hardware transmit
217   FIFO with data from a buffer passed as a parameter and returns the number of
218   bytes transferred to the FIFO. If the transmit FIFO is not empty when the
219   MSS_UART_fill_tx_fifo() function is called it returns immediately without
220   transferring any data to the FIFO.
221 
222   ---------------------------
223   Interrupt Driven Operations
224   ---------------------------
225   The driver can also transmit or receive data under interrupt control, freeing
226   your application to perform other tasks until an interrupt occurs indicating
227   that the driver's attention is required.
228 
229   Local or PLIC interrupt:
230   PolarFire SoC architecture provides flexibility in terms of how the MMUART
231   interrupt is seen by the PolarFire SoC Core Complex. Each of the 5 MMUART
232   instance interrupt line is connected to the PolarFire SoC Core Complex PLIC.
233   The MMUART0 instance interrupt line is also available as local interrupt on
234   E51 processor. The MMUART1 instance interrupt onwards are available as local
235   interrupt on the U54_1 processor onwards. e.g. MMUART2 interrupt is available
236   as local interrupt on U54_2.
237 
238   Interrupt Handlers
239   The MSS MMUART driver supports all types of interrupt triggered by the MSS
240   MMUART. The driver's internal top level interrupt handler identifies the
241   source of the MSS MMUART interrupt and calls the corresponding lower level
242   handler function that you previously registered with the driver through calls
243   to the MSS_UART_set_rx_handler(), MSS_UART_set_tx_handler(),
244   MSS_UART_set_rxstatus_handler(), and MSS_UART_set_modemstatus_handler()
245   functions. You are responsible for creating these lower level interrupt
246   handlers as part of your application program and registering them with the
247   driver.
248   Note: The PolarFire SoC HAL defines the interrupt handler functions for all
249         5 MMUART instances(with weak linkage) and assigns them as the interrupt
250         service routines (ISR) for the MSS MMUART interrupt inputs to the
251         PolarFire SoC Core Complex PLIC or the Local interrupts on each of the
252         respective CPUs. The MSS MMUART driver provides the implementation
253         functions all these ISRs from which it calls its own internal top level,
254         interrupt handler function.
255 
256   The MSS_UART_enable_irq() and MSS_UART_disable_irq() functions are used to
257   enable or disable the received line status, received data available/character
258   time-out, transmit holding register empty and modem status interrupts at the
259   MSS MMUART level. The MSS_UART_enable_irq() function also enables the MSS
260   MMUART instance interrupt at the PolarFire SoC Core Complex level.
261 
262   Note that the MSS_UART_enable_irq() and MSS_UART_disable_irq() and all the
263   calls to set the handler functions assume that the MMUART interrupt is
264   connected to the PolarFire SoC Core Complex PLIC. If you want the MMUART
265   interrupt to appear as a local interrupt to the corresponding HART then you
266   must explicitly call the MSS_UART_enable_local_irq() function. This function
267   will disable the PLIC interrupt (if it was previously enable) and enable the
268   local interrupt on the HART on which this function is being executed.
269 
270   Transmitting Data
271   Interrupt-driven transmit is initiated by a call to MSS_UART_irq_tx(),
272   specifying the block of data to transmit. Your application is then free to
273   perform other tasks and inquire later whether transmit has completed by
274   calling the MSS_UART_tx_complete() function. The MSS_UART_irq_tx() function
275   enables the UART's transmit holding register empty (THRE) interrupt and then,
276   when the interrupt goes active, the driver's default THRE interrupt handler
277   transfers the data block to the UART until the entire block is transmitted.
278   Note: You can use the MSS_UART_set_tx_handler() function to assign an
279         alternative handler to the THRE interrupt. In this case, you must not
280         use the MSS_UART_irq_tx() function to initiate the transmit, as this
281         will re-assign the driver's default THRE interrupt handler to the THRE
282         interrupt. Instead, your alternative THRE interrupt handler must include
283         a call to the MSS_UART_fill_tx_fifo() function to transfer the data to
284         the UART.
285 
286   Receiving Data
287   Interrupt-driven receive is performed by first calling
288   MSS_UART_set_rx_handler() to register a receive handler function that will be
289   called by the driver whenever receive data is available. You must provide this
290   receive handler function which must include a call to the MSS_UART_get_rx()
291   function to actually read the received data.
292 
293   -----------
294   UART Status
295   -----------
296   The function MSS_UART_get_rx_status() is used to read the receiver error
297   status. This function returns the overrun, parity, framing, break, and FIFO
298   error status of the receiver.
299   The function MSS_UART_get_tx_status() is used to read the transmitter status.
300   This function returns the transmit empty (TEMT) and transmit holding register
301   empty (THRE) status of the transmitter.
302   The function MSS_UART_get_modem_status() is used to read the modem status
303   flags. This function returns the current value of the modem status register.
304 
305   --------
306   Loopback
307   --------
308   The MSS_UART_set_loopback() function can be used to locally loopback the Tx
309   and Rx lines of a UART. This is not to be confused with the loopback of UART0
310   to UART1, which can be achieved through the microprocessor subsystem's system
311   registers.
312 
313  *//*=========================================================================*/
314 #ifndef __MSS_UART_H_
315 #define __MSS_UART_H_ 1
316 
317 #include <stddef.h>
318 #include <stdint.h>
319 
320 #ifdef __cplusplus
321 extern "C" {
322 #endif
323 
324 
325 /***************************************************************************//**
326   Baud rates
327   ==========
328   The following definitions are used to specify standard baud rates as a
329   parameter to the MSS_UART_init() function.
330 
331   | Constant             | Description      |
332   |----------------------|------------------|
333   | MSS_UART_110_BAUD    |    110 baud rate |
334   | MSS_UART_300_BAUD    |    300 baud rate |
335   | MSS_UART_600_BAUD    |    600 baud rate |
336   | MSS_UART_1200_BAUD   |   1200 baud rate |
337   | MSS_UART_2400_BAUD   |   2400 baud rate |
338   | MSS_UART_4800_BAUD   |   4800 baud rate |
339   | MSS_UART_9600_BAUD   |   9600 baud rate |
340   | MSS_UART_19200_BAUD  |  19200 baud rate |
341   | MSS_UART_38400_BAUD  |  38400 baud rate |
342   | MSS_UART_57600_BAUD  |  57600 baud rate |
343   | MSS_UART_115200_BAUD | 115200 baud rate |
344   | MSS_UART_230400_BAUD | 230400 baud rate |
345   | MSS_UART_460800_BAUD | 460800 baud rate |
346   | MSS_UART_921600_BAUD | 921600 baud rate |
347 
348  */
349 #define MSS_UART_110_BAUD       110U
350 #define MSS_UART_300_BAUD       300U
351 #define MSS_UART_600_BAUD       600U
352 #define MSS_UART_1200_BAUD      1200U
353 #define MSS_UART_2400_BAUD      2400U
354 #define MSS_UART_4800_BAUD      4800U
355 #define MSS_UART_9600_BAUD      9600U
356 #define MSS_UART_19200_BAUD     19200U
357 #define MSS_UART_38400_BAUD     38400U
358 #define MSS_UART_57600_BAUD     57600U
359 #define MSS_UART_115200_BAUD    115200U
360 #define MSS_UART_230400_BAUD    230400U
361 #define MSS_UART_460800_BAUD    460800U
362 #define MSS_UART_921600_BAUD    921600U
363 
364 /***************************************************************************//**
365   Data Bits Length
366   ================
367   The following defines are used to build the value of the MSS_UART_init()
368   function line_config parameter.
369 
370   | Constant             | Description                |
371   |----------------------|----------------------------|
372   | MSS_UART_DATA_5_BITS | 5 bits of data transmitted |
373   | MSS_UART_DATA_6_BITS | 6 bits of data transmitted |
374   | MSS_UART_DATA_7_BITS | 7 bits of data transmitted |
375   | MSS_UART_DATA_8_BITS | 8 bits of data transmitted |
376 
377  */
378 #define MSS_UART_DATA_5_BITS     ((uint8_t) 0x00)
379 #define MSS_UART_DATA_6_BITS     ((uint8_t) 0x01)
380 #define MSS_UART_DATA_7_BITS     ((uint8_t) 0x02)
381 #define MSS_UART_DATA_8_BITS     ((uint8_t) 0x03)
382 
383 /***************************************************************************//**
384   Parity
385   ======
386   The following defines are used to build the value of the MSS_UART_init()
387   function line_config parameter.
388 
389   | Constant                | Description              |
390   |-------------------------|--------------------------|
391   | MSS_UART_NO_PARITY      | No parity                |
392   | MSS_UART_ODD_PARITY     | Odd Parity               |
393   | MSS_UART_EVEN_PARITY    | Even parity              |
394   | MSS_UART_STICK_PARITY_0 | Stick parity bit to zero |
395   | MSS_UART_STICK_PARITY_1 | Stick parity bit to one  |
396 
397  */
398 #define MSS_UART_NO_PARITY           ((uint8_t) 0x00)
399 #define MSS_UART_ODD_PARITY          ((uint8_t) 0x08)
400 #define MSS_UART_EVEN_PARITY         ((uint8_t) 0x18)
401 #define MSS_UART_STICK_PARITY_0      ((uint8_t) 0x38)
402 #define MSS_UART_STICK_PARITY_1      ((uint8_t) 0x28)
403 
404 /***************************************************************************//**
405   Number of Stop Bits
406   ===================
407   The following defines are used to build the value of the MSS_UART_init()
408   function line_config parameter.
409 
410   | Constant                  | Description              |
411   |---------------------------|--------------------------|
412   | MSS_UART_ONE_STOP_BIT     | One stop bit             |
413   | MSS_UART_ONEHALF_STOP_BIT | One and a half stop bits |
414   | MSS_UART_TWO_STOP_BITS    | Two stop bits            |
415 
416  */
417 #define MSS_UART_ONE_STOP_BIT        ((uint8_t) 0x00)
418 #define MSS_UART_ONEHALF_STOP_BIT    ((uint8_t) 0x04)
419 #define MSS_UART_TWO_STOP_BITS       ((uint8_t) 0x04)
420 
421 /***************************************************************************//**
422   Receiver Error Status
423   =====================
424   The following defines are used to determine the UART receiver error type.
425   These bit mask constants are used with the return value of the
426   MSS_UART_get_rx_status() function to find out if any errors occurred while
427   receiving data.
428 
429 
430   | Constant               | Description                                |
431   |------------------------|--------------------------------------------|
432   | MSS_UART_NO_ERROR      | No error bit mask (0x00)                   |
433   | MSS_UART_OVERUN_ERROR  | Overrun error bit mask (0x02)              |
434   | MSS_UART_PARITY_ERROR  | Parity error bit mask (0x04)               |
435   | MSS_UART_FRAMING_ERROR | Framing error bit mask (0x08)              |
436   | MSS_UART_BREAK_ERROR   | Break error bit mask (0x10)                |
437   | MSS_UART_FIFO_ERROR    | FIFO error bit mask (0x80)                 |
438   | MSS_UART_INVALID_PARAM | Invalid function parameter bit mask (0xFF) |
439 
440  */
441 #define MSS_UART_INVALID_PARAM    ((uint8_t)0xFF)
442 #define MSS_UART_NO_ERROR         ((uint8_t)0x00 )
443 #define MSS_UART_OVERUN_ERROR     ((uint8_t)0x02)
444 #define MSS_UART_PARITY_ERROR     ((uint8_t)0x04)
445 #define MSS_UART_FRAMING_ERROR    ((uint8_t)0x08)
446 #define MSS_UART_BREAK_ERROR      ((uint8_t)0x10)
447 #define MSS_UART_FIFO_ERROR       ((uint8_t)0x80)
448 
449 /***************************************************************************//**
450   Transmitter Status
451   ==================
452   The following definitions are used to determine the UART transmitter status.
453   These bit mask constants are used with the return value of the
454   MSS_UART_get_tx_status() function to find out the status of the transmitter.
455 
456   | Constant         | Description                                        |
457   |------------------|----------------------------------------------------|
458   | MSS_UART_TX_BUSY | Transmitter busy (0x00)                            |
459   | MSS_UART_THRE    | Transmitter holding register empty bit mask (0x20) |
460   | MSS_UART_TEMT    | Transmitter empty bit mask (0x40)                  |
461 
462  */
463 #define MSS_UART_TX_BUSY          ((uint8_t) 0x00)
464 #define MSS_UART_THRE             ((uint8_t) 0x20)
465 #define MSS_UART_TEMT             ((uint8_t) 0x40)
466 
467 /***************************************************************************//**
468   Modem Status
469   ============
470   The following defines are used to determine the modem status. These bit
471   mask constants are used with the return value of the
472   MSS_UART_get_modem_status() function to find out the modem status of
473   the UART.
474 
475   | Constant      | Description                                     |
476   |---------------|-------------------------------------------------|
477   | MSS_UART_DCTS | Delta clear to send bit mask (0x01)             |
478   | MSS_UART_DDSR | Delta data set ready bit mask (0x02)            |
479   | MSS_UART_TERI | Trailing edge of ring indicator bit mask (0x04) |
480   | MSS_UART_DDCD | Delta data carrier detect bit mask (0x08)       |
481   | MSS_UART_CTS  | Clear to send bit mask (0x10)                   |
482   | MSS_UART_DSR  | Data set ready bit mask (0x20)                  |
483   | MSS_UART_RI   | Ring indicator bit mask (0x40)                  |
484   | MSS_UART_DCD  | Data carrier detect bit mask (0x80)             |
485 
486  */
487 #define MSS_UART_DCTS             ((uint8_t) 0x01)
488 #define MSS_UART_DDSR             ((uint8_t) 0x02)
489 #define MSS_UART_TERI             ((uint8_t) 0x04)
490 #define MSS_UART_DDCD             ((uint8_t) 0x08)
491 #define MSS_UART_CTS              ((uint8_t) 0x10)
492 #define MSS_UART_DSR              ((uint8_t) 0x20)
493 #define MSS_UART_RI               ((uint8_t) 0x40)
494 #define MSS_UART_DCD              ((uint8_t) 0x80)
495 
496 /***************************************************************************//**
497   This typedef specifies the irq_mask parameter for the MSS_UART_enable_irq()
498   and MSS_UART_disable_irq() functions. The driver defines a set of bit masks
499   that are used to build the value of the irq_mask parameter. A bitwise OR of
500   these bit masks is used to enable or disable multiple MSS MMUART interrupts.
501  */
502 typedef uint16_t mss_uart_irq_t;
503 
504 /***************************************************************************//**
505   MSS MMUART Interrupts
506   =====================
507   The following defines specify the interrupt masks to enable and disable MSS
508   MMUART interrupts. They are used to build the value of the irq_mask parameter
509   for the MSS_UART_enable_irq() and MSS_UART_disable_irq() functions. A bitwise
510   OR of these constants is used to enable or disable multiple interrupts.
511 
512 
513   | Constant           | Description                                                   |
514   |--------------------|---------------------------------------------------------------|
515   | MSS_UART_RBF_IRQ   | Receive Data Available Interrupt bit mask (0x001)             |
516   | MSS_UART_TBE_IRQ   | Transmitter Holding Register Empty interrupt bit mask (0x002) |
517   | MSS_UART_LS_IRQ    | Receiver Line Status interrupt bit mask (0x004)               |
518   | MSS_UART_MS_IRQ    | Modem Status interrupt bit mask (0x008)                       |
519   | MSS_UART_RTO_IRQ   | Receiver time-out interrupt bit mask (0x010)                  |
520   | MSS_UART_NACK_IRQ  | NACK / ERR signal interrupt bit mask (0x020)                  |
521   | MSS_UART_PIDPE_IRQ | PID parity error interrupt bit mask (0x040)                   |
522   | MSS_UART_LINB_IRQ  | LIN break detection interrupt bit mask (0x080)                |
523   | MSS_UART_LINS_IRQ  | LIN Sync detection interrupt bit mask (0x100)                 |
524 
525  */
526 #define MSS_UART_RBF_IRQ        0x001
527 #define MSS_UART_TBE_IRQ        0x002
528 #define MSS_UART_LS_IRQ         0x004
529 #define MSS_UART_MS_IRQ         0x008
530 #define MSS_UART_RTO_IRQ        0x010
531 #define MSS_UART_NACK_IRQ       0x020
532 #define MSS_UART_PIDPE_IRQ      0x040
533 #define MSS_UART_LINB_IRQ       0x080
534 #define MSS_UART_LINS_IRQ       0x100
535 #define MSS_UART_INVALID_IRQ    UINT16_MAX
536 
537 /***************************************************************************//**
538   This enumeration specifies the receiver FIFO trigger level. This is the number
539   of bytes that must be received before the UART generates a receive data
540   available interrupt. It provides the allowed values for the
541   MSS_UART_set_rx_handler() function trigger_level parameter.
542  */
543 typedef enum {
544     MSS_UART_FIFO_SINGLE_BYTE    = 0x00,
545     MSS_UART_FIFO_FOUR_BYTES     = 0x40,
546     MSS_UART_FIFO_EIGHT_BYTES    = 0x80,
547     MSS_UART_FIFO_FOURTEEN_BYTES = 0xC0,
548     MSS_UART_FIFO_INVALID_TRIG_LEVEL
549 
550 } mss_uart_rx_trig_level_t;
551 
552 /***************************************************************************//**
553   This enumeration specifies the loopback configuration of the UART. It provides
554   the allowed values for the MSS_UART_set_loopback() function's loopback
555   parameter. Use MSS_UART_LOCAL_LOOPBACK_ON to set up the UART to locally
556   loopback its Tx and Rx lines. Use MSS_UART_REMOTE_LOOPBACK_ON to set up the
557   UART in remote loopback mode.
558  */
559 typedef enum {
560     MSS_UART_LOCAL_LOOPBACK_OFF,
561     MSS_UART_LOCAL_LOOPBACK_ON,
562     MSS_UART_REMOTE_LOOPBACK_OFF,
563     MSS_UART_REMOTE_LOOPBACK_ON,
564     MSS_UART_AUTO_ECHO_OFF,
565     MSS_UART_AUTO_ECHO_ON,
566     MSS_UART_INVALID_LOOPBACK
567 
568 } mss_uart_loopback_t;
569 
570 /***************************************************************************//**
571   IrDA input / output polarity.
572   This enumeration specifies the RZI modem polarity for input and output signals.
573   This is passed as parameters in MSS_UART_irda_init() function.
574  */
575 typedef enum {
576     MSS_UART_ACTIVE_LOW = 0u,
577     MSS_UART_ACTIVE_HIGH = 1u,
578     MSS_UART_INVALID_POLARITY
579 
580 } mss_uart_rzi_polarity_t;
581 
582 /***************************************************************************//**
583   IrDA input / output pulse width.
584   This enumeration specifies the RZI modem pulse width for input and output
585   signals. This is passed as parameters in MSS_UART_irda_init() function.
586  */
587 typedef enum {
588     MSS_UART_3_BY_16 = 0u,
589     MSS_UART_1_BY_4 = 1u,
590     MSS_UART_INVALID_PW
591 
592 } mss_uart_rzi_pulsewidth_t;
593 
594 /***************************************************************************//**
595   Tx / Rx endianess.
596   This enumeration specifies the MSB first or LSB first for MSS UART transmitter
597   and receiver. The parameter of this type shall be passed in
598   MSS_UART_set_rx_endian()and MSS_UART_set_tx_endian() functions.
599  */
600 typedef enum {
601     MSS_UART_LITTLEEND,
602     MSS_UART_BIGEND,
603     MSS_UART_INVALID_ENDIAN
604 
605 } mss_uart_endian_t;
606 
607 /***************************************************************************//**
608   Glitch filter length.
609   This enumeration specifies the glitch filter length. The function
610   MSS_UART_set_filter_length() accepts the parameter of this type.
611  */
612 typedef enum {
613     MSS_UART_LEN0 = 0,
614     MSS_UART_LEN1 = 1,
615     MSS_UART_LEN2 = 2,
616     MSS_UART_LEN3 = 3,
617     MSS_UART_LEN4 = 4,
618     MSS_UART_LEN5 = 5,
619     MSS_UART_LEN6 = 6,
620     MSS_UART_LEN7 = 7,
621     MSS_UART_INVALID_FILTER_LENGTH = 8
622 
623 } mss_uart_filter_length_t;
624 
625 /***************************************************************************//**
626   TXRDY and RXRDY mode.
627   This enumeration specifies the TXRDY and RXRDY signal modes. The function
628   MSS_UART_set_ready_mode() accepts the parameter of this type.
629  */
630 typedef enum {
631     MSS_UART_READY_MODE0,
632     MSS_UART_READY_MODE1,
633     MSS_UART_INVALID_READY_MODE
634 
635 } mss_uart_ready_mode_t;
636 
637 /***************************************************************************//**
638   USART mode of operation.
639   This enumeration specifies the mode of operation of MSS UART when operating
640   as USART. The function MSS_UART_set_usart_mode() accepts the parameter of this
641   type.
642  */
643 typedef enum {
644     MSS_UART_ASYNC_MODE               = 0,
645     MSS_UART_SYNC_SLAVE_POS_EDGE_CLK  = 1,
646     MSS_UART_SYNC_SLAVE_NEG_EDGE_CLK  = 2,
647     MSS_UART_SYNC_MASTER_POS_EDGE_CLK = 3,
648     MSS_UART_SYNC_MASTER_NEG_EDGE_CLK = 4,
649     MSS_UART_INVALID_SYNC_MODE        = 5
650 
651 } mss_uart_usart_mode_t;
652 
653 
654 typedef enum {
655     MSS_UART0_LO    = 0,
656     MSS_UART1_LO    = 1,
657     MSS_UART2_LO    = 2,
658     MSS_UART3_LO    = 3,
659     MSS_UART4_LO    = 4,
660     MSS_UART0_HI    = 5,
661     MSS_UART1_HI    = 6,
662     MSS_UART2_HI    = 7,
663     MSS_UART3_HI    = 8,
664     MSS_UAR4_HI     = 9,
665 
666 } mss_uart_num_t;
667 
668 /***************************************************************************//**
669   MSS UART instance type.
670   This is type definition for MSS UART instance. You need to create and
671   maintain a record of this type. This holds all data regarding the MSS UART
672   instance
673  */
674 typedef struct  mss_uart_instance mss_uart_instance_t;
675 
676 /***************************************************************************//**
677   Interrupt handler prototype.
678   This typedef specifies the function prototype for MSS UART interrupt handlers.
679   All interrupt handlers registered with the MSS UART driver must be of this type.
680   The interrupt handlers are registered with the driver through the
681   MSS_UART_set_rx_handler(), MSS_UART_set_tx_handler(),
682   MSS_UART_set_rxstatus_handler(), and MSS_UART_set_modemstatus_handler()
683   functions.
684   The this_uart parameter is a pointer to either g_mss_uart0 or g_mss_uart1 to
685   identify the MSS UART to associate with the handler function.
686  */
687 typedef void (*mss_uart_irq_handler_t)( mss_uart_instance_t * this_uart );
688 
689 /*----------------------------------------------------------------------------*/
690 /*----------------------------------- UART -----------------------------------*/
691 /*----------------------------------------------------------------------------*/
692 
693 typedef struct
694 {
695     union
696     {
697         volatile const uint8_t    RBR;
698         volatile uint8_t    THR;
699         volatile uint8_t    DLR;
700         uint32_t RESERVED0;
701     };
702 
703     union
704     {
705         volatile uint8_t  DMR;
706         volatile uint8_t  IER;
707         uint32_t RESERVED1;
708     };
709 
710     union
711     {
712         volatile uint8_t  IIR;
713         volatile uint8_t  FCR;
714         uint32_t RESERVED2;
715     };
716 
717     volatile uint8_t  LCR;
718     uint8_t  RESERVED3[3];
719 
720     volatile uint8_t  MCR;
721     uint8_t  RESERVED4[3];
722 
723     volatile const  uint8_t  LSR;
724     uint8_t  RESERVED5[3];
725 
726     volatile const  uint8_t  MSR;
727     uint8_t  RESERVED6[3];
728 
729     volatile uint8_t  SR;
730     uint8_t  RESERVED7[7];
731 
732     volatile uint8_t  IEM;
733     uint8_t  RESERVED8[3];
734 
735     volatile uint8_t  IIM;
736     uint8_t  RESERVED9[7];
737 
738     volatile uint8_t  MM0;
739     uint8_t  RESERVED10[3];
740 
741     volatile uint8_t  MM1;
742     uint8_t  RESERVED11[3];
743 
744     volatile uint8_t  MM2;
745     uint8_t  RESERVED12[3];
746 
747     volatile uint8_t  DFR;
748     uint8_t  RESERVED13[7];
749 
750     volatile uint8_t GFR;
751     uint8_t  RESERVED14[3];
752 
753     volatile uint8_t TTG;
754     uint8_t  RESERVED15[3];
755 
756     volatile uint8_t RTO;
757     uint8_t  RESERVED16[3];
758 
759     volatile uint8_t ADR;
760     uint8_t  RESERVED17[3];
761 
762 } MSS_UART_TypeDef;
763 
764 
765 /***************************************************************************//**
766   mss_uart_instance.
767   There is one instance of this structure for each instance of the
768   microprocessor subsystem's UARTs. Instances of this structure are used to
769   identify a specific UART. A pointer to an initialized instance of the
770   mss_uart_instance_t structure is passed as the first parameter to
771   MSS UART driver functions to identify which UART should perform the
772   requested operation.
773  */
774 struct mss_uart_instance{
775     /* CMSIS related defines identifying the UART hardware. */
776     MSS_UART_TypeDef *      hw_reg;     /*!< Pointer to UART registers. */
777     uint32_t                baudrate;   /*!< Operating baud rate. */
778     uint8_t                 lineconfig; /*!< Line configuration parameters. */
779     uint8_t                 status;     /*!< Sticky line status. */
780 
781     /* transmit related info (used with interrupt driven transmit): */
782     const uint8_t * tx_buffer;          /*!< Pointer to transmit buffer. */
783     uint32_t        tx_buff_size;       /*!< Transmit buffer size. */
784     uint32_t        tx_idx;             /*!< Index within transmit buffer of next byte to transmit.*/
785 
786     /* line status interrupt handler:*/
787     mss_uart_irq_handler_t linests_handler;   /*!< Pointer to user registered line status handler. */
788     /* receive interrupt handler:*/
789     mss_uart_irq_handler_t rx_handler;        /*!< Pointer to user registered receiver handler. */
790     /* transmit interrupt handler:*/
791     mss_uart_irq_handler_t tx_handler;        /*!< Pointer to user registered transmit handler. */
792     /* modem status interrupt handler:*/
793     mss_uart_irq_handler_t modemsts_handler;  /*!< Pointer to user registered modem status handler. */
794     /* receiver timeout interrupt handler */
795     mss_uart_irq_handler_t rto_handler;       /*!< Pointer to user registered receiver timeout handler. */
796     /* NACK interrupt handler */
797     mss_uart_irq_handler_t nack_handler;      /*!< Pointer to user registered NACK handler. */
798     /* PID parity perror interrupt handler */
799     mss_uart_irq_handler_t pid_pei_handler;   /*!< Pointer to user registered PID parity error handler. */
800     /* LIN break interrupt handler */
801     mss_uart_irq_handler_t break_handler;     /*!< Pointer to user registered LIN break handler. */
802     /* LIN sync detection interrupt handler */
803     mss_uart_irq_handler_t sync_handler;      /*!< Pointer to user registered LIN sync detection handler. */
804     uint8_t                local_irq_enabled;  /*!< check if local interrupt were enabled on this instance*/
805     void* user_data;                          /*!< Pointer to user provided pointer for user specific use. */
806 
807 };
808 
809 /***************************************************************************//**
810   This instance of mss_uart_instance_t holds all data related to the operations
811   performed by the MMUART. The function MSS_UART_init() initializes this structure.
812   A pointer to g_mss_uart0_lo is passed as the first parameter to MSS UART driver
813   functions to indicate that MMUART0 should perform the requested operation.
814  */
815 
816 extern mss_uart_instance_t g_mss_uart0_lo;
817 extern mss_uart_instance_t g_mss_uart1_lo;
818 extern mss_uart_instance_t g_mss_uart2_lo;
819 extern mss_uart_instance_t g_mss_uart3_lo;
820 extern mss_uart_instance_t g_mss_uart4_lo;
821 
822 extern mss_uart_instance_t g_mss_uart0_hi;
823 extern mss_uart_instance_t g_mss_uart1_hi;
824 extern mss_uart_instance_t g_mss_uart2_hi;
825 extern mss_uart_instance_t g_mss_uart3_hi;
826 extern mss_uart_instance_t g_mss_uart4_hi;
827 
828 
829 /***************************************************************************//**
830   The MSS_UART_init() function initializes and configures one of the PolarFire SoC
831   MSS UARTs with the configuration passed as a parameter. The configuration
832   parameters are the baud_rate which is used to generate the baud value and the
833   line_config which is used to specify the line configuration (bit length,
834   stop bits and parity).
835 
836   @param this_uart
837     The this_uart parameter is a pointer to an mss_uart_instance_t
838     structure identifying the MSS UART hardware block that will perform
839     the requested function. There are ten such data structures,
840     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
841     when they are connected on the AXI switch slave 5 (main APB bus) and
842     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
843     when they are connected on the AXI switch slave 6 (AMP APB bus).
844     This parameter must point to one of these ten global data structure defined
845     within the UART driver.
846 
847     Note that if you are using the UART on the AMP APB bus, the hardware
848     configuration to connect UART on AMP APB bus must already be done by the
849     application using SYSREG registers before initializing the UART instance
850     structure.
851 
852   @param baud_rate
853     The baud_rate parameter specifies the baud rate. It can be specified for
854     common baud rates using the following defines:
855     - MSS_UART_110_BAUD
856     - MSS_UART_300_BAUD
857     - MSS_UART_600_BAUD
858     - MSS_UART_1200_BAUD
859     - MSS_UART_2400_BAUD
860     - MSS_UART_4800_BAUD
861     - MSS_UART_9600_BAUD
862     - MSS_UART_19200_BAUD
863     - MSS_UART_38400_BAUD
864     - MSS_UART_57600_BAUD
865     - MSS_UART_115200_BAUD
866     - MSS_UART_230400_BAUD
867     - MSS_UART_460800_BAUD
868     - MSS_UART_921600_BAUD
869 
870     Alternatively, any nonstandard baud rate can be specified by simply passing
871     the actual required baud rate as the value for this parameter.
872 
873   @param line_config
874     The line_config parameter is the line configuration specifying the bit length,
875     number of stop bits and parity settings.
876 
877     This is a bitwise OR of one value from each of the following groups of
878     allowed values:
879 
880     One of the following to specify the transmit/receive data bit length:
881      - MSS_UART_DATA_5_BITS
882      - MSS_UART_DATA_6_BITS,
883      - MSS_UART_DATA_7_BITS
884      - MSS_UART_DATA_8_BITS
885 
886     One of the following to specify the parity setting:
887      - MSS_UART_NO_PARITY
888      - MSS_UART_EVEN_PARITY
889      - MSS_UART_ODD_PARITY
890      - MSS_UART_STICK_PARITY_0
891      - MSS_UART_STICK_PARITY_1
892 
893     One of the following to specify the number of stop bits:
894      - MSS_UART_ONE_STOP_BIT
895      - MSS_UART_ONEHALF_STOP_BIT
896      - MSS_UART_TWO_STOP_BITS
897 
898   @return
899     This function does not return a value.
900 
901   Example:
902   @code
903   #include "mss_uart.h"
904 
905   int main(void)
906   {
907     MSS_UART_init(&g_mss_uart0_lo,
908              MSS_UART_57600_BAUD,
909              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
910 
911      return(0);
912   }
913   @endcode
914  */
915 void
916 MSS_UART_init
917 (
918     mss_uart_instance_t* this_uart,
919     uint32_t baud_rate,
920     uint8_t line_config
921 );
922 
923 /***************************************************************************//**
924  The MSS_UART_lin_init() function is used to initialize the MSS UART for
925  LIN mode of operation. The configuration parameters are the baud_rate which is
926  used to generate the baud value and the line_config which is used to specify
927  the line configuration (bit length, stop bits and parity).
928 
929   @param this_uart
930     The this_uart parameter is a pointer to an mss_uart_instance_t
931     structure identifying the MSS UART hardware block that will perform
932     the requested function. There are ten such data structures,
933     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
934     when they are connected on the AXI switch slave 5 (main APB bus) and
935     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
936     when they are connected on the AXI switch slave 6 (AMP APB bus).
937     This parameter must point to one of these ten global data structure defined
938     within the UART driver.
939 
940     Note that if you are using the UART on the AMP APB bus, the hardware
941     configuration to connect UART on AMP APB bus must already be done by the
942     application using SYSREG registers before initializing the UART instance
943     structure.
944 
945   @param baud_rate
946     The baud_rate parameter specifies the baud rate. It can be specified for
947     common baud rates using the following defines:
948     - MSS_UART_110_BAUD
949     - MSS_UART_300_BAUD
950     - MSS_UART_600_BAUD
951     - MSS_UART_1200_BAUD
952     - MSS_UART_2400_BAUD
953     - MSS_UART_4800_BAUD
954     - MSS_UART_9600_BAUD
955     - MSS_UART_19200_BAUD
956     - MSS_UART_38400_BAUD
957     - MSS_UART_57600_BAUD
958     - MSS_UART_115200_BAUD
959     - MSS_UART_230400_BAUD
960     - MSS_UART_460800_BAUD
961     - MSS_UART_921600_BAUD
962 
963     Alternatively, any nonstandard baud rate can be specified by simply passing
964     the actual required baud rate as the value for this parameter.
965 
966   @param line_config
967     The line_config parameter is the line configuration specifying the bit length,
968     number of stop bits and parity settings.
969 
970     This is a bitwise OR of one value from each of the following groups of
971     allowed values:
972 
973     One of the following to specify the transmit/receive data bit length:
974      - MSS_UART_DATA_5_BITS
975      - MSS_UART_DATA_6_BITS,
976      - MSS_UART_DATA_7_BITS
977      - MSS_UART_DATA_8_BITS
978 
979     One of the following to specify the parity setting:
980      - MSS_UART_NO_PARITY
981      - MSS_UART_EVEN_PARITY
982      - MSS_UART_ODD_PARITY
983      - MSS_UART_STICK_PARITY_0
984      - MSS_UART_STICK_PARITY_1
985 
986     One of the following to specify the number of stop bits:
987      - MSS_UART_ONE_STOP_BIT
988      - MSS_UART_ONEHALF_STOP_BIT
989      - MSS_UART_TWO_STOP_BITS
990 
991   @return
992     This function does not return a value.
993 
994   Example:
995   @code
996   #include "mss_uart.h"
997 
998   int main(void)
999   {
1000      MSS_UART_lin_init(&g_mss_uart0_lo,
1001              MSS_UART_57600_BAUD,
1002              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1003 
1004      return(0);
1005   }
1006   @endcode
1007  */
1008 void
1009 MSS_UART_lin_init
1010 (
1011     mss_uart_instance_t* this_uart,
1012     uint32_t baud_rate,
1013     uint8_t line_config
1014 );
1015 
1016 /***************************************************************************//**
1017   The MSS_UART_irda_init() function is used to initialize the MSS UART instance
1018   referenced by the parameter this_uart  for IrDA mode of operation. This
1019   function must be called before calling any other IrDA functionality specific
1020   functions.
1021 
1022   @param this_uart
1023     The this_uart parameter is a pointer to an mss_uart_instance_t
1024     structure identifying the MSS UART hardware block that will perform
1025     the requested function. There are ten such data structures,
1026     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1027     when they are connected on the AXI switch slave 5 (main APB bus) and
1028     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1029     when they are connected on the AXI switch slave 6 (AMP APB bus).
1030     This parameter must point to one of these ten global data structure defined
1031     within the UART driver.
1032 
1033     Note that if you are using the UART on the AMP APB bus, the hardware
1034     configuration to connect UART on AMP APB bus must already be done by the
1035     application using SYSREG registers before initializing the UART instance
1036     structure.
1037 
1038   @param baud_rate
1039     The baud_rate parameter specifies the baud rate. It can be specified for
1040     common baud rates using the following defines:
1041     - MSS_UART_110_BAUD
1042     - MSS_UART_300_BAUD
1043     - MSS_UART_600_BAUD
1044     - MSS_UART_1200_BAUD
1045     - MSS_UART_2400_BAUD
1046     - MSS_UART_4800_BAUD
1047     - MSS_UART_9600_BAUD
1048     - MSS_UART_19200_BAUD
1049     - MSS_UART_38400_BAUD
1050     - MSS_UART_57600_BAUD
1051     - MSS_UART_115200_BAUD
1052     - MSS_UART_230400_BAUD
1053     - MSS_UART_460800_BAUD
1054     - MSS_UART_921600_BAUD
1055 
1056     Alternatively, any nonstandard baud rate can be specified by simply passing
1057     the actual required baud rate as the value for this parameter.
1058 
1059   @param line_config
1060     The line_config parameter is the line configuration specifying the bit
1061     length, number of stop bits and parity settings.
1062 
1063     This is a bitwise OR of one value from each of the following groups of
1064     allowed values:
1065 
1066     One of the following to specify the transmit/receive data bit length:
1067      - MSS_UART_DATA_5_BITS
1068      - MSS_UART_DATA_6_BITS,
1069      - MSS_UART_DATA_7_BITS
1070      - MSS_UART_DATA_8_BITS
1071 
1072     One of the following to specify the parity setting:
1073      - MSS_UART_NO_PARITY
1074      - MSS_UART_EVEN_PARITY
1075      - MSS_UART_ODD_PARITY
1076      - MSS_UART_STICK_PARITY_0
1077      - MSS_UART_STICK_PARITY_1
1078 
1079     One of the following to specify the number of stop bits:
1080      - MSS_UART_ONE_STOP_BIT
1081      - MSS_UART_ONEHALF_STOP_BIT
1082      - MSS_UART_TWO_STOP_BITS
1083 
1084   @return
1085     This function does not return a value.
1086 
1087   Example:
1088   @code
1089     MSS_UART_irda_init(&g_mss_uart0_lo,
1090               MSS_UART_57600_BAUD,
1091               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT,
1092               MSS_UART_ACTIVE_LOW,
1093               MSS_UART_ACTIVE_LOW,
1094               MSS_UART_3_BY_16);
1095   @endcode
1096  */
1097 void
1098 MSS_UART_irda_init
1099 (
1100     mss_uart_instance_t* this_uart,
1101     uint32_t baud_rate,
1102     uint8_t line_config,
1103     mss_uart_rzi_polarity_t rxpol,
1104     mss_uart_rzi_polarity_t txpol,
1105     mss_uart_rzi_pulsewidth_t pw
1106 );
1107 
1108 /***************************************************************************//**
1109   The MSS_UART_smartcard_init() function is used to initialize the MSS UART
1110   for ISO 7816 (smartcard) mode of operation. The configuration parameters are
1111   the baud_rate which is used to generate the baud value and the line_config
1112   which is used to specify the line configuration (bit length, stop bits and
1113   parity). This function disables all other modes of the MSS UART instance
1114   pointed by the parameter this_uart.
1115 
1116   @param this_uart
1117     The this_uart parameter is a pointer to an mss_uart_instance_t
1118     structure identifying the MSS UART hardware block that will perform
1119     the requested function. There are ten such data structures,
1120     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1121     when they are connected on the AXI switch slave 5 (main APB bus) and
1122     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1123     when they are connected on the AXI switch slave 6 (AMP APB bus).
1124     This parameter must point to one of these ten global data structure defined
1125     within the UART driver.
1126 
1127     Note that if you are using the UART on the AMP APB bus, the hardware
1128     configuration to connect UART on AMP APB bus must already be done by the
1129     application using SYSREG registers before initializing the UART instance
1130     structure.
1131 
1132   @param baud_rate
1133     The baud_rate parameter specifies the baud rate. It can be specified for
1134     common baud rates using the following defines:
1135     - MSS_UART_110_BAUD
1136     - MSS_UART_300_BAUD
1137     - MSS_UART_600_BAUD
1138     - MSS_UART_1200_BAUD
1139     - MSS_UART_2400_BAUD
1140     - MSS_UART_4800_BAUD
1141     - MSS_UART_9600_BAUD
1142     - MSS_UART_19200_BAUD
1143     - MSS_UART_38400_BAUD
1144     - MSS_UART_57600_BAUD
1145     - MSS_UART_115200_BAUD
1146     - MSS_UART_230400_BAUD
1147     - MSS_UART_460800_BAUD
1148     - MSS_UART_921600_BAUD
1149 
1150     Alternatively, any nonstandard baud rate can be specified by simply passing
1151     the actual required baud rate as the value for this parameter.
1152 
1153   @param line_config
1154     The line_config parameter is the line configuration specifying the bit
1155     length, number of stop bits and parity settings.
1156 
1157     This is a bitwise OR of one value from each of the following groups of
1158     allowed values:
1159 
1160     One of the following to specify the transmit/receive data bit length:
1161      - MSS_UART_DATA_5_BITS
1162      - MSS_UART_DATA_6_BITS,
1163      - MSS_UART_DATA_7_BITS
1164      - MSS_UART_DATA_8_BITS
1165 
1166     One of the following to specify the parity setting:
1167      - MSS_UART_NO_PARITY
1168      - MSS_UART_EVEN_PARITY
1169      - MSS_UART_ODD_PARITY
1170      - MSS_UART_STICK_PARITY_0
1171      - MSS_UART_STICK_PARITY_1
1172 
1173     One of the following to specify the number of stop bits:
1174      - MSS_UART_ONE_STOP_BIT
1175      - MSS_UART_ONEHALF_STOP_BIT
1176      - MSS_UART_TWO_STOP_BITS
1177 
1178   @return
1179     This function does not return a value.
1180 
1181   Example:
1182   @code
1183     #include "mss_uart.h"
1184 
1185       int main(void)
1186       {
1187          MSS_UART_smartcard_init(&g_mss_uart0_lo,
1188               MSS_UART_57600_BAUD,
1189               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1190 
1191          return(0);
1192       }
1193   @endcode
1194  */
1195 void
1196 MSS_UART_smartcard_init
1197 (
1198     mss_uart_instance_t* this_uart,
1199     uint32_t baud_rate,
1200     uint8_t line_config
1201 );
1202 
1203 /***************************************************************************//**
1204   The function MSS_UART_polled_tx() is used to transmit data. It transfers the
1205   contents of the transmitter data buffer, passed as a function parameter, into
1206   the UART's hardware transmitter FIFO. It returns when the full content of the
1207   transmit data buffer has been transferred to the UART's transmit FIFO. It is
1208   safe to release or reuse the memory used as the transmitter data buffer once
1209   this function returns.
1210 
1211   Note:     This function reads the UART's line status register (LSR) to poll
1212   for the active state of the transmitter holding register empty (THRE) bit
1213   before transferring data from the data buffer to the transmitter FIFO. It
1214   transfers data to the transmitter FIFO in blocks of 16 bytes or less and
1215   allows the FIFO to empty before transferring the next block of data.
1216 
1217   Note:     The actual transmission over the serial connection will still be
1218   in progress when this function returns. Use the MSS_UART_get_tx_status()
1219   function if you need to know when the transmitter is empty.
1220 
1221   @param this_uart
1222     The this_uart parameter is a pointer to an mss_uart_instance_t
1223     structure identifying the MSS UART hardware block that will perform
1224     the requested function. There are ten such data structures,
1225     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1226     when they are connected on the AXI switch slave 5 (main APB bus) and
1227     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1228     when they are connected on the AXI switch slave 6 (AMP APB bus).
1229     This parameter must point to one of these ten global data structure defined
1230     within the UART driver.
1231 
1232   @param pbuff
1233     The pbuff parameter is a pointer to a buffer containing the data to
1234     be transmitted.
1235 
1236   @param tx_size
1237     The tx_size parameter specifies the size, in bytes, of the data to
1238     be transmitted.
1239 
1240   @return
1241     This function does not return a value.
1242 
1243   Example:
1244   @code
1245   #include "mss_uart.h"
1246 
1247   int main(void)
1248   {
1249      uint8_t message[12] = "Hello World";
1250 
1251      MSS_UART_init(&g_mss_uart0_lo,
1252               MSS_UART_57600_BAUD,
1253               SS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1254 
1255      MSS_UART_polled_tx(&g_mss_uart0_lo, message, sizeof(message));
1256 
1257      return(0);
1258   }
1259   @endcode
1260  */
1261 void
1262 MSS_UART_polled_tx
1263 (
1264     mss_uart_instance_t * this_uart,
1265     const uint8_t * pbuff,
1266     uint32_t tx_size
1267 );
1268 
1269 /***************************************************************************//**
1270   The function MSS_UART_polled_tx_string() is used to transmit a NUL ('\0')
1271   terminated string. It transfers the text string, from the buffer starting at
1272   the address pointed to by p_sz_string into the UART's hardware transmitter
1273   FIFO. It returns when the complete string has been transferred to the UART's
1274   transmit FIFO. It is safe to release or reuse the memory used as the string
1275   buffer once this function returns.
1276 
1277   Note:     This function reads the UART's line status register (LSR) to poll
1278   for the active state of the transmitter holding register empty (THRE) bit
1279   before transferring data from the data buffer to the transmitter FIFO. It
1280   transfers data to the transmitter FIFO in blocks of 16 bytes or less and
1281   allows the FIFO to empty before transferring the next block of data.
1282 
1283   Note:     The actual transmission over the serial connection will still be
1284   in progress when this function returns. Use the MSS_UART_get_tx_status()
1285   function if you need to know when the transmitter is empty.
1286 
1287   @param this_uart
1288     The this_uart parameter is a pointer to an mss_uart_instance_t
1289     structure identifying the MSS UART hardware block that will perform
1290     the requested function. There are ten such data structures,
1291     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1292     when they are connected on the AXI switch slave 5 (main APB bus) and
1293     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1294     when they are connected on the AXI switch slave 6 (AMP APB bus).
1295     This parameter must point to one of these ten global data structure defined
1296     within the UART driver.
1297 
1298   @param p_sz_string
1299     The p_sz_string parameter is a pointer to a buffer containing the NUL ('\0')
1300     terminated string to be transmitted.
1301 
1302   @return
1303     This function does not return a value.
1304 
1305   Example:
1306   @code
1307   #include "mss_uart.h"
1308 
1309   int main(void)
1310   {
1311      uint8_t message[12] = "Hello World";
1312 
1313      MSS_UART_init(&g_mss_uart0_lo,
1314              MSS_UART_57600_BAUD,
1315              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1316 
1317      MSS_UART_polled_tx_string(&g_mss_uart0_lo, message);
1318 
1319      return(0);
1320   }
1321   @endcode
1322 
1323  */
1324 void
1325 MSS_UART_polled_tx_string
1326 (
1327     mss_uart_instance_t * this_uart,
1328     const uint8_t * p_sz_string
1329 );
1330 
1331 /***************************************************************************//**
1332   The function MSS_UART_irq_tx() is used to initiate an interrupt-driven
1333   transmit. It returns immediately after making a note of the transmit buffer
1334   location and enabling transmit interrupts both at the UART and the PolarFire
1335   SoC Core Complex PLIC level. This function takes a pointer via the pbuff
1336   parameter to a memory buffer containing the data to transmit. The memory
1337   buffer specified through this pointer must remain allocated and contain the
1338   data to transmit until the transmit completion has been detected through calls
1339   to function MSS_UART_tx_complete(). The actual transmission over the serial
1340   connection is still in progress until calls to the MSS_UART_tx_complete()
1341   function indicate transmit completion.
1342 
1343   Note:     The MSS_UART_irq_tx() function enables both the transmit holding
1344   register empty (THRE) interrupt in the UART and the MSS UART instance
1345   interrupt in the PolarFire SoC Core Complex PLIC as part of its implementation.
1346 
1347   Note:     The MSS_UART_irq_tx() function assigns an internal default transmit
1348   interrupt handler function to the UART's THRE interrupt. This interrupt
1349   handler overrides any custom interrupt handler that you may have previously
1350   registered using the MSS_UART_set_tx_handler() function.
1351 
1352   Note:     The MSS_UART_irq_tx() function's default transmit interrupt
1353   handler disables the UART's THRE interrupt when all of the data has
1354   been transferred to the UART's transmit FIFO.
1355 
1356 
1357   @param this_uart
1358     The this_uart parameter is a pointer to an mss_uart_instance_t
1359     structure identifying the MSS UART hardware block that will perform
1360     the requested function. There are ten such data structures,
1361     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1362     when they are connected on the AXI switch slave 5 (main APB bus) and
1363     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1364     when they are connected on the AXI switch slave 6 (AMP APB bus).
1365     This parameter must point to one of these ten global data structure defined
1366     within the UART driver.
1367 
1368   @param pbuff
1369     The pbuff parameter is a pointer to a buffer containing the data
1370     to be transmitted.
1371 
1372   @param tx_size
1373     The tx_size parameter specifies the size, in bytes, of the data
1374     to be transmitted.
1375 
1376   @return
1377     This function does not return a value.
1378 
1379   Example:
1380   @code
1381   #include "mss_uart.h"
1382 
1383   int main(void)
1384   {
1385      uint8_t tx_buff[10] = "abcdefghi";
1386 
1387      MSS_UART_init(&g_mss_uart0_lo,
1388               MSS_UART_57600_BAUD,
1389               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1390 
1391      MSS_UART_irq_tx(&g_mss_uart0_lo, tx_buff, sizeof(tx_buff));
1392 
1393      while(0 == MSS_UART_tx_complete(&g_mss_uart0_lo))
1394      {
1395          ;
1396      }
1397      return(0);
1398   }
1399   @endcode
1400  */
1401 void
1402 MSS_UART_irq_tx
1403 (
1404     mss_uart_instance_t * this_uart,
1405     const uint8_t * pbuff,
1406     uint32_t tx_size
1407 );
1408 
1409 /***************************************************************************//**
1410   The MSS_UART_tx_complete() function is used to find out if the
1411   interrupt-driven transmit previously initiated through a call to
1412   MSS_UART_irq_tx() is complete. This is typically used to find out when it is
1413   safe to reuse or release the memory buffer holding transmit data.
1414 
1415   Note:     The transfer of all of the data from the memory buffer to the UART's
1416   transmit FIFO and the actual transmission over the serial connection are both
1417   complete when a call to the MSS_UART_tx_complete() function indicates transmit
1418   completion.
1419 
1420   @param this_uart
1421     The this_uart parameter is a pointer to an mss_uart_instance_t
1422     structure identifying the MSS UART hardware block that will perform
1423     the requested function. There are ten such data structures,
1424     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1425     when they are connected on the AXI switch slave 5 (main APB bus) and
1426     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1427     when they are connected on the AXI switch slave 6 (AMP APB bus).
1428     This parameter must point to one of these ten global data structure defined
1429     within the UART driver.
1430 
1431   @return
1432     This function return a non-zero value if transmit has completed, otherwise
1433     it returns zero.
1434 
1435   Example:
1436     See the MSS_UART_irq_tx() function for an example that uses the
1437     MSS_UART_tx_complete() function.
1438 
1439  */
1440 int8_t
1441 MSS_UART_tx_complete
1442 (
1443    mss_uart_instance_t * this_uart
1444 );
1445 
1446 /***************************************************************************//**
1447   The MSS_UART_get_rx() function reads the content of the UART receiver's FIFO
1448   and stores it in the receive buffer that is passed via the rx_buff function
1449   parameter. It copies either the full contents of the FIFO into the receive
1450   buffer, or just enough data from the FIFO to fill the receive buffer,
1451   dependent upon the size of the receive buffer passed by the buff_size
1452   parameter. The MSS_UART_get_rx() function returns the number of bytes copied
1453   into the receive buffer .This function is non-blocking and will return 0
1454   immediately if no data has been received.
1455 
1456   Note:     The MSS_UART_get_rx() function reads and accumulates the receiver
1457   status of the MSS UART instance before reading each byte from the receiver's
1458   data register/FIFO. This allows the driver to maintain a sticky record of any
1459   receiver errors that occur as the UART receives each data byte; receiver
1460   errors would otherwise be lost after each read from the receiver's data
1461   register. A call to the MSS_UART_get_rx_status() function returns any receiver
1462   errors accumulated during the execution of the MSS_UART_get_rx() function.
1463 
1464   Note:     If you need to read the error status for each byte received, set
1465   the buff_size to 1 and read the receive line error status for each byte
1466   using the MSS_UART_get_rx_status() function.
1467 
1468   The MSS_UART_get_rx() function can be used in polled mode, where it is called
1469   at regular intervals to find out if any data has been received, or in
1470   interrupt driven-mode, where it is called as part of a receive handler that is
1471   called by the driver as a result of data being received.
1472 
1473   Note:     In interrupt driven mode you should call the MSS_UART_get_rx()
1474   function as part of the receive handler function that you register with
1475   the MSS UART driver through a call to MSS_UART_set_rx_handler().
1476 
1477   @param this_uart
1478     The this_uart parameter is a pointer to an mss_uart_instance_t
1479     structure identifying the MSS UART hardware block that will perform
1480     the requested function. There are ten such data structures,
1481     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1482     when they are connected on the AXI switch slave 5 (main APB bus) and
1483     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1484     when they are connected on the AXI switch slave 6 (AMP APB bus).
1485     This parameter must point to one of these ten global data structure defined
1486     within the UART driver.
1487 
1488   @param rx_buff
1489     The rx_buff parameter is a pointer to a buffer where the received
1490     data is copied.
1491 
1492   @param buff_size
1493     The buff_size parameter specifies the size of the receive buffer in bytes.
1494 
1495   @return
1496     This function returns the number of bytes that were copied into the
1497     rx_buff buffer. It returns 0 if no data has been received.
1498 
1499   Polled mode example:
1500   @code
1501    int main( void )
1502    {
1503       uint8_t rx_buff[RX_BUFF_SIZE];
1504       uint32_t rx_idx  = 0;
1505 
1506       MSS_UART_init(&g_mss_uart0_lo,
1507              MSS_UART_57600_BAUD,
1508              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1509 
1510       while(1)
1511       {
1512           rx_size = MSS_UART_get_rx(&g_mss_uart0_lo, rx_buff, sizeof(rx_buff));
1513           if(rx_size > 0)
1514           {
1515               process_rx_data(rx_buff, rx_size);
1516           }
1517           task_a();
1518           task_b();
1519       }
1520       return 0;
1521    }
1522   @endcode
1523 
1524   Interrupt driven example:
1525   @code
1526    int main( void )
1527    {
1528       MSS_UART_init(&g_mss_uart1,
1529               MSS_UART_57600_BAUD,
1530               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1531 
1532       MSS_UART_set_rx_handler(&g_mss_uart1,
1533                               uart1_rx_handler,
1534                               MSS_UART_FIFO_SINGLE_BYTE);
1535 
1536       while(1)
1537       {
1538           task_a();
1539           task_b();
1540       }
1541       return 0;
1542    }
1543 
1544    void uart1_rx_handler(mss_uart_instance_t * this_uart)
1545    {
1546       uint8_t rx_buff[RX_BUFF_SIZE];
1547       uint32_t rx_idx  = 0;
1548       rx_size = MSS_UART_get_rx(this_uart, rx_buff, sizeof(rx_buff));
1549       process_rx_data(rx_buff, rx_size);
1550    }
1551   @endcode
1552  */
1553 size_t
1554 MSS_UART_get_rx
1555 (
1556    mss_uart_instance_t * this_uart,
1557    uint8_t * rx_buff,
1558    size_t buff_size
1559 );
1560 
1561 /***************************************************************************//**
1562   The MSS_UART_set_rx_handler() function is used to register a receive handler
1563   function that is called by the driver when a UART receive data available (RDA)
1564   interrupt occurs. You must create and register the receive handler function
1565   to suit your application and it must include a call to the MSS_UART_get_rx()
1566   function to actually read the received data.
1567 
1568   Note:     The MSS_UART_set_rx_handler() function enables both the RDA
1569   interrupt in the MSS UART instance. It also enables the corresponding
1570   MSS UART instance interrupt in the PolarFire SoC Core Complex PLIC  as part
1571   of its implementation.
1572 
1573   Note:     You can disable the RDA interrupt when required by calling the
1574   MSS_UART_disable_irq() function. This is your choice and is dependent upon
1575   your application.
1576 
1577   @param this_uart
1578     The this_uart parameter is a pointer to an mss_uart_instance_t
1579     structure identifying the MSS UART hardware block that will perform
1580     the requested function. There are ten such data structures,
1581     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1582     when they are connected on the AXI switch slave 5 (main APB bus) and
1583     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1584     when they are connected on the AXI switch slave 6 (AMP APB bus).
1585     This parameter must point to one of these ten global data structure defined
1586     within the UART driver.
1587 
1588   @param handler
1589     The handler parameter is a pointer to a receive interrupt handler function
1590     provided by your application that will be called as a result of a UART RDA
1591     interrupt. This handler function must be of type mss_uart_irq_handler_t.
1592 
1593   @param trigger_level
1594     The trigger_level parameter is the receive FIFO trigger level. This
1595     specifies the number of bytes that must be received before the UART
1596     triggers an RDA interrupt.
1597 
1598   @return
1599     This function does not return a value.
1600 
1601   Example:
1602   @code
1603   #include "mss_uart.h"
1604 
1605   #define RX_BUFF_SIZE    64
1606 
1607   uint8_t g_rx_buff[RX_BUFF_SIZE];
1608 
1609   void uart0_rx_handler(mss_uart_instance_t * this_uart)
1610   {
1611       MSS_UART_get_rx(this_uart, &g_rx_buff[g_rx_idx], sizeof(g_rx_buff));
1612   }
1613 
1614   int main(void)
1615   {
1616       MSS_UART_init(&g_mss_uart0_lo,
1617              MSS_UART_57600_BAUD,
1618              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1619 
1620       MSS_UART_set_rx_handler(&g_mss_uart0_lo,
1621                               uart0_rx_handler,
1622                               MSS_UART_FIFO_SINGLE_BYTE);
1623 
1624       while(1)
1625       {
1626          ;
1627       }
1628       return(0);
1629    }
1630   @endcode
1631  */
1632 void
1633 MSS_UART_set_rx_handler
1634 (
1635     mss_uart_instance_t *       this_uart,
1636     mss_uart_irq_handler_t          handler,
1637     mss_uart_rx_trig_level_t    trigger_level
1638 );
1639 
1640 /***************************************************************************//**
1641   The MSS_UART_set_loopback() function is used to locally loop-back the Tx and
1642   Rx lines of a UART. This is not to be confused with the loop-back of UART0
1643   to UART1, which can be achieved through the microprocessor subsystem's
1644   system registers.
1645 
1646   @param this_uart
1647     The this_uart parameter is a pointer to an mss_uart_instance_t
1648     structure identifying the MSS UART hardware block that will perform
1649     the requested function. There are ten such data structures,
1650     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1651     when they are connected on the AXI switch slave 5 (main APB bus) and
1652     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1653     when they are connected on the AXI switch slave 6 (AMP APB bus).
1654     This parameter must point to one of these ten global data structure defined
1655     within the UART driver.
1656 
1657   @param loopback
1658     The loopback parameter indicates whether or not the UART's transmit and
1659     receive lines should be looped back. Allowed values are as follows:
1660       - MSS_UART_LOCAL_LOOPBACK_ON
1661       - MSS_UART_LOCAL_LOOPBACK_OFF
1662       - MSS_UART_REMOTE_LOOPBACK_ON
1663       - MSS_UART_REMOTE_LOOPBACK_OFF
1664       - MSS_UART_AUTO_ECHO_ON
1665       - MSS_UART_AUTO_ECHO_OFF
1666 
1667   @return
1668     This function does not return a value.
1669 
1670   Example:
1671   @code
1672     MSS_UART_init(&g_mss_uart0_lo,
1673              MSS_UART_57600_BAUD,
1674              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1675 
1676       MSS_UART_set_loopback(&g_mss_uart0_lo, MSS_UART_LOCAL_LOOPBACK_OFF);
1677   @endcode
1678  */
1679 void
1680 MSS_UART_set_loopback
1681 (
1682     mss_uart_instance_t *   this_uart,
1683     mss_uart_loopback_t     loopback
1684 );
1685 
1686 /***************************************************************************//**
1687   The MSS_UART_enable_irq() function enables the MSS UART interrupts specified
1688   by the irq_mask parameter. The irq_mask parameter identifies the MSS UART
1689   interrupts by bit position, as defined in the interrupt enable register (IER)
1690   of MSS UART. The MSS UART interrupts and their identifying irq_mask bit
1691   positions are as follows:
1692   When an irq_mask bit position is set to 1, this function enables the
1693   corresponding MSS UART interrupt in the IER register. When an irq_mask bit
1694   position is set to 0, the state of the corresponding interrupt remains
1695   unchanged in the IER register.
1696 
1697   Note: The MSS_UART_enable_irq() function also enables the MSS UART instance
1698         interrupt in the PolarFire SoC Core Complex PLIC.
1699 
1700   @param this_uart
1701     The this_uart parameter is a pointer to an mss_uart_instance_t
1702     structure identifying the MSS UART hardware block that will perform
1703     the requested function. There are ten such data structures,
1704     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1705     when they are connected on the AXI switch slave 5 (main APB bus) and
1706     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1707     when they are connected on the AXI switch slave 6 (AMP APB bus).
1708     This parameter must point to one of these ten global data structure defined
1709     within the UART driver.
1710 
1711   @param irq_mask
1712     The irq_mask parameter is used to select which of the MSS UART's interrupts
1713     you want to enable. The allowed value for the irq_mask parameter is one of
1714     the following constants or a bitwise OR of more than one:
1715       - MSS_UART_RBF_IRQ        (bit mask = 0x001)
1716       - MSS_UART_TBE_IRQ        (bit mask = 0x002)
1717       - MSS_UART_LS_IRQ         (bit mask = 0x004)
1718       - MSS_UART_MS_IRQ         (bit mask = 0x008)
1719       - MSS_UART_RTO_IRQ        (bit mask = 0x010)
1720       - MSS_UART_NACK_IRQ       (bit mask = 0x020)
1721       - MSS_UART_PIDPE_IRQ      (bit mask = 0x040)
1722       - MSS_UART_LINB_IRQ       (bit mask = 0x080)
1723       - MSS_UART_LINS_IRQ       (bit mask = 0x100)
1724 
1725   @return
1726      This function does not return a value.
1727 
1728   Example:
1729   @code
1730       #include "mss_uart.h"
1731 
1732       int main(void)
1733       {
1734          uint8_t tx_buff[10] = "abcdefghi";
1735 
1736          MSS_UART_init(&g_mss_uart0_lo,
1737                   MSS_UART_57600_BAUD,
1738                   MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1739 
1740          MSS_UART_enable_irq(&g_mss_uart0_lo,(MSS_UART_RBF_IRQ | MSS_UART_TBE_IRQ));
1741 
1742          return(0);
1743       }
1744 
1745   @endcode
1746  */
1747 void
1748 MSS_UART_enable_irq
1749 (
1750     mss_uart_instance_t * this_uart,
1751     mss_uart_irq_t irq_mask
1752 );
1753 
1754 /***************************************************************************//**
1755   The MSS_UART_disable_irq() function disables the MSS UART interrupts specified
1756   by the irq_mask parameter. The irq_mask parameter identifies the MSS UART
1757   interrupts by bit position, as defined in the interrupt enable register (IER)
1758   of MSS UART. The MSS UART interrupts and their identifying bit positions are
1759   as follows:
1760   When an irq_mask bit position is set to 1, this function disables the
1761   corresponding MSS UART interrupt in the IER register. When an irq_mask bit
1762   position is set to 0, the state of the corresponding interrupt remains
1763   unchanged in the IER register.
1764 
1765   Note: If you disable all four of the UART's interrupts, the
1766         MSS_UART_disable_irq() function also disables the MSS UART instance
1767         interrupt in the PolarFire SoC Core Complex PLIC.
1768 
1769   @param this_uart
1770     The this_uart parameter is a pointer to an mss_uart_instance_t
1771     structure identifying the MSS UART hardware block that will perform
1772     the requested function. There are ten such data structures,
1773     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1774     when they are connected on the AXI switch slave 5 (main APB bus) and
1775     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1776     when they are connected on the AXI switch slave 6 (AMP APB bus).
1777     This parameter must point to one of these ten global data structure defined
1778     within the UART driver.
1779 
1780   @param irq_mask
1781     The irq_mask parameter is used to select which of the MSS UART's interrupts
1782     you want to disable. The allowed value for the irq_mask parameter is one of
1783     the following constants or a bitwise OR of more than one:
1784       - MSS_UART_RBF_IRQ    (bit mask = 0x001)
1785       - MSS_UART_TBE_IRQ    (bit mask = 0x002)
1786       - MSS_UART_LS_IRQ     (bit mask = 0x004)
1787       - MSS_UART_MS_IRQ     (bit mask = 0x008)
1788       - MSS_UART_RTO_IRQ    (bit mask = 0x010)
1789       - MSS_UART_NACK_IRQ   (bit mask = 0x020)
1790       - MSS_UART_PIDPE_IRQ  (bit mask = 0x040)
1791       - MSS_UART_LINB_IRQ   (bit mask = 0x080)
1792       - MSS_UART_LINS_IRQ   (bit mask = 0x100)
1793 
1794   @return
1795      This function does not return a value.
1796 
1797   Example:
1798   @code
1799       #include "mss_uart.h"
1800 
1801   int main(void)
1802   {
1803      uint8_t tx_buff[10] = "abcdefghi";
1804 
1805      MSS_UART_init(&g_mss_uart0_lo,
1806               MSS_UART_57600_BAUD,
1807               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1808 
1809      MSS_UART_disable_irq(&g_mss_uart0_lo,(MSS_UART_RBF_IRQ | MSS_UART_TBE_IRQ));
1810 
1811      return(0);
1812   }
1813 
1814   @endcode
1815  */
1816 void
1817 MSS_UART_disable_irq
1818 (
1819     mss_uart_instance_t * this_uart,
1820     mss_uart_irq_t irq_mask
1821 );
1822 
1823 /***************************************************************************//**
1824   The MSS_UART_set_pidpei_handler() function is used assign a custom interrupt
1825   handler for the PIDPEI (PID parity error interrupt) when the MSS UART is
1826   operating in LIN mode.
1827 
1828   Note:     The MSS_UART_set_pidpei_handler() function enables both the PIDPEI
1829   interrupt in the MSS UART instance. It also enables the corresponding
1830   MSS UART instance interrupt in the PolarFire SoC Core Complex PLIC as part of
1831   its implementation.
1832 
1833   Note:     You can disable the PIDPEI interrupt when required by calling the
1834   MSS_UART_disable_irq() function. This is your choice and is dependent upon
1835   your application.
1836 
1837   @param this_uart
1838     The this_uart parameter is a pointer to an mss_uart_instance_t
1839     structure identifying the MSS UART hardware block that will perform
1840     the requested function. There are ten such data structures,
1841     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1842     when they are connected on the AXI switch slave 5 (main APB bus) and
1843     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1844     when they are connected on the AXI switch slave 6 (AMP APB bus).
1845     This parameter must point to one of these ten global data structure defined
1846     within the UART driver.
1847 
1848   @param handler
1849     The handler parameter is the pointer to the custom handler function.
1850     This parameter is of type mss_uart_irq_handler_t.
1851 
1852   @return
1853     This function does not return a value.
1854 
1855   Example:
1856   @code
1857   #include "mss_uart.h"
1858 
1859   int main(void)
1860   {
1861      uint8_t tx_buff[10] = "abcdefghi";
1862 
1863      MSS_UART_init(&g_mss_uart0_lo,
1864             MSS_UART_57600_BAUD,
1865             MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1866 
1867      MSS_UART_set_pidpei_handler(&g_mss_uart0_lo, my_pidpei_handler);
1868 
1869      return(0);
1870   }
1871   @endcode
1872  */
1873 void
1874 MSS_UART_set_pidpei_handler
1875 (
1876     mss_uart_instance_t * this_uart,
1877     mss_uart_irq_handler_t handler
1878 );
1879 
1880 /***************************************************************************//**
1881   The MSS_UART_set_linbreak_handler () function is used assign a custom
1882   interrupt handler for the LIN Break detection interrupt  when the MSS UART
1883   is operating in LIN mode.
1884 
1885   Note:     The MSS_UART_set_linbreak_handler() function enables both the LIN
1886   BREAK interrupt in the MSS UART instance. It also enables the corresponding
1887   MSS UART instance interrupt in the PolarFire SoC Core Complex PLIC as part of
1888   its implementation.
1889 
1890   Note:     You can disable the LIN BREAK interrupt when required by calling the
1891   MSS_UART_disable_irq() function. This is your choice and is dependent upon
1892   your application.
1893 
1894   @param this_uart
1895     The this_uart parameter is a pointer to an mss_uart_instance_t
1896     structure identifying the MSS UART hardware block that will perform
1897     the requested function. There are ten such data structures,
1898     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1899     when they are connected on the AXI switch slave 5 (main APB bus) and
1900     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1901     when they are connected on the AXI switch slave 6 (AMP APB bus).
1902     This parameter must point to one of these ten global data structure defined
1903     within the UART driver.
1904 
1905   @param handler
1906     The handler parameter is the pointer to the custom handler function.
1907     This parameter is of type mss_uart_irq_handler_t.
1908 
1909   @return
1910     This function does not return a value.
1911   Example:
1912   @code
1913   #include "mss_uart.h"
1914 
1915   int main(void)
1916   {
1917      uint8_t tx_buff[10] = "abcdefghi";
1918 
1919      MSS_UART_init(&g_mss_uart0_lo,
1920               MSS_UART_57600_BAUD,
1921               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1922 
1923      MSS_UART_set_linbreak_handler(&g_mss_uart0_lo, my_break_handler);
1924 
1925      return(0);
1926   }
1927 
1928   @endcode
1929  */
1930 void
1931 MSS_UART_set_linbreak_handler
1932 (
1933     mss_uart_instance_t * this_uart,
1934     mss_uart_irq_handler_t handler
1935 );
1936 
1937 /***************************************************************************//**
1938   The MSS_UART_set_linsync_handler() function is used assign a custom interrupt
1939   handler for the LIN Sync character detection interrupt  when the MSS UART is
1940   operating in LIN mode.
1941 
1942   Note:     The MSS_UART_set_linsync_handler() function enables both the LIN
1943   SYNC interrupt in the MSS UART instance. It also enables the corresponding
1944   MSS UART instance interrupt in the PolarFire SoC Core Complex PLIC as part of
1945   its implementation.
1946 
1947   Note:     You can disable the LIN SYNC interrupt when required by calling the
1948   MSS_UART_disable_irq() function. This is your choice and is dependent upon
1949   your application.
1950 
1951   @param this_uart
1952     The this_uart parameter is a pointer to an mss_uart_instance_t
1953     structure identifying the MSS UART hardware block that will perform
1954     the requested function. There are ten such data structures,
1955     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
1956     when they are connected on the AXI switch slave 5 (main APB bus) and
1957     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
1958     when they are connected on the AXI switch slave 6 (AMP APB bus).
1959     This parameter must point to one of these ten global data structure defined
1960     within the UART driver.
1961 
1962   @param handler
1963     The handler parameter is the pointer to the custom handler function.
1964     This parameter is of type mss_uart_irq_handler_t.
1965 
1966   @return
1967     This function does not return a value.
1968 
1969   Example:
1970   @code
1971   #include "mss_uart.h"
1972 
1973   int main(void)
1974   {
1975      uint8_t tx_buff[10] = "abcdefghi";
1976 
1977      MSS_UART_init(&g_mss_uart0_lo,
1978               MSS_UART_57600_BAUD,
1979               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
1980 
1981      MSS_UART_set_linsync_handler(&g_mss_uart0_lo, my_linsync_handler);
1982 
1983      return(0);
1984   }
1985 
1986   @endcode
1987  */
1988 void
1989 MSS_UART_set_linsync_handler
1990 (
1991     mss_uart_instance_t * this_uart,
1992     mss_uart_irq_handler_t handler
1993 );
1994 
1995 /***************************************************************************//**
1996   The MSS_UART_set_nack_handler() function is used assign a custom interrupt
1997   handler for the NACK character detection interrupt  when the MSS UART
1998   is operating in Smartcard mode.
1999 
2000   Note:     The MSS_UART_set_nack_handler() function enables both the NAK
2001   interrupt in the MSS UART instance. It also enables the corresponding
2002   MSS UART instance interrupt in the PolarFire SoC Core Complex PLIC as part of
2003   its implementation.
2004 
2005   Note:     You can disable the NAK interrupt when required by calling the
2006   MSS_UART_disable_irq() function. This is your choice and is dependent upon
2007   your application.
2008 
2009   @param this_uart
2010     The this_uart parameter is a pointer to an mss_uart_instance_t
2011     structure identifying the MSS UART hardware block that will perform
2012     the requested function. There are ten such data structures,
2013     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2014     when they are connected on the AXI switch slave 5 (main APB bus) and
2015     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2016     when they are connected on the AXI switch slave 6 (AMP APB bus).
2017     This parameter must point to one of these ten global data structure defined
2018     within the UART driver.
2019 
2020   @param handler
2021     The handler parameter is the pointer to the custom handler function.
2022     This parameter is of type mss_uart_irq_handler_t.
2023 
2024   @return
2025     This function does not return a value.
2026 
2027   Example:
2028   @code
2029   #include "mss_uart.h"
2030 
2031   int main(void)
2032   {
2033      uint8_t tx_buff[10] = "abcdefghi";
2034 
2035      MSS_UART_init(&g_mss_uart0_lo,
2036               MSS_UART_57600_BAUD,
2037               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2038 
2039      MSS_UART_set_nack_handler(&g_mss_uart0_lo, my_nack_handler);
2040 
2041      return(0);
2042   }
2043 
2044   @endcode
2045  */
2046 void
2047 MSS_UART_set_nack_handler
2048 (
2049     mss_uart_instance_t * this_uart,
2050     mss_uart_irq_handler_t handler
2051 );
2052 
2053 /***************************************************************************//**
2054   The MSS_UART_set_rx_timeout_handler() function is used assign a custom
2055   interrupt handler for the receiver timeout interrupt  when the MSS UART is
2056   operating in mode. It finds application in IrDA mode of operation.
2057 
2058   Note:     The MSS_UART_set_rx_timeout_handler() function enables both the
2059   time-out interrupt in the MSS UART instance. It also enables the corresponding
2060   MSS UART instance interrupt in the PolarFire SoC Core Complex PLIC as part of
2061   its implementation.
2062 
2063   Note:     You can disable the RX time-out interrupt when required by calling
2064   the MSS_UART_disable_irq() function. This is your choice and is dependent upon
2065   your application.
2066 
2067   @param this_uart
2068     The this_uart parameter is a pointer to an mss_uart_instance_t
2069     structure identifying the MSS UART hardware block that will perform
2070     the requested function. There are ten such data structures,
2071     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2072     when they are connected on the AXI switch slave 5 (main APB bus) and
2073     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2074     when they are connected on the AXI switch slave 6 (AMP APB bus).
2075     This parameter must point to one of these ten global data structure defined
2076     within the UART driver.
2077 
2078   @param handler
2079     The handler parameter is the pointer to the custom handler function.
2080     This parameter is of type mss_uart_irq_handler_t.
2081 
2082   @return
2083     This function does not return a value.
2084 
2085   Example:
2086   @code
2087     #include "mss_uart.h"
2088 
2089   int main(void)
2090   {
2091      uint8_t tx_buff[10] = "abcdefghi";
2092 
2093      MSS_UART_init(&g_mss_uart0_lo,
2094               MSS_UART_57600_BAUD,
2095               MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2096 
2097      MSS_UART_set_rx_timeout_handler(&g_mss_uart0_lo, my_rxtimeout_handler);
2098 
2099      return(0);
2100   }
2101 
2102   @endcode
2103  */
2104 void
2105 MSS_UART_set_rx_timeout_handler
2106 (
2107     mss_uart_instance_t * this_uart,
2108     mss_uart_irq_handler_t handler
2109 );
2110 
2111 /***************************************************************************//**
2112   The MSS_UART_set_rxstatus_handler() function is used to register a receiver
2113   status handler function that is called by the driver when a UART receiver
2114   line status (RLS) interrupt occurs. You must create and register the handler
2115   function to suit your application.
2116 
2117   Note:     The MSS_UART_set_rxstatus_handler() function enables both the RLS
2118   interrupt in the MSS UART instance. It also enables the corresponding MSS UART
2119   instance interrupt in the PolarFire SoC Core Complex PLIC as part of its
2120   implementation.
2121 
2122   Note:     You can disable the RLS interrupt when required by calling the
2123   MSS_UART_disable_irq() function. This is your choice and is dependent upon
2124   your application.
2125 
2126   @param this_uart
2127     The this_uart parameter is a pointer to an mss_uart_instance_t
2128     structure identifying the MSS UART hardware block that will perform
2129     the requested function. There are ten such data structures,
2130     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2131     when they are connected on the AXI switch slave 5 (main APB bus) and
2132     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2133     when they are connected on the AXI switch slave 6 (AMP APB bus).
2134     This parameter must point to one of these ten global data structure defined
2135     within the UART driver.
2136 
2137   @param handler
2138      The handler parameter is a pointer to a receiver line status interrupt
2139      handler function provided by your application that will be called as a
2140      result of a UART RLS interrupt. This handler function must be of type
2141      mss_uart_irq_handler_t.
2142 
2143   @return
2144      This function does not return a value.
2145 
2146   Example:
2147   @code
2148   #include "mss_uart.h"
2149 
2150   void uart_rxsts_handler(mss_uart_instance_t * this_uart)
2151   {
2152     uint8_t status;
2153     status = MSS_UART_get_rx_status(this_uart);
2154     if(status & MSS_UART_OVERUN_ERROR)
2155     {
2156         discard_rx_data();
2157     }
2158   }
2159 
2160   int main(void)
2161   {
2162     MSS_UART_init( &g_mss_uart0_lo,
2163              MSS_UART_57600_BAUD,
2164              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2165 
2166     MSS_UART_set_rxstatus_handler(&g_mss_uart0_lo, uart_rxsts_handler);
2167 
2168     while(1)
2169     {
2170         ;
2171     }
2172     return(0);
2173   }
2174   @endcode
2175  */
2176 void
2177 MSS_UART_set_rxstatus_handler
2178 (
2179     mss_uart_instance_t * this_uart,
2180     mss_uart_irq_handler_t handler
2181 );
2182 
2183 /***************************************************************************//**
2184   The MSS_UART_set_tx_handler() function is used to register a transmit handler
2185   function that is called by the driver when a UART transmit holding register
2186   empty (THRE) interrupt occurs. You must create and register the transmit
2187   handler function to suit your application. You can use the
2188   MSS_UART_fill_tx_fifo() function in your transmit handler function to
2189   write data to the transmitter.
2190 
2191   Note:     The MSS_UART_set_tx_handler() function enables both the THRE
2192   interrupt in the MSS UART instance. It also enables the corresponding MSS UART
2193   instance interrupt in the PolarFire SoC Core Complex PLIC as part of its
2194   implementation.
2195 
2196 
2197   Note:     You can disable the THRE interrupt when required by calling the
2198   MSS_UART_disable_irq() function. This is your choice and is dependent upon
2199   your application.
2200 
2201   Note:     The MSS_UART_irq_tx() function does not use the transmit handler
2202   function that you register with the MSS_UART_set_tx_handler() function.
2203   It uses its own internal THRE interrupt handler function that overrides
2204   any custom interrupt handler that you register using the
2205   MSS_UART_set_tx_handler() function.
2206 
2207   @param this_uart
2208     The this_uart parameter is a pointer to an mss_uart_instance_t
2209     structure identifying the MSS UART hardware block that will perform
2210     the requested function. There are ten such data structures,
2211     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2212     when they are connected on the AXI switch slave 5 (main APB bus) and
2213     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2214     when they are connected on the AXI switch slave 6 (AMP APB bus).
2215     This parameter must point to one of these ten global data structure defined
2216     within the UART driver.
2217 
2218    @param handler
2219      The handler parameter is a pointer to a transmit interrupt handler
2220      function provided by your application that will be called as a result
2221      of a UART THRE interrupt. This handler function must be of type
2222      mss_uart_irq_handler_t.
2223 
2224    @return
2225      This function does not return a value.
2226 
2227    Example:
2228    @code
2229     #include "mss_uart.h"
2230 
2231     uint8_t * g_tx_buffer;
2232     size_t g_tx_size = 0;
2233 
2234     void uart_tx_handler(mss_uart_instance_t * this_uart)
2235     {
2236         size_t size_in_fifo;
2237         size_in_fifo = MSS_UART_fill_tx_fifo(this_uart,
2238                                              (const uint8_t *)g_tx_buffer,
2239                                              g_tx_size);
2240 
2241         if(size_in_fifo  ==  g_tx_size)
2242         {
2243             g_tx_size = 0;
2244             MSS_UART_disable_irq(this_uart, MSS_UART_TBE_IRQ);
2245         }
2246         else
2247         {
2248             g_tx_buffer = &g_tx_buffer[size_in_fifo];
2249             g_tx_size = g_tx_size - size_in_fifo;
2250         }
2251     }
2252 
2253     int main(void)
2254     {
2255         uint8_t message[12] = "Hello world";
2256 
2257         MSS_UART_init(&g_mss_uart0_lo,
2258              MSS_UART_57600_BAUD,
2259              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2260 
2261         g_tx_buffer = message;
2262         g_tx_size = sizeof(message);
2263 
2264         MSS_UART_set_tx_handler(&g_mss_uart0_lo, uart_tx_handler);
2265 
2266         while(1)
2267         {
2268             ;
2269         }
2270         return(0);
2271     }
2272    @endcode
2273  */
2274 void
2275 MSS_UART_set_tx_handler
2276 (
2277     mss_uart_instance_t * this_uart,
2278     mss_uart_irq_handler_t handler
2279 );
2280 
2281 /***************************************************************************//**
2282   The MSS_UART_set_modemstatus_handler() function is used to register a modem
2283   status handler function that is called by the driver when a UART modem status
2284   (MS) interrupt occurs. You must create and register the handler function to
2285   suit your application.
2286 
2287   Note:     The MSS_UART_set_modemstatus_handler() function enables both the MS
2288   interrupt in the MSS UART instance. It also enables the corresponding MSS UART
2289   instance interrupt in the PolarFire SoC Core Complex PLIC as part of its
2290   implementation.
2291 
2292   Note:     You can disable the MS interrupt when required by calling the
2293   MSS_UART_disable_irq() function. This is your choice and is dependent
2294   upon your application.
2295 
2296   @param this_uart
2297     The this_uart parameter is a pointer to an mss_uart_instance_t
2298     structure identifying the MSS UART hardware block that will perform
2299     the requested function. There are ten such data structures,
2300     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2301     when they are connected on the AXI switch slave 5 (main APB bus) and
2302     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2303     when they are connected on the AXI switch slave 6 (AMP APB bus).
2304     This parameter must point to one of these ten global data structure defined
2305     within the UART driver.
2306 
2307    @param handler
2308      The handler parameter is a pointer to a modem status interrupt handler
2309      function provided by your application that will be called as a result
2310      of a UART MS interrupt. This handler function must be of type
2311      mss_uart_irq_handler_t.
2312 
2313    @return
2314      This function does not return a value.
2315 
2316    Example:
2317    @code
2318    #include "mss_uart.h"
2319 
2320    void uart_modem_handler(mss_uart_instance_t * this_uart)
2321    {
2322      uint8_t status;
2323      status = MSS_UART_get_modem_status(this_uart);
2324      if(status & MSS_UART_CTS)
2325      {
2326         uart_cts_handler();
2327      }
2328    }
2329 
2330    int main(void)
2331    {
2332       MSS_UART_init(&g_mss_uart0_lo,
2333              MSS_UART_57600_BAUD,
2334              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2335 
2336       MSS_UART_set_modemstatus_handler(&g_mss_uart0_lo, uart_modem_handler);
2337 
2338       while(1)
2339       {
2340         ;
2341       }
2342       return(0);
2343    }
2344    @endcode
2345  */
2346 
2347 void
2348 MSS_UART_set_modemstatus_handler
2349 (
2350     mss_uart_instance_t * this_uart,
2351     mss_uart_irq_handler_t handler
2352 );
2353 
2354 /***************************************************************************//**
2355   The MSS_UART_fill_tx_fifo() function fills the UART's hardware transmitter
2356   FIFO with the data found in the transmitter buffer that is passed via the
2357   tx_buffer function parameter. If the transmitter FIFO is not empty when
2358   the function is called, the function returns immediately without transferring
2359   any data to the FIFO; otherwise, the function transfers data from the
2360   transmitter buffer to the FIFO until it is full or until the complete
2361   contents of the transmitter buffer have been copied into the FIFO. The
2362   function returns the number of bytes copied into the UART's transmitter FIFO.
2363 
2364   Note:     This function reads the UART's line status register (LSR) to check
2365   for the active state of the transmitter holding register empty (THRE) bit
2366   before transferring data from the data buffer to the transmitter FIFO. If
2367   THRE is 0, the function returns immediately, without transferring any data
2368   to the FIFO. If THRE is 1, the function transfers up to 16 bytes of data
2369   to the FIFO and then returns.
2370 
2371   Note:     The actual transmission over the serial connection will still be
2372   in progress when this function returns. Use the MSS_UART_get_tx_status()
2373   function if you need to know when the transmitter is empty.
2374 
2375   @param this_uart
2376     The this_uart parameter is a pointer to an mss_uart_instance_t
2377     structure identifying the MSS UART hardware block that will perform
2378     the requested function. There are ten such data structures,
2379     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2380     when they are connected on the AXI switch slave 5 (main APB bus) and
2381     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2382     when they are connected on the AXI switch slave 6 (AMP APB bus).
2383     This parameter must point to one of these ten global data structure defined
2384     within the UART driver.
2385 
2386   @param tx_buffer
2387     The tx_buffer parameter is a pointer to a buffer containing the data
2388     to be transmitted.
2389 
2390   @param tx_size
2391     The tx_size parameter is the size in bytes, of the data to be transmitted.
2392 
2393   @return
2394     This function returns the number of bytes copied into the UART's
2395     transmitter FIFO.
2396 
2397   Example:
2398   @code
2399      void send_using_interrupt(uint8_t * pbuff, size_t tx_size)
2400      {
2401         size_t size_in_fifo;
2402         size_in_fifo = MSS_UART_fill_tx_fifo(&g_mss_uart0_lo, pbuff, tx_size);
2403      }
2404   @endcode
2405  */
2406 size_t
2407 MSS_UART_fill_tx_fifo
2408 (
2409     mss_uart_instance_t * this_uart,
2410     const uint8_t * tx_buffer,
2411     size_t tx_size
2412 );
2413 
2414 /***************************************************************************//**
2415   The MSS_UART_get_rx_status() function returns the receiver error status of the
2416   MSS UART instance. It reads both the current error status of the receiver from
2417   the UART's line status register (LSR) and the accumulated error status from
2418   preceding calls to the MSS_UART_get_rx() function, and it combines them using
2419   a bitwise OR. It returns the cumulative overrun, parity, framing, break and
2420   FIFO error status of the receiver, since the previous call to
2421   MSS_UART_get_rx_status(), as an 8-bit encoded value.
2422 
2423   Note:     The MSS_UART_get_rx() function reads and accumulates the receiver
2424   status of the MSS UART instance before reading each byte from the receiver's
2425   data register/FIFO. The driver maintains a sticky record of the cumulative
2426   receiver error status, which persists after the MSS_UART_get_rx() function
2427   returns. The MSS_UART_get_rx_status() function clears the driver's sticky
2428   receiver error record before returning.
2429 
2430   Note:     The driver's transmit functions also read the line status
2431   register (LSR) as part of their implementation. When the driver reads the
2432   LSR, the UART clears any active receiver error bits in the LSR. This could
2433   result in the driver losing receiver errors. To avoid any loss of receiver
2434   errors, the transmit functions also update the driver's sticky record of the
2435   cumulative receiver error status whenever they read the LSR.
2436 
2437   @param this_uart
2438     The this_uart parameter is a pointer to an mss_uart_instance_t
2439     structure identifying the MSS UART hardware block that will perform
2440     the requested function. There are ten such data structures,
2441     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2442     when they are connected on the AXI switch slave 5 (main APB bus) and
2443     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2444     when they are connected on the AXI switch slave 6 (AMP APB bus).
2445     This parameter must point to one of these ten global data structure defined
2446     within the UART driver.
2447 
2448   @return
2449     This function returns the UART's receiver error status as an 8-bit unsigned
2450     integer. The returned value is 0 if no receiver errors occurred. The driver
2451     provides a set of bit mask constants that should be compared with and/or
2452     used to mask the returned value to determine the receiver error status.
2453     When the return value is compared to the following bit masks, a non-zero
2454     result indicates that the corresponding error occurred:
2455         - MSS_UART_OVERRUN_ERROR      (bit mask = 0x02)
2456         - MSS_UART_PARITY_ERROR       (bit mask = 0x04)
2457         - MSS_UART_FRAMING_ERROR      (bit mask = 0x08)
2458         - MSS_UART_BREAK_ERROR        (bit mask = 0x10)
2459         - MSS_UART_FIFO_ERROR         (bit mask = 0x80)
2460 
2461     When the return value is compared to the following bit mask, a non-zero
2462     result indicates that no error occurred:
2463         - MSS_UART_NO_ERROR       (bit mask = 0x00)
2464 
2465     Upon unsuccessful execution, this function returns:
2466         - MSS_UART_INVALID_PARAM      (bit mask = 0xFF)
2467 
2468   Example:
2469   @code
2470     uint8_t rx_data[MAX_RX_DATA_SIZE];
2471     uint8_t err_status;
2472     err_status = MSS_UART_get_rx_status(&g_mss_uart0);
2473 
2474     if(MSS_UART_NO_ERROR == err_status)
2475     {
2476        rx_size = MSS_UART_get_rx(&g_mss_uart0_lo, rx_data, MAX_RX_DATA_SIZE);
2477     }
2478   @endcode
2479  */
2480 uint8_t
2481 MSS_UART_get_rx_status
2482 (
2483     mss_uart_instance_t * this_uart
2484 );
2485 
2486 /***************************************************************************//**
2487   The MSS_UART_get_modem_status() function returns the modem status of the
2488   MSS UART instance. It reads the modem status register (MSR) and returns
2489   the 8 bit value. The bit encoding of the returned value is exactly the
2490   same as the definition of the bits in the MSR.
2491 
2492   @param this_uart
2493     The this_uart parameter is a pointer to an mss_uart_instance_t
2494     structure identifying the MSS UART hardware block that will perform
2495     the requested function. There are ten such data structures,
2496     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2497     when they are connected on the AXI switch slave 5 (main APB bus) and
2498     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2499     when they are connected on the AXI switch slave 6 (AMP APB bus).
2500     This parameter must point to one of these ten global data structure defined
2501     within the UART driver.
2502 
2503   @return
2504     This function returns current state of the UART's MSR as an 8 bit
2505     unsigned integer. The driver provides the following set of bit mask
2506     constants that should be compared with and/or used to mask the
2507     returned value to determine the modem status:
2508         - MSS_UART_DCTS   (bit mask = 0x01)
2509         - MSS_UART_DDSR   (bit mask = 0x02)
2510         - MSS_UART_TERI   (bit mask = 0x04)
2511         - MSS_UART_DDCD   (bit mask = 0x08)
2512         - MSS_UART_CTS    (bit mask = 0x10)
2513         - MSS_UART_DSR    (bit mask = 0x20)
2514         - MSS_UART_RI     (bit mask = 0x40)
2515         - MSS_UART_DCD    (bit mask = 0x80)
2516 
2517   Example:
2518   @code
2519     void uart_modem_status_isr(mss_uart_instance_t * this_uart)
2520     {
2521         uint8_t status;
2522         status = MSS_UART_get_modem_status(this_uart);
2523         if( status & MSS_UART_DCTS )
2524         {
2525             uart_dcts_handler();
2526         }
2527         if( status & MSS_UART_CTS )
2528         {
2529             uart_cts_handler();
2530         }
2531     }
2532   @endcode
2533  */
2534 uint8_t
2535 MSS_UART_get_modem_status
2536 (
2537     const mss_uart_instance_t * this_uart
2538 );
2539 
2540 /***************************************************************************//**
2541   The MSS_UART_get_tx_status() function returns the transmitter status of the
2542   MSS UART instance. It reads both the UART's line status register (LSR) and
2543   returns the status of the transmit holding register empty (THRE) and
2544   transmitter empty (TEMT) bits.
2545 
2546   @param this_uart
2547     The this_uart parameter is a pointer to an mss_uart_instance_t
2548     structure identifying the MSS UART hardware block that will perform
2549     the requested function. There are ten such data structures,
2550     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2551     when they are connected on the AXI switch slave 5 (main APB bus) and
2552     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2553     when they are connected on the AXI switch slave 6 (AMP APB bus).
2554     This parameter must point to one of these ten global data structure defined
2555     within the UART driver.
2556 
2557   @return
2558     This function returns the UART's transmitter status as an 8-bit unsigned
2559     integer. The returned value is 0 if the transmitter status bits are not
2560     set or the function execution failed. The driver provides a set of bit
2561     mask constants that should be compared with and/or used to mask the
2562     returned value to determine the transmitter status.
2563     When the return value is compared to the following bit mask, a non-zero
2564     result indicates that the corresponding transmitter status bit is set:
2565       - MSS_UART_THRE       (bit mask = 0x20)
2566       - MSS_UART_TEMT       (bit mask = 0x40)
2567 
2568     When the return value is compared to the following bit mask, a non-zero
2569     result indicates that the transmitter is busy or the function execution
2570     failed.
2571       - MSS_UART_TX_BUSY        (bit mask = 0x00)
2572 
2573   Example:
2574   @code
2575     uint8_t tx_buff[10] = "abcdefghi";
2576     MSS_UART_init(&g_mss_uart0_lo,
2577              MSS_UART_57600_BAUD,
2578              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2579 
2580     MSS_UART_polled_tx(&g_mss_uart0_lo, tx_buff, sizeof(tx_buff));
2581 
2582     while(!(MSS_UART_TEMT & MSS_UART_get_tx_status(&g_mss_uart0)))
2583     {
2584         ;
2585     }
2586   @endcode
2587  */
2588 uint8_t
2589 MSS_UART_get_tx_status
2590 (
2591     mss_uart_instance_t * this_uart
2592 );
2593 
2594 /***************************************************************************//**
2595   The MSS_UART_set_break() function is used to send the break
2596   (9 zeros after stop bit) signal on the TX line. This function can be used
2597   only when the MSS UART is initialized in LIN mode by using MSS_UART_lin_init().
2598 
2599   @param this_uart
2600     The this_uart parameter is a pointer to an mss_uart_instance_t
2601     structure identifying the MSS UART hardware block that will perform
2602     the requested function. There are ten such data structures,
2603     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2604     when they are connected on the AXI switch slave 5 (main APB bus) and
2605     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2606     when they are connected on the AXI switch slave 6 (AMP APB bus).
2607     This parameter must point to one of these ten global data structure defined
2608     within the UART driver.
2609 
2610   @return
2611     This function does not return a value.
2612 
2613   Example:
2614   @code
2615     MSS_UART_lin_init(&g_mss_uart0_lo,
2616              MSS_UART_57600_BAUD,
2617              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2618 
2619     MSS_UART_set_break(&g_mss_uart0);
2620   @endcode
2621  */
2622 void
2623 MSS_UART_set_break
2624 (
2625     mss_uart_instance_t * this_uart
2626 );
2627 
2628 /***************************************************************************//**
2629   The MSS_UART_clear_break() function is used to remove the break signal on the
2630   TX line. This function can be used only when the MSS UART is initialized in
2631   LIN mode by using MSS_UART_lin_init().
2632 
2633   @param this_uart
2634     The this_uart parameter is a pointer to an mss_uart_instance_t
2635     structure identifying the MSS UART hardware block that will perform
2636     the requested function. There are ten such data structures,
2637     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2638     when they are connected on the AXI switch slave 5 (main APB bus) and
2639     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2640     when they are connected on the AXI switch slave 6 (AMP APB bus).
2641     This parameter must point to one of these ten global data structure defined
2642     within the UART driver.
2643 
2644   @return
2645     This function does not return a value.
2646 
2647   Example:
2648   @code
2649     MSS_UART_lin_init(&g_mss_uart0_lo,
2650              MSS_UART_57600_BAUD,
2651              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2652 
2653     MSS_UART_clear_break(&g_mss_uart0_lo);
2654   @endcode
2655  */
2656 void
2657 MSS_UART_clear_break
2658 (
2659     mss_uart_instance_t * this_uart
2660 );
2661 
2662 /***************************************************************************//**
2663   The MSS_UART_enable_half_duplex() function is used to enable the half-duplex
2664   (single wire) mode for the MSS UART. Though it finds application in Smartcard
2665   mode, half-duplex mode can be used in other modes as well.
2666 
2667   @param this_uart
2668     The this_uart parameter is a pointer to an mss_uart_instance_t
2669     structure identifying the MSS UART hardware block that will perform
2670     the requested function. There are ten such data structures,
2671     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2672     when they are connected on the AXI switch slave 5 (main APB bus) and
2673     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2674     when they are connected on the AXI switch slave 6 (AMP APB bus).
2675     This parameter must point to one of these ten global data structure defined
2676     within the UART driver.
2677 
2678   @return
2679     This function does not return a value.
2680 
2681   Example:
2682   @code
2683     MSS_UART_init(&g_mss_uart0_lo,
2684              MSS_UART_57600_BAUD,
2685              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2686 
2687     MSS_UART_enable_half_duplex(&g_mss_uart0_lo);
2688   @endcode
2689  */
2690 void
2691 MSS_UART_enable_half_duplex
2692 (
2693     mss_uart_instance_t * this_uart
2694 );
2695 
2696 /***************************************************************************//**
2697   The MSS_UART_disable_half_duplex() function is used to disable the half-duplex
2698   (single wire) mode for the MSS UART. Though it finds application in Smartcard
2699   mode, half-duplex mode can be used in other modes as well.
2700 
2701   @param this_uart
2702     The this_uart parameter is a pointer to an mss_uart_instance_t
2703     structure identifying the MSS UART hardware block that will perform
2704     the requested function. There are ten such data structures,
2705     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2706     when they are connected on the AXI switch slave 5 (main APB bus) and
2707     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2708     when they are connected on the AXI switch slave 6 (AMP APB bus).
2709     This parameter must point to one of these ten global data structure defined
2710     within the UART driver.
2711 
2712   @return
2713     This function does not return a value.
2714 
2715   Example:
2716   @code
2717     MSS_UART_init(&g_mss_uart0_lo,
2718              MSS_UART_57600_BAUD,
2719              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2720 
2721     MSS_UART_disable_half_duplex(&g_mss_uart0_lo);
2722   @endcode
2723  */
2724 void
2725 MSS_UART_disable_half_duplex
2726 (
2727     mss_uart_instance_t * this_uart
2728 );
2729 
2730 /***************************************************************************//**
2731   The MSS_UART_set_rx_endian() function is used to configure the LSB first or
2732   MSB first setting for MSS UART receiver
2733 
2734   @param this_uart
2735     The this_uart parameter is a pointer to an mss_uart_instance_t
2736     structure identifying the MSS UART hardware block that will perform
2737     the requested function. There are ten such data structures,
2738     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2739     when they are connected on the AXI switch slave 5 (main APB bus) and
2740     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2741     when they are connected on the AXI switch slave 6 (AMP APB bus).
2742     This parameter must point to one of these ten global data structure defined
2743     within the UART driver.
2744 
2745   @param endian
2746     The endian parameter tells the LSB first or MSB first configuration.
2747     This parameter is of type mss_uart_endian_t.
2748 
2749   @return
2750     This function does not return a value.
2751 
2752   Example:
2753   @code
2754     MSS_UART_init(&g_mss_uart0_lo,
2755              MSS_UART_57600_BAUD,
2756              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2757 
2758     MSS_UART_set_rx_endian(&g_mss_uart0_lo, MSS_UART_LITTLEEND);
2759   @endcode
2760  */
2761 void
2762 MSS_UART_set_rx_endian
2763 (
2764     mss_uart_instance_t * this_uart,
2765     mss_uart_endian_t endian
2766 );
2767 
2768 /***************************************************************************//**
2769   The MSS_UART_set_tx_endian() function is used to configure the LSB first or
2770   MSB first setting for MSS UART transmitter.
2771 
2772   @param this_uart
2773     The this_uart parameter is a pointer to an mss_uart_instance_t
2774     structure identifying the MSS UART hardware block that will perform
2775     the requested function. There are ten such data structures,
2776     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2777     when they are connected on the AXI switch slave 5 (main APB bus) and
2778     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2779     when they are connected on the AXI switch slave 6 (AMP APB bus).
2780     This parameter must point to one of these ten global data structure defined
2781     within the UART driver.
2782 
2783   @param endian
2784     The endian parameter tells the LSB first or MSB first configuration.
2785     This parameter is of type mss_uart_endian_t.
2786 
2787   @return
2788     This function does not return a value.
2789 
2790   Example:
2791   @code
2792     MSS_UART_init(&g_mss_uart0_lo,
2793              MSS_UART_57600_BAUD,
2794              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2795 
2796     MSS_UART_set_tx_endian(&g_mss_uart0_lo, MSS_UART_LITTLEEND);
2797   @endcode
2798  */
2799 void
2800 MSS_UART_set_tx_endian
2801 (
2802     mss_uart_instance_t * this_uart,
2803     mss_uart_endian_t endian
2804 );
2805 
2806 /***************************************************************************//**
2807   The MSS_UART_set_filter_length () function is used to configure the glitch
2808   filter length of the MSS UART. This should be configured in accordance with
2809   the chosen baud rate.
2810 
2811   @param this_uart
2812     The this_uart parameter is a pointer to an mss_uart_instance_t
2813     structure identifying the MSS UART hardware block that will perform
2814     the requested function. There are ten such data structures,
2815     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2816     when they are connected on the AXI switch slave 5 (main APB bus) and
2817     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2818     when they are connected on the AXI switch slave 6 (AMP APB bus).
2819     This parameter must point to one of these ten global data structure defined
2820     within the UART driver.
2821 
2822   @param length
2823     The length parameter is of mss_uart_filter_length_t type that determines
2824     the length of the glitch filter.
2825 
2826   @return
2827     This function does not return a value.
2828 
2829   Example:
2830   @code
2831     MSS_UART_init(&g_mss_uart0_lo,
2832              MSS_UART_57600_BAUD,
2833              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2834 
2835     MSS_UART_set_filter_length(&g_mss_uart0_lo, MSS_UART_LEN2);
2836   @endcode
2837  */
2838 void
2839 MSS_UART_set_filter_length
2840 (
2841     mss_uart_instance_t * this_uart,
2842     mss_uart_filter_length_t length
2843 );
2844 
2845 /***************************************************************************//**
2846   The MSS_UART_enable_afm() function is used to enable address flag detection
2847   mode of the MSS UART
2848 
2849   @param this_uart
2850     The this_uart parameter is a pointer to an mss_uart_instance_t
2851     structure identifying the MSS UART hardware block that will perform
2852     the requested function. There are ten such data structures,
2853     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2854     when they are connected on the AXI switch slave 5 (main APB bus) and
2855     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2856     when they are connected on the AXI switch slave 6 (AMP APB bus).
2857     This parameter must point to one of these ten global data structure defined
2858     within the UART driver.
2859 
2860   @return
2861     This function does not return a value.
2862 
2863   Example:
2864   @code
2865     MSS_UART_init(&g_mss_uart0_lo,
2866              MSS_UART_57600_BAUD,
2867              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2868 
2869     MSS_UART_enable_afm(&g_mss_uart0_lo);
2870   @endcode
2871  */
2872 void
2873 MSS_UART_enable_afm
2874 (
2875      mss_uart_instance_t * this_uart
2876 );
2877 
2878 /***************************************************************************//**
2879   The MSS_UART_disable_afm() function is used to disable address flag detection
2880   mode of the MSS UART.
2881 
2882   @param this_uart
2883     The this_uart parameter is a pointer to an mss_uart_instance_t
2884     structure identifying the MSS UART hardware block that will perform
2885     the requested function. There are ten such data structures,
2886     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2887     when they are connected on the AXI switch slave 5 (main APB bus) and
2888     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2889     when they are connected on the AXI switch slave 6 (AMP APB bus).
2890     This parameter must point to one of these ten global data structure defined
2891     within the UART driver.
2892 
2893     Note that if you are using the UART on the AMP APB bus, the hardware
2894     configuration to connect UART on AMP APB bus must already be done by the
2895     application using SYSREG registers before initializing the UART instance
2896     structure.
2897 
2898   @return
2899     This function does not return a value.
2900 
2901   Example:
2902   @code
2903     MSS_UART_init(&g_mss_uart0_lo,
2904              MSS_UART_57600_BAUD,
2905              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2906 
2907     MSS_UART_disable_afm(&g_mss_uart0_lo);
2908   @endcode
2909  */
2910 void
2911 MSS_UART_disable_afm
2912 (
2913      mss_uart_instance_t * this_uart
2914 );
2915 
2916 /***************************************************************************//**
2917   The MSS_UART_enable_afclear () function is used to enable address flag clear
2918   of the MSS UART. This should be used in conjunction with address flag
2919   detection mode (AFM).
2920 
2921   @param this_uart
2922     The this_uart parameter is a pointer to an mss_uart_instance_t
2923     structure identifying the MSS UART hardware block that will perform
2924     the requested function. There are ten such data structures,
2925     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2926     when they are connected on the AXI switch slave 5 (main APB bus) and
2927     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2928     when they are connected on the AXI switch slave 6 (AMP APB bus).
2929     This parameter must point to one of these ten global data structure defined
2930     within the UART driver.
2931 
2932   @return
2933     This function does not return a value.
2934 
2935   Example:
2936   @code
2937     MSS_UART_init(&g_mss_uart0_lo,
2938              MSS_UART_57600_BAUD,
2939              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2940 
2941     MSS_UART_enable_afclear(&g_mss_uart0_lo);
2942   @endcode
2943  */
2944 void
2945 MSS_UART_enable_afclear
2946 (
2947      mss_uart_instance_t * this_uart
2948 );
2949 
2950 /***************************************************************************//**
2951   The MSS_UART_disable_afclear () function is used to disable address flag
2952   clear of the MSS UART. This should be used in conjunction with address flag
2953   detection mode (AFM).
2954 
2955   @param this_uart
2956     The this_uart parameter is a pointer to an mss_uart_instance_t
2957     structure identifying the MSS UART hardware block that will perform
2958     the requested function. There are ten such data structures,
2959     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
2960     when they are connected on the AXI switch slave 5 (main APB bus) and
2961     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
2962     when they are connected on the AXI switch slave 6 (AMP APB bus).
2963     This parameter must point to one of these ten global data structure defined
2964     within the UART driver.
2965 
2966     Note that if you are using the UART on the AMP APB bus, the hardware
2967     configuration to connect UART on AMP APB bus must already be done by the
2968     application using SYSREG registers before initializing the UART instance
2969     structure.
2970 
2971   @return
2972     This function does not return a value.
2973 
2974   Example:
2975   @code
2976     MSS_UART_init(&g_mss_uart0_lo,
2977              MSS_UART_57600_BAUD,
2978              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
2979 
2980     MSS_UART_disable_afclear(&g_mss_uart0_lo);
2981   @endcode
2982  */
2983 void
2984 MSS_UART_disable_afclear
2985 (
2986      mss_uart_instance_t * this_uart
2987 );
2988 
2989 /***************************************************************************//**
2990   The MSS_UART_enable_rx_timeout() function is used to enable and configure
2991   the receiver timeout functionality of MSS UART. This function accepts the
2992   timeout parameter and applies the timeout based up on the baud rate as per
2993   the formula 4 x timeout x bit time.
2994 
2995   @param this_uart
2996     The this_uart parameter is a pointer to an mss_uart_instance_t
2997     structure identifying the MSS UART hardware block that will perform
2998     the requested function. There are ten such data structures,
2999     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3000     when they are connected on the AXI switch slave 5 (main APB bus) and
3001     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3002     when they are connected on the AXI switch slave 6 (AMP APB bus).
3003     This parameter must point to one of these ten global data structure defined
3004     within the UART driver.
3005 
3006   @param timeout
3007     The timeout parameter specifies the receiver timeout multiple.
3008     It should be configured according to the baud rate in use.
3009 
3010   @return
3011     This function does not return a value.
3012 
3013   Example:
3014   @code
3015     MSS_UART_init(&g_mss_uart0_lo,
3016              MSS_UART_57600_BAUD,
3017              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3018 
3019     MSS_UART_enable_rx_timeout(&g_mss_uart0_lo, 24);
3020   @endcode
3021  */
3022 void
3023 MSS_UART_enable_rx_timeout
3024 (
3025     mss_uart_instance_t * this_uart,
3026     uint8_t timeout
3027 );
3028 
3029 /***************************************************************************//**
3030   The MSS_UART_disable_rx_timeout() function is used to disable the receiver
3031   timeout functionality of MSS UART.
3032 
3033   @param this_uart
3034     The this_uart parameter is a pointer to an mss_uart_instance_t
3035     structure identifying the MSS UART hardware block that will perform
3036     the requested function. There are ten such data structures,
3037     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3038     when they are connected on the AXI switch slave 5 (main APB bus) and
3039     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3040     when they are connected on the AXI switch slave 6 (AMP APB bus).
3041     This parameter must point to one of these ten global data structure defined
3042     within the UART driver.
3043 
3044     Note that if you are using the UART on the AMP APB bus, the hardware
3045     configuration to connect UART on AMP APB bus must already be done by the
3046     application using SYSREG registers before initializing the UART instance
3047     structure.
3048 
3049   @return
3050     This function does not return a value.
3051 
3052   Example:
3053   @code
3054     MSS_UART_init(&g_mss_uart0_lo,
3055              MSS_UART_57600_BAUD,
3056              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3057 
3058     MSS_UART_disable_rx_timeout(&g_mss_uart0_lo);
3059   @endcode
3060  */
3061 void
3062 MSS_UART_disable_rx_timeout
3063 (
3064     mss_uart_instance_t * this_uart
3065 );
3066 
3067 /***************************************************************************//**
3068   The MSS_UART_enable_tx_time_guard() function is used to enable and configure
3069   the transmitter time guard functionality of MSS UART. This function accepts
3070   the timeguard parameter and applies the timeguard based up on the baud rate
3071   as per the formula timeguard x bit time.
3072 
3073   @param this_uart
3074     The this_uart parameter is a pointer to an mss_uart_instance_t
3075     structure identifying the MSS UART hardware block that will perform
3076     the requested function. There are ten such data structures,
3077     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3078     when they are connected on the AXI switch slave 5 (main APB bus) and
3079     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3080     when they are connected on the AXI switch slave 6 (AMP APB bus).
3081     This parameter must point to one of these ten global data structure defined
3082     within the UART driver.
3083 
3084     Note that if you are using the UART on the AMP APB bus, the hardware
3085     configuration to connect UART on AMP APB bus must already be done by the
3086     application using SYSREG registers before initializing the UART instance
3087     structure.
3088 
3089   @param timeguard
3090     The timeguard parameter specifies the transmitter time guard multiple.
3091     It should be configured according to the baud rate in use.
3092 
3093   @return
3094     This function does not return a value.
3095 
3096   Example:
3097   @code
3098     MSS_UART_init(&g_mss_uart0_lo,
3099              MSS_UART_57600_BAUD,
3100              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3101 
3102     MSS_UART_enable_tx_time_guard(&g_mss_uart0_lo, 24);
3103   @endcode
3104  */
3105 void
3106 MSS_UART_enable_tx_time_guard
3107 (
3108     mss_uart_instance_t * this_uart,
3109     uint8_t timeguard
3110 );
3111 
3112 /***************************************************************************//**
3113   The MSS_UART_disable_tx_time_guard() function is used to disable the
3114   transmitter time guard functionality of MSS UART.
3115 
3116   @param this_uart
3117     The this_uart parameter is a pointer to an mss_uart_instance_t
3118     structure identifying the MSS UART hardware block that will perform
3119     the requested function. There are ten such data structures,
3120     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3121     when they are connected on the AXI switch slave 5 (main APB bus) and
3122     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3123     when they are connected on the AXI switch slave 6 (AMP APB bus).
3124     This parameter must point to one of these ten global data structure defined
3125     within the UART driver.
3126 
3127     Note that if you are using the UART on the AMP APB bus, the hardware
3128     configuration to connect UART on AMP APB bus must already be done by the
3129     application using SYSREG registers before initializing the UART instance
3130     structure.
3131 
3132   @return
3133     This function does not return a value.
3134 
3135   Example:
3136   @code
3137     MSS_UART_init(&g_mss_uart0_lo,
3138              MSS_UART_57600_BAUD,
3139              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3140 
3141     MSS_UART_disable_tx_time_guard(&g_mss_uart0_lo);
3142   @endcode
3143  */
3144 void
3145 MSS_UART_disable_tx_time_guard
3146 (
3147     mss_uart_instance_t * this_uart
3148 );
3149 
3150 /***************************************************************************//**
3151   The MSS_UART_set_address() function is used to set the 8-bit address for
3152   the MSS UART referenced by this_uart parameter.
3153 
3154   @param this_uart
3155     The this_uart parameter is a pointer to an mss_uart_instance_t
3156     structure identifying the MSS UART hardware block that will perform
3157     the requested function. There are ten such data structures,
3158     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3159     when they are connected on the AXI switch slave 5 (main APB bus) and
3160     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3161     when they are connected on the AXI switch slave 6 (AMP APB bus).
3162     This parameter must point to one of these ten global data structure defined
3163     within the UART driver.
3164 
3165   @param address
3166     The address parameter is the 8-bit address which is to be configured
3167     to the MSS UART referenced by this_uart parameter.
3168 
3169   @return
3170     This function does not return a value.
3171 
3172   Example:
3173   @code
3174     MSS_UART_init(&g_mss_uart0_lo,
3175              MSS_UART_57600_BAUD,
3176              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3177 
3178     MSS_UART_set_address(&g_mss_uart0_lo, 0xAA);
3179   @endcode
3180  */
3181 void
3182 MSS_UART_set_address
3183 (
3184     mss_uart_instance_t * this_uart,
3185     uint8_t address
3186 );
3187 
3188 /***************************************************************************//**
3189   The MSS_UART_set_ready_mode() function is used to configure the MODE0 or MODE1
3190   to the TXRDY and RXRDY signals of the MSS UART referenced by this_uart
3191   parameter. The mode parameter is used to provide the mode to be configured.
3192 
3193   @param this_uart
3194     The this_uart parameter is a pointer to an mss_uart_instance_t
3195     structure identifying the MSS UART hardware block that will perform
3196     the requested function. There are ten such data structures,
3197     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3198     when they are connected on the AXI switch slave 5 (main APB bus) and
3199     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3200     when they are connected on the AXI switch slave 6 (AMP APB bus).
3201     This parameter must point to one of these ten global data structure defined
3202     within the UART driver.
3203 
3204   @param mode
3205     The mode parameter is the mss_uart_ready_mode_t type which is used to
3206     configure the TXRDY and RXRDY signal modes.
3207 
3208   @return
3209     This function does not return a value.
3210 
3211   Example:
3212   @code
3213     MSS_UART_init(&g_mss_uart0_lo,
3214              MSS_UART_57600_BAUD,
3215              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3216 
3217     MSS_UART_set_ready_mode(&g_mss_uart0_lo, MSS_UART_READY_MODE0);
3218   @endcode
3219  */
3220 void
3221 MSS_UART_set_ready_mode
3222 (
3223     mss_uart_instance_t * this_uart,
3224     mss_uart_ready_mode_t mode
3225 );
3226 
3227 /***************************************************************************//**
3228   The MSS_UART_set_usart_mode() function is used to configure the MSS UART
3229   referenced by the parameter this_uart in USART mode. Various USART modes
3230   are supported which can be configured by the parameter mode of type
3231   mss_uart_usart_mode_t.
3232 
3233   @param this_uart
3234     The this_uart parameter is a pointer to an mss_uart_instance_t
3235     structure identifying the MSS UART hardware block that will perform
3236     the requested function. There are ten such data structures,
3237     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3238     when they are connected on the AXI switch slave 5 (main APB bus) and
3239     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3240     when they are connected on the AXI switch slave 6 (AMP APB bus).
3241     This parameter must point to one of these ten global data structure defined
3242     within the UART driver.
3243 
3244   @param mode
3245     The mode parameter is the USART mode to be configured.
3246     This parameter is of type mss_uart_usart_mode_t.
3247 
3248   @return
3249     This function does not return a value.
3250 
3251   Example:
3252   @code
3253     MSS_UART_init(&g_mss_uart0_lo,
3254              MSS_UART_57600_BAUD,
3255              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3256 
3257     MSS_UART_set_usart_mode(&g_mss_uart0_lo, MSS_UART_SYNC_MASTER_POS_EDGE_CLK);
3258   @endcode
3259  */
3260 void
3261 MSS_UART_set_usart_mode
3262 (
3263     mss_uart_instance_t * this_uart,
3264     mss_uart_usart_mode_t mode
3265 );
3266 
3267 /***************************************************************************//**
3268   The MSS_UART_enable_local_irq() function is used to enable the MMUART
3269   interrupt as a local interrupt to the hart rather than via PLIC.
3270   MMUART interrupt can be configured to trigger an interrupt via PLIC or it
3271   can be configured to trigger a local interrupt. The arrangement is such that
3272   the UART0 interrupt can appear as local interrupt on E51. The UART1 to UART4
3273   interrupts can appear as local interrupt to U51_1 to U54_4 respectively.
3274   The UART0 to UART4 can appear as PLIC interrupt. Multiple HARTs can enable
3275   and receive the PLIC interrupt, the HART that claims the interrupt processes
3276   it. For rest of the HARTs the IRQ gets silently skipped as the interrupt
3277   claim has already been taken.
3278 
3279   By default, the PLIC interrupt is enabled by this driver when
3280   MSS_UART_enable_irq() or the APIs to set the interrupt handler is called.
3281   To enable the local interrupt application must explicitly call
3282   MSS_UART_enable_local_irq() function. Note that this function disables the
3283   interrupt over PLIC if it was previously enabled.
3284 
3285   This function must be called after the MMUART is initialized, the required
3286   interrupt hander functions are set and before initiating any data transfers.
3287   If you want to register multiple register handlers such as tx handler, rx
3288   handler etc. then this function must be called after all such handlers are set.
3289 
3290   Call to this function is treated as one time activity. The driver gives no
3291   option to disable the local interrupt and enable the PLIC interrupt again at
3292   runtime.
3293 
3294   @param this_uart
3295     The this_uart parameter is a pointer to an mss_uart_instance_t
3296     structure identifying the MSS UART hardware block that will perform
3297     the requested function. There are ten such data structures,
3298     g_mss_uart0_lo to g_mss_uart4_lo, associated with MSS UART0 to MSS UART4
3299     when they are connected on the AXI switch slave 5 (main APB bus) and
3300     g_mss_uart0_hi to g_mss_uart4_hi, associated with MSS UART0 to MSS UART4
3301     when they are connected on the AXI switch slave 6 (AMP APB bus).
3302     This parameter must point to one of these ten global data structure defined
3303     within the UART driver.
3304 
3305   @return
3306     This function does not return a value.
3307 
3308   Example:
3309   @code
3310 
3311 
3312     __enable_irq();
3313     MSS_UART_init(&g_mss_uart0_lo,
3314              MSS_UART_57600_BAUD,
3315              MSS_UART_DATA_8_BITS | MSS_UART_NO_PARITY | MSS_UART_ONE_STOP_BIT);
3316 
3317     MSS_UART_set_rx_handler(&g_mss_uart0_lo,
3318                             uart0_rx_handler,
3319                             MSS_UART_FIFO_SINGLE_BYTE);
3320 
3321     MSS_UART_enable_local_irq(&g_mss_uart0_lo);
3322 
3323   @endcode
3324  */
3325 void
3326 MSS_UART_enable_local_irq
3327 (
3328     mss_uart_instance_t * this_uart
3329 );
3330 
3331 #ifdef __cplusplus
3332 }
3333 #endif
3334 
3335 #endif /* __MSS_UART_H_ */
3336