opentitanlib/console/
spi.rs

1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5use anyhow::Result;
6use std::cell::{Cell, RefCell};
7use std::collections::VecDeque;
8use std::rc::Rc;
9use std::time::Duration;
10
11use crate::io::console::ConsoleDevice;
12use crate::io::gpio::GpioPin;
13use crate::io::spi::Target;
14use crate::spiflash::flash::SpiFlash;
15
16pub struct SpiConsoleDevice<'a> {
17    spi: &'a dyn Target,
18    flash: SpiFlash,
19    console_next_frame_number: Cell<u32>,
20    rx_buf: RefCell<VecDeque<u8>>,
21    next_read_address: Cell<u32>,
22    device_tx_ready_pin: Option<&'a Rc<dyn GpioPin>>,
23}
24
25impl<'a> SpiConsoleDevice<'a> {
26    const SPI_FRAME_HEADER_SIZE: usize = 12;
27    const SPI_FLASH_READ_BUFFER_SIZE: u32 = 2048;
28    const SPI_MAX_DATA_LENGTH: usize = 2036;
29    const SPI_FRAME_MAGIC_NUMBER: u32 = 0xa5a5beef;
30    const SPI_FLASH_PAYLOAD_BUFFER_SIZE: usize = 256;
31    const SPI_TX_LAST_CHUNK_MAGIC_ADDRESS: u32 = 0x100;
32    const SPI_BOOT_MAGIC_PATTERN: u32 = 0xcafeb002;
33
34    pub fn new(
35        spi: &'a dyn Target,
36        device_tx_ready_pin: Option<&'a Rc<dyn GpioPin>>,
37    ) -> Result<Self> {
38        let flash = SpiFlash {
39            ..Default::default()
40        };
41        Ok(Self {
42            spi,
43            flash,
44            rx_buf: RefCell::new(VecDeque::new()),
45            console_next_frame_number: Cell::new(0),
46            next_read_address: Cell::new(0),
47            device_tx_ready_pin,
48        })
49    }
50
51    fn check_device_boot_up(&self, buf: &[u8]) -> Result<usize> {
52        for i in (0..buf.len()).step_by(4) {
53            let pattern: u32 = u32::from_le_bytes(buf[i..i + 4].try_into().unwrap());
54            if pattern != SpiConsoleDevice::SPI_BOOT_MAGIC_PATTERN {
55                return Ok(0);
56            }
57        }
58        // Set busy bit and wait for the device to clear the boot magic.
59        self.flash.program(self.spi, 0, buf)?;
60        self.console_next_frame_number.set(0);
61        self.next_read_address.set(0);
62        Ok(0)
63    }
64
65    fn read_from_spi(&self) -> Result<usize> {
66        // Read the SPI console frame header.
67        let read_address = self.next_read_address.get();
68        let mut header = vec![0u8; SpiConsoleDevice::SPI_FRAME_HEADER_SIZE];
69        self.read_data(read_address, &mut header)?;
70
71        let magic_number: u32 = u32::from_le_bytes(header[0..4].try_into().unwrap());
72        let frame_number: u32 = u32::from_le_bytes(header[4..8].try_into().unwrap());
73        let data_len_bytes: usize = u32::from_le_bytes(header[8..12].try_into().unwrap()) as usize;
74        if magic_number != SpiConsoleDevice::SPI_FRAME_MAGIC_NUMBER
75            || frame_number != self.console_next_frame_number.get()
76            || data_len_bytes > SpiConsoleDevice::SPI_MAX_DATA_LENGTH
77        {
78            if self.get_tx_ready_pin()?.is_none() {
79                self.check_device_boot_up(&header)?;
80            }
81            // This frame is junk, so we do not read the data
82            return Ok(0);
83        }
84        self.console_next_frame_number.set(frame_number + 1);
85
86        // Read the SPI console frame data.
87        let data_len_bytes_w_pad = (data_len_bytes + 3) & !3;
88        let mut data = vec![0u8; data_len_bytes_w_pad];
89        let data_address: u32 = (read_address
90            + u32::try_from(SpiConsoleDevice::SPI_FRAME_HEADER_SIZE).unwrap())
91            % SpiConsoleDevice::SPI_FLASH_READ_BUFFER_SIZE;
92        self.read_data(data_address, &mut data)?;
93
94        if self.get_tx_ready_pin()?.is_some() {
95            // When using the TX-indicator pin feature, we always write each SPI frame at the
96            // beginning of the flash buffer, and wait for the host to ready it out before writing
97            // another frame.
98            self.next_read_address.set(0);
99        } else {
100            let next_read_address: u32 = (read_address
101                + u32::try_from(SpiConsoleDevice::SPI_FRAME_HEADER_SIZE + data_len_bytes_w_pad)
102                    .unwrap())
103                % SpiConsoleDevice::SPI_FLASH_READ_BUFFER_SIZE;
104            self.next_read_address.set(next_read_address);
105        }
106
107        // Copy data to the internal data queue.
108        self.rx_buf.borrow_mut().extend(&data[..data_len_bytes]);
109        Ok(data_len_bytes)
110    }
111
112    fn read_data(&self, address: u32, buf: &mut [u8]) -> Result<&Self> {
113        let buf_len: usize = buf.len();
114        let space_to_end_of_buffer: usize =
115            usize::try_from(SpiConsoleDevice::SPI_FLASH_READ_BUFFER_SIZE - address).unwrap();
116        let first_part_size: usize = if buf_len > space_to_end_of_buffer {
117            space_to_end_of_buffer
118        } else {
119            buf_len
120        };
121        self.flash
122            .read(self.spi, address, &mut buf[0..first_part_size])?;
123        // Handle wrap-around
124        if first_part_size < buf_len {
125            self.flash
126                .read(self.spi, 0, &mut buf[first_part_size..buf_len])?;
127        }
128        Ok(self)
129    }
130}
131
132impl<'a> ConsoleDevice for SpiConsoleDevice<'a> {
133    fn console_poll_read(
134        &self,
135        cx: &mut std::task::Context<'_>,
136        buf: &mut [u8],
137    ) -> std::task::Poll<Result<usize>> {
138        // Have a non-zero polling interval to avoid busy polling.
139        // Each read would require some USB transaction, so using USB time slice (1ms) as the
140        // polling interval is deemed as a good value.
141        const POLL_INTERVAL: Duration = Duration::from_millis(1);
142
143        if self.rx_buf.borrow().is_empty() {
144            if let Some(ready_pin) = self.get_tx_ready_pin()? {
145                // If we are gated by the TX-ready pin, only perform the SPI console read if
146                // the ready pin is high.
147                if !ready_pin.read()? {
148                    return crate::util::runtime::poll_later(cx, POLL_INTERVAL);
149                }
150            }
151
152            if self.read_from_spi()? == 0 {
153                return crate::util::runtime::poll_later(cx, POLL_INTERVAL);
154            }
155        }
156
157        // Copy from the internal data queue to the output buffer.
158        let mut i: usize = 0;
159        while !self.rx_buf.borrow().is_empty() && i < buf.len() {
160            buf[i] = self.rx_buf.borrow_mut().pop_front().unwrap();
161            i += 1;
162        }
163
164        std::task::Poll::Ready(Ok(i))
165    }
166
167    fn console_write(&self, buf: &[u8]) -> Result<()> {
168        let buf_len: usize = buf.len();
169        let mut written_data_len: usize = 0;
170        while written_data_len < buf_len {
171            let mut write_address = SpiConsoleDevice::SPI_TX_LAST_CHUNK_MAGIC_ADDRESS;
172            let mut data_len: usize = buf_len - written_data_len;
173
174            if data_len > SpiConsoleDevice::SPI_FLASH_PAYLOAD_BUFFER_SIZE {
175                data_len = SpiConsoleDevice::SPI_FLASH_PAYLOAD_BUFFER_SIZE;
176                write_address = 0;
177            }
178
179            self.flash.program(
180                self.spi,
181                write_address,
182                &buf[written_data_len..written_data_len + data_len],
183            )?;
184            written_data_len += data_len;
185        }
186
187        Ok(())
188    }
189
190    fn get_tx_ready_pin(&self) -> Result<Option<&'a Rc<dyn GpioPin>>> {
191        Ok(self.device_tx_ready_pin)
192    }
193}
opentitanlib/console/spi.rs

opentitanlib/console/
spi.rs
