1 // Copyright 2024, Linaro Limited 2 // Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org> 3 // SPDX-License-Identifier: GPL-2.0-or-later 4 // 5 // PL011 QEMU Device Model 6 // 7 // This library implements a device model for the PrimeCell® UART (PL011) 8 // device in QEMU. 9 // 10 #![doc = include_str!("../README.md")] 11 //! # Library crate 12 //! 13 //! See [`PL011State`](crate::device::PL011State) for the device model type and 14 //! the [`registers`] module for register types. 15 16 #![deny( 17 clippy::correctness, 18 clippy::suspicious, 19 clippy::complexity, 20 clippy::perf, 21 clippy::cargo, 22 clippy::nursery, 23 clippy::style 24 )] 25 #![allow(clippy::upper_case_acronyms)] 26 #![allow(clippy::result_unit_err)] 27 28 extern crate bilge; 29 extern crate bilge_impl; 30 extern crate qemu_api; 31 32 use qemu_api::c_str; 33 34 pub mod device; 35 pub mod device_class; 36 pub mod memory_ops; 37 38 pub const TYPE_PL011: &::std::ffi::CStr = c_str!("pl011"); 39 pub const TYPE_PL011_LUMINARY: &::std::ffi::CStr = c_str!("pl011_luminary"); 40 41 /// Offset of each register from the base memory address of the device. 42 /// 43 /// # Source 44 /// ARM DDI 0183G, Table 3-1 p.3-3 45 #[doc(alias = "offset")] 46 #[allow(non_camel_case_types)] 47 #[repr(u64)] 48 #[derive(Debug)] 49 pub enum RegisterOffset { 50 /// Data Register 51 /// 52 /// A write to this register initiates the actual data transmission 53 #[doc(alias = "UARTDR")] 54 DR = 0x000, 55 /// Receive Status Register or Error Clear Register 56 #[doc(alias = "UARTRSR")] 57 #[doc(alias = "UARTECR")] 58 RSR = 0x004, 59 /// Flag Register 60 /// 61 /// A read of this register shows if transmission is complete 62 #[doc(alias = "UARTFR")] 63 FR = 0x018, 64 /// Fractional Baud Rate Register 65 /// 66 /// responsible for baud rate speed 67 #[doc(alias = "UARTFBRD")] 68 FBRD = 0x028, 69 /// `IrDA` Low-Power Counter Register 70 #[doc(alias = "UARTILPR")] 71 ILPR = 0x020, 72 /// Integer Baud Rate Register 73 /// 74 /// Responsible for baud rate speed 75 #[doc(alias = "UARTIBRD")] 76 IBRD = 0x024, 77 /// line control register (data frame format) 78 #[doc(alias = "UARTLCR_H")] 79 LCR_H = 0x02C, 80 /// Toggle UART, transmission or reception 81 #[doc(alias = "UARTCR")] 82 CR = 0x030, 83 /// Interrupt FIFO Level Select Register 84 #[doc(alias = "UARTIFLS")] 85 FLS = 0x034, 86 /// Interrupt Mask Set/Clear Register 87 #[doc(alias = "UARTIMSC")] 88 IMSC = 0x038, 89 /// Raw Interrupt Status Register 90 #[doc(alias = "UARTRIS")] 91 RIS = 0x03C, 92 /// Masked Interrupt Status Register 93 #[doc(alias = "UARTMIS")] 94 MIS = 0x040, 95 /// Interrupt Clear Register 96 #[doc(alias = "UARTICR")] 97 ICR = 0x044, 98 /// DMA control Register 99 #[doc(alias = "UARTDMACR")] 100 DMACR = 0x048, 101 ///// Reserved, offsets `0x04C` to `0x07C`. 102 //Reserved = 0x04C, 103 } 104 105 impl core::convert::TryFrom<u64> for RegisterOffset { 106 type Error = u64; 107 108 fn try_from(value: u64) -> Result<Self, Self::Error> { 109 macro_rules! case { 110 ($($discriminant:ident),*$(,)*) => { 111 /* check that matching on all macro arguments compiles, which means we are not 112 * missing any enum value; if the type definition ever changes this will stop 113 * compiling. 114 */ 115 const fn _assert_exhaustive(val: RegisterOffset) { 116 match val { 117 $(RegisterOffset::$discriminant => (),)* 118 } 119 } 120 121 match value { 122 $(x if x == Self::$discriminant as u64 => Ok(Self::$discriminant),)* 123 _ => Err(value), 124 } 125 } 126 } 127 case! { DR, RSR, FR, FBRD, ILPR, IBRD, LCR_H, CR, FLS, IMSC, RIS, MIS, ICR, DMACR } 128 } 129 } 130 131 pub mod registers { 132 //! Device registers exposed as typed structs which are backed by arbitrary 133 //! integer bitmaps. [`Data`], [`Control`], [`LineControl`], etc. 134 use bilge::prelude::*; 135 136 /// Receive Status Register / Data Register common error bits 137 /// 138 /// The `UARTRSR` register is updated only when a read occurs 139 /// from the `UARTDR` register with the same status information 140 /// that can also be obtained by reading the `UARTDR` register 141 #[bitsize(8)] 142 #[derive(Clone, Copy, Default, DebugBits, FromBits)] 143 pub struct Errors { 144 pub framing_error: bool, 145 pub parity_error: bool, 146 pub break_error: bool, 147 pub overrun_error: bool, 148 _reserved_unpredictable: u4, 149 } 150 151 // TODO: FIFO Mode has different semantics 152 /// Data Register, `UARTDR` 153 /// 154 /// The `UARTDR` register is the data register. 155 /// 156 /// For words to be transmitted: 157 /// 158 /// - if the FIFOs are enabled, data written to this location is pushed onto 159 /// the transmit 160 /// FIFO 161 /// - if the FIFOs are not enabled, data is stored in the transmitter 162 /// holding register (the 163 /// bottom word of the transmit FIFO). 164 /// 165 /// The write operation initiates transmission from the UART. The data is 166 /// prefixed with a start bit, appended with the appropriate parity bit 167 /// (if parity is enabled), and a stop bit. The resultant word is then 168 /// transmitted. 169 /// 170 /// For received words: 171 /// 172 /// - if the FIFOs are enabled, the data byte and the 4-bit status (break, 173 /// frame, parity, 174 /// and overrun) is pushed onto the 12-bit wide receive FIFO 175 /// - if the FIFOs are not enabled, the data byte and status are stored in 176 /// the receiving 177 /// holding register (the bottom word of the receive FIFO). 178 /// 179 /// The received data byte is read by performing reads from the `UARTDR` 180 /// register along with the corresponding status information. The status 181 /// information can also be read by a read of the `UARTRSR/UARTECR` 182 /// register. 183 /// 184 /// # Note 185 /// 186 /// You must disable the UART before any of the control registers are 187 /// reprogrammed. When the UART is disabled in the middle of 188 /// transmission or reception, it completes the current character before 189 /// stopping. 190 /// 191 /// # Source 192 /// ARM DDI 0183G 3.3.1 Data Register, UARTDR 193 #[bitsize(32)] 194 #[derive(Clone, Copy, Default, DebugBits, FromBits)] 195 #[doc(alias = "UARTDR")] 196 pub struct Data { 197 pub data: u8, 198 pub errors: Errors, 199 _reserved: u16, 200 } 201 202 impl Data { 203 // bilge is not very const-friendly, unfortunately 204 pub const BREAK: Self = Self { value: 1 << 10 }; 205 } 206 207 // TODO: FIFO Mode has different semantics 208 /// Receive Status Register / Error Clear Register, `UARTRSR/UARTECR` 209 /// 210 /// The UARTRSR/UARTECR register is the receive status register/error clear 211 /// register. Receive status can also be read from the `UARTRSR` 212 /// register. If the status is read from this register, then the status 213 /// information for break, framing and parity corresponds to the 214 /// data character read from the [Data register](Data), `UARTDR` prior to 215 /// reading the UARTRSR register. The status information for overrun is 216 /// set immediately when an overrun condition occurs. 217 /// 218 /// 219 /// # Note 220 /// The received data character must be read first from the [Data 221 /// Register](Data), `UARTDR` before reading the error status associated 222 /// with that data character from the `UARTRSR` register. This read 223 /// sequence cannot be reversed, because the `UARTRSR` register is 224 /// updated only when a read occurs from the `UARTDR` register. However, 225 /// the status information can also be obtained by reading the `UARTDR` 226 /// register 227 /// 228 /// # Source 229 /// ARM DDI 0183G 3.3.2 Receive Status Register/Error Clear Register, 230 /// UARTRSR/UARTECR 231 #[bitsize(32)] 232 #[derive(Clone, Copy, DebugBits, FromBits)] 233 pub struct ReceiveStatusErrorClear { 234 pub errors: Errors, 235 _reserved_unpredictable: u24, 236 } 237 238 impl ReceiveStatusErrorClear { 239 pub fn set_from_data(&mut self, data: Data) { 240 self.set_errors(data.errors()); 241 } 242 243 pub fn reset(&mut self) { 244 // All the bits are cleared to 0 on reset. 245 *self = Self::default(); 246 } 247 } 248 249 impl Default for ReceiveStatusErrorClear { 250 fn default() -> Self { 251 0.into() 252 } 253 } 254 255 #[bitsize(32)] 256 #[derive(Clone, Copy, DebugBits, FromBits)] 257 /// Flag Register, `UARTFR` 258 #[doc(alias = "UARTFR")] 259 pub struct Flags { 260 /// CTS Clear to send. This bit is the complement of the UART clear to 261 /// send, `nUARTCTS`, modem status input. That is, the bit is 1 262 /// when `nUARTCTS` is LOW. 263 pub clear_to_send: bool, 264 /// DSR Data set ready. This bit is the complement of the UART data set 265 /// ready, `nUARTDSR`, modem status input. That is, the bit is 1 when 266 /// `nUARTDSR` is LOW. 267 pub data_set_ready: bool, 268 /// DCD Data carrier detect. This bit is the complement of the UART data 269 /// carrier detect, `nUARTDCD`, modem status input. That is, the bit is 270 /// 1 when `nUARTDCD` is LOW. 271 pub data_carrier_detect: bool, 272 /// BUSY UART busy. If this bit is set to 1, the UART is busy 273 /// transmitting data. This bit remains set until the complete 274 /// byte, including all the stop bits, has been sent from the 275 /// shift register. This bit is set as soon as the transmit FIFO 276 /// becomes non-empty, regardless of whether the UART is enabled 277 /// or not. 278 pub busy: bool, 279 /// RXFE Receive FIFO empty. The meaning of this bit depends on the 280 /// state of the FEN bit in the UARTLCR_H register. If the FIFO 281 /// is disabled, this bit is set when the receive holding 282 /// register is empty. If the FIFO is enabled, the RXFE bit is 283 /// set when the receive FIFO is empty. 284 pub receive_fifo_empty: bool, 285 /// TXFF Transmit FIFO full. The meaning of this bit depends on the 286 /// state of the FEN bit in the UARTLCR_H register. If the FIFO 287 /// is disabled, this bit is set when the transmit holding 288 /// register is full. If the FIFO is enabled, the TXFF bit is 289 /// set when the transmit FIFO is full. 290 pub transmit_fifo_full: bool, 291 /// RXFF Receive FIFO full. The meaning of this bit depends on the state 292 /// of the FEN bit in the UARTLCR_H register. If the FIFO is 293 /// disabled, this bit is set when the receive holding register 294 /// is full. If the FIFO is enabled, the RXFF bit is set when 295 /// the receive FIFO is full. 296 pub receive_fifo_full: bool, 297 /// Transmit FIFO empty. The meaning of this bit depends on the state of 298 /// the FEN bit in the [Line Control register](LineControl), 299 /// `UARTLCR_H`. If the FIFO is disabled, this bit is set when the 300 /// transmit holding register is empty. If the FIFO is enabled, 301 /// the TXFE bit is set when the transmit FIFO is empty. This 302 /// bit does not indicate if there is data in the transmit shift 303 /// register. 304 pub transmit_fifo_empty: bool, 305 /// `RI`, is `true` when `nUARTRI` is `LOW`. 306 pub ring_indicator: bool, 307 _reserved_zero_no_modify: u23, 308 } 309 310 impl Flags { 311 pub fn reset(&mut self) { 312 *self = Self::default(); 313 } 314 } 315 316 impl Default for Flags { 317 fn default() -> Self { 318 let mut ret: Self = 0.into(); 319 // After reset TXFF, RXFF, and BUSY are 0, and TXFE and RXFE are 1 320 ret.set_receive_fifo_empty(true); 321 ret.set_transmit_fifo_empty(true); 322 ret 323 } 324 } 325 326 #[bitsize(32)] 327 #[derive(Clone, Copy, DebugBits, FromBits)] 328 /// Line Control Register, `UARTLCR_H` 329 #[doc(alias = "UARTLCR_H")] 330 pub struct LineControl { 331 /// BRK Send break. 332 /// 333 /// If this bit is set to `1`, a low-level is continually output on the 334 /// `UARTTXD` output, after completing transmission of the 335 /// current character. For the proper execution of the break command, 336 /// the software must set this bit for at least two complete 337 /// frames. For normal use, this bit must be cleared to `0`. 338 pub send_break: bool, 339 /// 1 PEN Parity enable: 340 /// 341 /// - 0 = parity is disabled and no parity bit added to the data frame 342 /// - 1 = parity checking and generation is enabled. 343 /// 344 /// See Table 3-11 on page 3-14 for the parity truth table. 345 pub parity_enabled: bool, 346 /// EPS Even parity select. Controls the type of parity the UART uses 347 /// during transmission and reception: 348 /// - 0 = odd parity. The UART generates or checks for an odd number of 349 /// 1s in the data and parity bits. 350 /// - 1 = even parity. The UART generates or checks for an even number 351 /// of 1s in the data and parity bits. 352 /// This bit has no effect when the `PEN` bit disables parity checking 353 /// and generation. See Table 3-11 on page 3-14 for the parity 354 /// truth table. 355 pub parity: Parity, 356 /// 3 STP2 Two stop bits select. If this bit is set to 1, two stop bits 357 /// are transmitted at the end of the frame. The receive 358 /// logic does not check for two stop bits being received. 359 pub two_stops_bits: bool, 360 /// FEN Enable FIFOs: 361 /// 0 = FIFOs are disabled (character mode) that is, the FIFOs become 362 /// 1-byte-deep holding registers 1 = transmit and receive FIFO 363 /// buffers are enabled (FIFO mode). 364 pub fifos_enabled: Mode, 365 /// WLEN Word length. These bits indicate the number of data bits 366 /// transmitted or received in a frame as follows: b11 = 8 bits 367 /// b10 = 7 bits 368 /// b01 = 6 bits 369 /// b00 = 5 bits. 370 pub word_length: WordLength, 371 /// 7 SPS Stick parity select. 372 /// 0 = stick parity is disabled 373 /// 1 = either: 374 /// • if the EPS bit is 0 then the parity bit is transmitted and checked 375 /// as a 1 • if the EPS bit is 1 then the parity bit is 376 /// transmitted and checked as a 0. This bit has no effect when 377 /// the PEN bit disables parity checking and generation. See Table 3-11 378 /// on page 3-14 for the parity truth table. 379 pub sticky_parity: bool, 380 /// 31:8 - Reserved, do not modify, read as zero. 381 _reserved_zero_no_modify: u24, 382 } 383 384 impl LineControl { 385 pub fn reset(&mut self) { 386 // All the bits are cleared to 0 when reset. 387 *self = 0.into(); 388 } 389 } 390 391 impl Default for LineControl { 392 fn default() -> Self { 393 0.into() 394 } 395 } 396 397 #[bitsize(1)] 398 #[derive(Clone, Copy, Debug, Eq, FromBits, PartialEq)] 399 /// `EPS` "Even parity select", field of [Line Control 400 /// register](LineControl). 401 pub enum Parity { 402 /// - 0 = odd parity. The UART generates or checks for an odd number of 403 /// 1s in the data and parity bits. 404 Odd = 0, 405 /// - 1 = even parity. The UART generates or checks for an even number 406 /// of 1s in the data and parity bits. 407 Even = 1, 408 } 409 410 #[bitsize(1)] 411 #[derive(Clone, Copy, Debug, Eq, FromBits, PartialEq)] 412 /// `FEN` "Enable FIFOs" or Device mode, field of [Line Control 413 /// register](LineControl). 414 pub enum Mode { 415 /// 0 = FIFOs are disabled (character mode) that is, the FIFOs become 416 /// 1-byte-deep holding registers 417 Character = 0, 418 /// 1 = transmit and receive FIFO buffers are enabled (FIFO mode). 419 FIFO = 1, 420 } 421 422 impl From<Mode> for bool { 423 fn from(val: Mode) -> Self { 424 matches!(val, Mode::FIFO) 425 } 426 } 427 428 #[bitsize(2)] 429 #[derive(Clone, Copy, Debug, Eq, FromBits, PartialEq)] 430 /// `WLEN` Word length, field of [Line Control register](LineControl). 431 /// 432 /// These bits indicate the number of data bits transmitted or received in a 433 /// frame as follows: 434 pub enum WordLength { 435 /// b11 = 8 bits 436 _8Bits = 0b11, 437 /// b10 = 7 bits 438 _7Bits = 0b10, 439 /// b01 = 6 bits 440 _6Bits = 0b01, 441 /// b00 = 5 bits. 442 _5Bits = 0b00, 443 } 444 445 /// Control Register, `UARTCR` 446 /// 447 /// The `UARTCR` register is the control register. All the bits are cleared 448 /// to `0` on reset except for bits `9` and `8` that are set to `1`. 449 /// 450 /// # Source 451 /// ARM DDI 0183G, 3.3.8 Control Register, `UARTCR`, Table 3-12 452 #[bitsize(32)] 453 #[doc(alias = "UARTCR")] 454 #[derive(Clone, Copy, DebugBits, FromBits)] 455 pub struct Control { 456 /// `UARTEN` UART enable: 0 = UART is disabled. If the UART is disabled 457 /// in the middle of transmission or reception, it completes the current 458 /// character before stopping. 1 = the UART is enabled. Data 459 /// transmission and reception occurs for either UART signals or SIR 460 /// signals depending on the setting of the SIREN bit. 461 pub enable_uart: bool, 462 /// `SIREN` `SIR` enable: 0 = IrDA SIR ENDEC is disabled. `nSIROUT` 463 /// remains LOW (no light pulse generated), and signal transitions on 464 /// SIRIN have no effect. 1 = IrDA SIR ENDEC is enabled. Data is 465 /// transmitted and received on nSIROUT and SIRIN. UARTTXD remains HIGH, 466 /// in the marking state. Signal transitions on UARTRXD or modem status 467 /// inputs have no effect. This bit has no effect if the UARTEN bit 468 /// disables the UART. 469 pub enable_sir: bool, 470 /// `SIRLP` SIR low-power IrDA mode. This bit selects the IrDA encoding 471 /// mode. If this bit is cleared to 0, low-level bits are transmitted as 472 /// an active high pulse with a width of 3/ 16th of the bit period. If 473 /// this bit is set to 1, low-level bits are transmitted with a pulse 474 /// width that is 3 times the period of the IrLPBaud16 input signal, 475 /// regardless of the selected bit rate. Setting this bit uses less 476 /// power, but might reduce transmission distances. 477 pub sir_lowpower_irda_mode: u1, 478 /// Reserved, do not modify, read as zero. 479 _reserved_zero_no_modify: u4, 480 /// `LBE` Loopback enable. If this bit is set to 1 and the SIREN bit is 481 /// set to 1 and the SIRTEST bit in the Test Control register, UARTTCR 482 /// on page 4-5 is set to 1, then the nSIROUT path is inverted, and fed 483 /// through to the SIRIN path. The SIRTEST bit in the test register must 484 /// be set to 1 to override the normal half-duplex SIR operation. This 485 /// must be the requirement for accessing the test registers during 486 /// normal operation, and SIRTEST must be cleared to 0 when loopback 487 /// testing is finished. This feature reduces the amount of external 488 /// coupling required during system test. If this bit is set to 1, and 489 /// the SIRTEST bit is set to 0, the UARTTXD path is fed through to the 490 /// UARTRXD path. In either SIR mode or UART mode, when this bit is set, 491 /// the modem outputs are also fed through to the modem inputs. This bit 492 /// is cleared to 0 on reset, to disable loopback. 493 pub enable_loopback: bool, 494 /// `TXE` Transmit enable. If this bit is set to 1, the transmit section 495 /// of the UART is enabled. Data transmission occurs for either UART 496 /// signals, or SIR signals depending on the setting of the SIREN bit. 497 /// When the UART is disabled in the middle of transmission, it 498 /// completes the current character before stopping. 499 pub enable_transmit: bool, 500 /// `RXE` Receive enable. If this bit is set to 1, the receive section 501 /// of the UART is enabled. Data reception occurs for either UART 502 /// signals or SIR signals depending on the setting of the SIREN bit. 503 /// When the UART is disabled in the middle of reception, it completes 504 /// the current character before stopping. 505 pub enable_receive: bool, 506 /// `DTR` Data transmit ready. This bit is the complement of the UART 507 /// data transmit ready, `nUARTDTR`, modem status output. That is, when 508 /// the bit is programmed to a 1 then `nUARTDTR` is LOW. 509 pub data_transmit_ready: bool, 510 /// `RTS` Request to send. This bit is the complement of the UART 511 /// request to send, `nUARTRTS`, modem status output. That is, when the 512 /// bit is programmed to a 1 then `nUARTRTS` is LOW. 513 pub request_to_send: bool, 514 /// `Out1` This bit is the complement of the UART Out1 (`nUARTOut1`) 515 /// modem status output. That is, when the bit is programmed to a 1 the 516 /// output is 0. For DTE this can be used as Data Carrier Detect (DCD). 517 pub out_1: bool, 518 /// `Out2` This bit is the complement of the UART Out2 (`nUARTOut2`) 519 /// modem status output. That is, when the bit is programmed to a 1, the 520 /// output is 0. For DTE this can be used as Ring Indicator (RI). 521 pub out_2: bool, 522 /// `RTSEn` RTS hardware flow control enable. If this bit is set to 1, 523 /// RTS hardware flow control is enabled. Data is only requested when 524 /// there is space in the receive FIFO for it to be received. 525 pub rts_hardware_flow_control_enable: bool, 526 /// `CTSEn` CTS hardware flow control enable. If this bit is set to 1, 527 /// CTS hardware flow control is enabled. Data is only transmitted when 528 /// the `nUARTCTS` signal is asserted. 529 pub cts_hardware_flow_control_enable: bool, 530 /// 31:16 - Reserved, do not modify, read as zero. 531 _reserved_zero_no_modify2: u16, 532 } 533 534 impl Control { 535 pub fn reset(&mut self) { 536 *self = 0.into(); 537 self.set_enable_receive(true); 538 self.set_enable_transmit(true); 539 } 540 } 541 542 impl Default for Control { 543 fn default() -> Self { 544 let mut ret: Self = 0.into(); 545 ret.reset(); 546 ret 547 } 548 } 549 550 /// Interrupt status bits in UARTRIS, UARTMIS, UARTIMSC 551 pub const INT_OE: u32 = 1 << 10; 552 pub const INT_BE: u32 = 1 << 9; 553 pub const INT_PE: u32 = 1 << 8; 554 pub const INT_FE: u32 = 1 << 7; 555 pub const INT_RT: u32 = 1 << 6; 556 pub const INT_TX: u32 = 1 << 5; 557 pub const INT_RX: u32 = 1 << 4; 558 pub const INT_DSR: u32 = 1 << 3; 559 pub const INT_DCD: u32 = 1 << 2; 560 pub const INT_CTS: u32 = 1 << 1; 561 pub const INT_RI: u32 = 1 << 0; 562 pub const INT_E: u32 = INT_OE | INT_BE | INT_PE | INT_FE; 563 pub const INT_MS: u32 = INT_RI | INT_DSR | INT_DCD | INT_CTS; 564 565 #[repr(u32)] 566 pub enum Interrupt { 567 OE = 1 << 10, 568 BE = 1 << 9, 569 PE = 1 << 8, 570 FE = 1 << 7, 571 RT = 1 << 6, 572 TX = 1 << 5, 573 RX = 1 << 4, 574 DSR = 1 << 3, 575 DCD = 1 << 2, 576 CTS = 1 << 1, 577 RI = 1 << 0, 578 } 579 580 impl Interrupt { 581 pub const E: u32 = INT_OE | INT_BE | INT_PE | INT_FE; 582 pub const MS: u32 = INT_RI | INT_DSR | INT_DCD | INT_CTS; 583 } 584 } 585 586 // TODO: You must disable the UART before any of the control registers are 587 // reprogrammed. When the UART is disabled in the middle of transmission or 588 // reception, it completes the current character before stopping 589