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