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
