diff --git a/services/graphics-server/Cargo.toml b/services/graphics-server/Cargo.toml index 7e9aab7ed..5ff401b97 100644 --- a/services/graphics-server/Cargo.toml +++ b/services/graphics-server/Cargo.toml @@ -36,7 +36,12 @@ cramium-hal = { path = "../../libs/cramium-hal", optional = true, features = [ minifb = "0.23.0" [features] -cramium-soc = ["utralib/cramium-soc", "cram-hal-service", "cramium-hal"] +cramium-soc = [ + "utralib/cramium-soc", + "cram-hal-service", + "cramium-hal", + "cramium-hal/std", +] precursor = ["utralib/precursor"] hosted = ["utralib/hosted"] renode = ["utralib/renode"] @@ -44,4 +49,4 @@ debugprint = [] braille = [] gfx-testing = [] ditherpunk = [] -default = [] +default = ["cramium-soc"] diff --git a/services/graphics-server/src/backend/cramium.rs b/services/graphics-server/src/backend/cramium.rs index c24427e9f..09fa547d0 100644 --- a/services/graphics-server/src/backend/cramium.rs +++ b/services/graphics-server/src/backend/cramium.rs @@ -1,74 +1,75 @@ -use cram_hal_service::IframRange; -use cramium_hal::iox; +//! # Display backend for Cramium target +//! +//! There isn't a dedicated memory LCD frame buffer device, so it has to be +//! cobbled together somewhat painfully from a DMA engine and the PIO block. +//! +//! The drawing frame buffer is laid out as 11 words by 536 lines. +//! +//! Each line has 16 extra bits on the MSB of the last word that are used to +//! indicate if the line is dirty. +//! +//! Drawing frame buffer: +//! 0x0000: [data 0, data 1, ... data 0A, data 0B | dirty << 16], +//! 0x000C: [data C, data D, ... data 15, data 16 | dirty << 16], +//! ... +//! +//! The PIO is "dumb" in that it can only shift bits out; however, the memory +//! LCD requires addressing and mode set information on each line. In order +//! to accommodate this, the top 16 unused bits of the previous line is used +//! to encode the addressing and mode set information, referred to as `addr` +//! in the schematic below. +//! +//! So, in the redraw routine, the drawing frame buffer is checked line-by-line +//! to see if the line is dirty; if it is, it is copied to the HW DMA buffer, +//! such that the line *prior* to the current line has the addressing bits +//! for the LCD inserted in the top 16 bits. This means that the first line +//! in the HW DMA buffer is mostly dummy words, plus the address of the first +//! line: +//! +//! HW DMA buffer: +//! 0x0000: [dummy 0, dummy 1, .... dummy 0A, dummy 0B | addr 0 << 16], +//! 0x0030: [data 0, data 1, .... data 0A, data 0B | addr 1 << 16], +//! ... +//! +//! The HW DMA buffer will only contain the dirty lines to blit. Thus, when +//! passing the blit initiation command off to the `cram-hal-service` server, +//! the number of lines to blit must be specified. +//! +//! There are two implementations currently contemplated: one using the PL230+PIO +//! block, and the other using the UDMA block. +//! +//! ## PL230+PIO: +//! +//! The PL230 DMA engine is configured to copy only the specified number +//! of half-words (where a half-word is 16 bits in length) into the PIO block, +//! computed as (23 half-words per line) * (number of lines), with the first +//! half-word originating at the addressing bits on the previous line. Thus the +//! DMA would start at address 0xA, shifting 16 bits of `addr 0` first, then +//! 22 16-bit words consisting of 352 bits of line data, and a final 16 bits of +//! "don't care" (which turns out to be the next line's address info). +//! +//! The PIO engine is configured as a simple 16-bit, LSB-first shift register +//! to send data to the LCD at a rate of 2 MHz, requesting a new word via DMA +//! whenever the shift register is empty. Multi-line mode is used to drive +//! the LCD, so CS should be manually de-asserted at the conclusion of the transfer. +//! In this implementation, setup time on CS is enforced by the PIO with a short +//! pre-amble. +//! +//! ## UDMA: +//! +//! The UDMA engine is configured to send only the specified number of half-words +//! (where a half-word is 16 bits in length) into the SPIM block. I think the CS +//! line should still be managed through a GPIO bit-bang operation, since there +//! is a fairly long setup/hold time requirement on it and there does not seem +//! to be a provision in the UDMA block to put guardbands around the CS timing. + +use cram_hal_service::IoxHal; use cramium_hal::udma::PeriphId; -use utralib::generated::*; -use utralib::utra; +use cramium_hal::{iox, udma}; use xous::MemoryRange; -/// # Display backend for Cramium target -/// -/// There isn't a dedicated memory LCD frame buffer device, so it has to be -/// cobbled together somewhat painfully from a DMA engine and the PIO block. -/// -/// The drawing frame buffer is laid out as 11 words by 536 lines. -/// -/// Each line has 16 extra bits on the MSB of the last word that are used to -/// indicate if the line is dirty. -/// -/// Drawing frame buffer: -/// 0x0000: [data 0, data 1, ... data 0A, data 0B | dirty << 16], -/// 0x000C: [data C, data D, ... data 15, data 16 | dirty << 16], -/// ... -/// -/// The PIO is "dumb" in that it can only shift bits out; however, the memory -/// LCD requires addressing and mode set information on each line. In order -/// to accommodate this, the top 16 unused bits of the previous line is used -/// to encode the addressing and mode set information, referred to as `addr` -/// in the schematic below. -/// -/// So, in the redraw routine, the drawing frame buffer is checked line-by-line -/// to see if the line is dirty; if it is, it is copied to the HW DMA buffer, -/// such that the line *prior* to the current line has the addressing bits -/// for the LCD inserted in the top 16 bits. This means that the first line -/// in the HW DMA buffer is mostly dummy words, plus the address of the first -/// line: -/// -/// HW DMA buffer: -/// 0x0000: [dummy 0, dummy 1, .... dummy 0A, dummy 0B | addr 0 << 16], -/// 0x0030: [data 0, data 1, .... data 0A, data 0B | addr 1 << 16], -/// ... -/// -/// The HW DMA buffer will only contain the dirty lines to blit. Thus, when -/// passing the blit initiation command off to the `cram-hal-service` server, -/// the number of lines to blit must be specified. -/// -/// There are two implementations currently contemplated: one using the PL230+PIO -/// block, and the other using the UDMA block. -/// -/// ## PL230+PIO: -/// -/// The PL230 DMA engine is configured to copy only the specified number -/// of half-words (where a half-word is 16 bits in length) into the PIO block, -/// computed as (23 half-words per line) * (number of lines), with the first -/// half-word originating at the addressing bits on the previous line. Thus the -/// DMA would start at address 0xA, shifting 16 bits of `addr 0` first, then -/// 22 16-bit words consisting of 352 bits of line data, and a final 16 bits of -/// "don't care" (which turns out to be the next line's address info). -/// -/// The PIO engine is configured as a simple 16-bit, LSB-first shift register -/// to send data to the LCD at a rate of 2 MHz, requesting a new word via DMA -/// whenever the shift register is empty. Multi-line mode is used to drive -/// the LCD, so CS should be manually de-asserted at the conclusion of the transfer. -/// In this implementation, setup time on CS is enforced by the PIO with a short -/// pre-amble. -/// -/// ## UDMA: -/// -/// The UDMA engine is configured to send only the specified number of half-words -/// (where a half-word is 16 bits in length) into the SPIM block. I think the CS -/// line should still be managed through a GPIO bit-bang operation, since there -/// is a fairly long setup/hold time requirement on it and there does not seem -/// to be a provision in the UDMA block to put guardbands around the CS timing. +use crate::api::Point; +use crate::api::{LINES, WIDTH}; pub const FB_WIDTH_WORDS: usize = 11; pub const FB_WIDTH_PIXELS: usize = WIDTH as usize; @@ -76,6 +77,11 @@ pub const FB_LINES: usize = LINES as usize; pub const FB_SIZE: usize = FB_WIDTH_WORDS * FB_LINES; // 44 bytes by 536 lines const CONFIG_CLOCK_FREQUENCY: u32 = 100_000_000; +const SPI_CS_PIN: u8 = 10; +const SPI_CLK_PIN: u8 = 7; +const SPI_DAT_PIN: u8 = 8; +const SPI_PORT: iox::IoxPort = iox::IoxPort::PD; + pub struct MainThreadToken(()); pub enum Never {} @@ -89,16 +95,15 @@ pub fn claim_main_thread(f: impl FnOnce(MainThreadToken) -> Never + Send + 'stat pub struct XousDisplay { fb: MemoryRange, - hwfb: cramium_hal::udma::Spim, next_free_line: usize, - srfb: [u32; FB_SIZE], - csr: utralib::CSR, + spim: udma::Spim, devboot: bool, + iox: IoxHal, } impl XousDisplay { pub fn new(_main_thread_token: MainThreadToken) -> XousDisplay { - let fb = xous::syscall::map_memory( + let mut fb = xous::syscall::map_memory( None, None, ((FB_WIDTH_WORDS * FB_LINES * 4) + 4096) & !4095, @@ -118,68 +123,62 @@ impl XousDisplay { // using bank SPIM_B[1] udma_global.udma_clock_config(PeriphId::Spim1, true); - // safety: this is safe because we bind hwfb to XousDisplay which lives for the entire - // duration of the OS. - /////////////// LEFT OFF HERE - let hwfb = unsafe { - cram_hal_service::IframRange::request(4096 * 3, None) - .expect("Couldn't allocate a DMA target for graphics!") + // safety: this is safe because we remembered to set up the clock config; and, + // this binding should live for the lifetime of Xous so we don't have to worry about unmapping. + let spim = unsafe { + cramium_hal::udma::Spim::new( + udma::SpimChannel::Channel1, + 2_000_000, + 100_000_000, + udma::SpimClkPol::LeadingEdgeRise, + udma::SpimClkPha::CaptureOnTrailing, + udma::SpimCs::Cs0, + None, + // one extra line for handling the addressing setup + FB_SIZE + FB_WIDTH_WORDS * 4, + 0, + ) + .expect("Couldn't allocate SPI channel for LCD") }; // setup the I/O pins - let iox = cram_hal_service::IoxHal::new(); + let iox = IoxHal::new(); // SPIM_CLK_B[1] iox.setup_io_pin( - iox::IoxPort::PD, - 7, + SPI_PORT, + SPI_CLK_PIN, Some(iox::IoxDir::Output), Some(iox::IoxFunction::AF2), None, None, - Some(iox::IoxEnable), + Some(iox::IoxEnable::Enable), Some(iox::IoxDriveStrength::Drive2mA), ); // SPIM_SD0_B[1] iox.setup_io_pin( - iox::IoxPort::PD, - 8, + SPI_PORT, + SPI_DAT_PIN, Some(iox::IoxDir::Output), Some(iox::IoxFunction::AF2), None, None, - Some(iox::IoxEnable), + Some(iox::IoxEnable::Enable), Some(iox::IoxDriveStrength::Drive2mA), ); // SPIM_SCSN0_B[1] - as GPIO iox.setup_io_pin( - iox::IoxPort::PD, - 10, + SPI_PORT, + SPI_CS_PIN, Some(iox::IoxDir::Output), Some(iox::IoxFunction::Gpio), None, - Some(iox::IoxEnable), - Some(iox::IoxEnable), + Some(iox::IoxEnable::Enable), + Some(iox::IoxEnable::Enable), Some(iox::IoxDriveStrength::Drive2mA), ); - let control = xous::syscall::map_memory( - xous::MemoryAddress::new(utralib::generated::HW_UDMA_SPIM_1_BASE), - None, - 4096, - xous::MemoryFlags::R | xous::MemoryFlags::W, - ) - .expect("couldn't map control port"); + let mut display = XousDisplay { fb, spim, next_free_line: 0, devboot: false, iox }; - let mut display = XousDisplay { - fb, - hwfb, - csr: CSR::new(control.as_mut_ptr() as *mut u32), - srfb: [0u32; FB_SIZE], - next_free_line: 0, - devboot: bool, - }; - - display.set_clock(CONFIG_CLOCK_FREQUENCY); // initialize the DMA buffer with valid mode/address lines & blank data for line in 0..FB_LINES { display.copy_line_to_dma(line) @@ -204,7 +203,11 @@ impl XousDisplay { /// any access to these registers have to be protected with a mutex of some form. In the case of /// the panic handler, the `is_panic` `AtomicBool` will suppress graphics loop operation /// in the case of a panic. - pub unsafe fn hw_regs(&self) -> (u32, u32) { (self.hwfb.as_mut_ptr() as u32, self.csr.base() as u32) } + pub unsafe fn hw_regs(&self) -> (u32, u32) { + todo!( + "Need to implement visual panic handler -- requires also a deep refactor of the panic handler itself!" + ); + } pub fn stash(&mut self) { unimplemented!("Cramium platform does not yet support suspend/resume"); @@ -231,13 +234,27 @@ impl XousDisplay { xous::yield_slice(); busy_count += 1; } - // this code is safe because u32 is representable on the system - let fb = unsafe { self.fb.as_slice_mut::() }; // check if a line is dirty; if so, copy it to the DMA buffer, then mark it as clean. for line_no in 0..FB_LINES { - if fb[line_no * FB_WIDTH_WORDS + (FB_WIDTH_WORDS - 1)] & 0xFFFF_0000 != 0x0 { + // this code is safe because u32 is representable on the system + let fb = unsafe { self.fb.as_slice::() }; + // check an immutably borrowed copy of the soft framebuffer to see if the line is dirty, + // and store the result. + let is_dirty = if fb[line_no * FB_WIDTH_WORDS + (FB_WIDTH_WORDS - 1)] & 0xFFFF_0000 != 0x0 { + true + } else { + false + }; + // dirty check is split from the line update to avoid re-borrowing the immutable borrow that was + // needed to check the dirty state. + if is_dirty { + // this borrows self to copy the line data to the DMA buffer self.copy_line_to_dma(line_no); + // this borrows self.fb to clear the dirty flag on the soft framebuffer + // this code is safe because u32 is representable on the system + let fb = unsafe { self.fb.as_slice_mut::() }; fb[line_no * FB_WIDTH_WORDS + (FB_WIDTH_WORDS - 1)] &= 0x0000_FFFF; + dirty_count += 1; } } self.update_dirty(); @@ -270,17 +287,17 @@ impl XousDisplay { /// Beneath this line are pure-HAL layer, and should not be user-visible /// Copies a display line to the DMA buffer, while setting up all the bits for /// the DMA operation. Manages the DMA line pointer as well. - fn copy_line_to_dma(&self, src_line: usize) { + fn copy_line_to_dma(&mut self, src_line: usize) { // safety: this is safe because the underlying data types (u32) are representable on the system unsafe { - let mut hwfb = self.hwfb.as_slice_u32_mut(); + let hwfb = self.spim.tx_buf_mut(); let fb = self.fb.as_slice::(); // set the mode and address // the very first line is unused, except for the mode & address info // this is done just to keep the math easy for computing strides & alignments hwfb[(self.next_free_line + 1) * FB_WIDTH_WORDS - 1] = (hwfb[(self.next_free_line + 1) * FB_WIDTH_WORDS - 1] & 0x0000_FFFFF) - | (src_line << 6) + | ((src_line as u32) << 6) | 0b001; // now copy the data hwfb[(self.next_free_line + 1) * FB_WIDTH_WORDS..(self.next_free_line + 2) * FB_WIDTH_WORDS] @@ -298,23 +315,29 @@ impl XousDisplay { } } - // NEXT UP: translate all the UDMA SPIM calls from the Pulp C source into the udma.rs file in cram-hal! - fn set_clock(&mut self, clk_mhz: u32) { - // TODO: - // - set up the UDMA block registers - } - fn update_dirty(&mut self) { - // TODO: - // - set up DMA based on next_free_line - - self.next_free_line = 0; + if self.next_free_line != 0 { + // manual toggle of CS pins is necessary in part to meet setup/hold time of the LCD + self.iox.set_gpio_pin_value(SPI_PORT, SPI_CS_PIN, iox::IoxValue::High); + // safety: this function is safe to call because: + // - `is_virtual` is `false` => data should be a physical buffer that is pre-populated with the + // transmit data this is done by `copy_line_to_dma()` + // - the `data` argument is a physical buffer slice, which is only used as a base/bounds + // argument + unsafe { + self.spim.tx_data_async_from_parts::( + FB_WIDTH_WORDS - 1, + (self.next_free_line + 1) * FB_WIDTH_WORDS, + false, + false, + ); + } + self.iox.set_gpio_pin_value(SPI_PORT, SPI_CS_PIN, iox::IoxValue::Low); + self.next_free_line = 0; + } } - fn busy(&self) -> bool { - // TODO: - // - return if DMA is in progress by monitoring the UDMA bits - } + fn busy(&self) -> bool { self.spim.is_tx_busy() } pub fn set_devboot(&mut self, ena: bool) { // one-way door (set-only)