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