litex/
liteeth.rs

1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! LiteX LiteEth peripheral
6//!
7//! The hardware source and any documentation can be found in the [LiteEth Git
8//! repository](https://github.com/enjoy-digital/liteeth).
9
10use crate::event_manager::LiteXEventManager;
11use crate::litex_registers::{LiteXSoCRegisterConfiguration, Read, Write};
12use core::cell::Cell;
13use core::slice;
14use kernel::debug;
15use kernel::hil::ethernet::{EthernetAdapterDatapath, EthernetAdapterDatapathClient};
16use kernel::utilities::cells::{MapCell, OptionalCell, TakeCell};
17use kernel::utilities::StaticRef;
18use kernel::ErrorCode;
19
20// Both events have the same index since they are located on different event
21// manager instances
22const LITEETH_TX_EVENT: usize = 0;
23const LITEETH_RX_EVENT: usize = 0;
24
25type LiteEthRXEV<'a, R> = LiteXEventManager<
26    'a,
27    u8,
28    <R as LiteXSoCRegisterConfiguration>::ReadOnly8,
29    <R as LiteXSoCRegisterConfiguration>::ReadWrite8,
30    <R as LiteXSoCRegisterConfiguration>::ReadWrite8,
31>;
32type LiteEthTXEV<'a, R> = LiteEthRXEV<'a, R>;
33
34#[repr(C)]
35pub struct LiteEthMacRegisters<R: LiteXSoCRegisterConfiguration> {
36    /// ETHMAC_SRAM_WRITER_SLOT
37    rx_slot: R::ReadOnly8,
38    /// ETHMAC_SRAM_WRITER_LENGTH
39    rx_length: R::ReadOnly32,
40    /// ETHMAC_SRAM_WRITER_ERRORS
41    rx_errors: R::ReadOnly32,
42    /// ETHMAC_SRAM_WRITER_EV
43    rx_ev_status: R::ReadOnly8,
44    rx_ev_pending: R::ReadWrite8,
45    rx_ev_enable: R::ReadWrite8,
46
47    /// ETHMAC_SRAM_READER_START
48    tx_start: R::ReadWrite8,
49    /// ETHMAC_SRAM_READER_READY
50    tx_ready: R::ReadOnly8,
51    /// ETHMAC_SRAM_READER_LEVEL
52    tx_level: R::ReadOnly8,
53    /// ETHMAC_SRAM_READER_SLOT
54    tx_slot: R::ReadWrite8,
55    /// ETHMAC_SRAM_READER_LENGTH
56    tx_length: R::ReadWrite16,
57    /// ETHMAC_SRAM_READER_EV
58    tx_ev_status: R::ReadOnly8,
59    tx_ev_pending: R::ReadWrite8,
60    tx_ev_enable: R::ReadWrite8,
61
62    /// ETHMAC_PREAMBLE_CRC
63    preamble_crc: R::ReadWrite8,
64    /// ETHMAC_PREAMBLE_ERRORS
65    preamble_errors: R::ReadOnly8,
66    /// ETHMAC_CRC_ERRORS
67    crc_errors: R::ReadOnly32,
68}
69
70impl<R: LiteXSoCRegisterConfiguration> LiteEthMacRegisters<R> {
71    fn rx_ev(&self) -> LiteEthRXEV<'_, R> {
72        LiteEthRXEV::<R>::new(&self.rx_ev_status, &self.rx_ev_pending, &self.rx_ev_enable)
73    }
74
75    fn tx_ev(&self) -> LiteEthTXEV<'_, R> {
76        LiteEthTXEV::<R>::new(&self.tx_ev_status, &self.tx_ev_pending, &self.tx_ev_enable)
77    }
78}
79
80pub struct LiteEth<'a, const MAX_TX_SLOTS: usize, R: LiteXSoCRegisterConfiguration> {
81    mac_regs: StaticRef<LiteEthMacRegisters<R>>,
82    mac_memory_base: usize,
83    mac_memory_len: usize,
84    slot_size: usize,
85    rx_slots: usize,
86    tx_slots: usize,
87    client: OptionalCell<&'a dyn EthernetAdapterDatapathClient>,
88    tx_frame: TakeCell<'static, [u8]>,
89    tx_frame_info: MapCell<[(usize, u16); MAX_TX_SLOTS]>,
90    initialized: Cell<bool>,
91}
92
93impl<const MAX_TX_SLOTS: usize, R: LiteXSoCRegisterConfiguration> LiteEth<'_, MAX_TX_SLOTS, R> {
94    pub unsafe fn new(
95        mac_regs: StaticRef<LiteEthMacRegisters<R>>,
96        mac_memory_base: usize,
97        mac_memory_len: usize,
98        slot_size: usize,
99        rx_slots: usize,
100        tx_slots: usize,
101    ) -> Self {
102        LiteEth {
103            mac_regs,
104            mac_memory_base,
105            mac_memory_len,
106            slot_size,
107            rx_slots,
108            tx_slots,
109            client: OptionalCell::empty(),
110            tx_frame: TakeCell::empty(),
111            tx_frame_info: MapCell::new([(0, 0); MAX_TX_SLOTS]),
112            initialized: Cell::new(false),
113        }
114    }
115
116    pub fn initialize(&self) {
117        // Sanity check the memory parameters
118        //
119        // Technically the constructor is unsafe as it will (over the lifetime
120        // of this struct) "cast" the raw mac_memory pointer (and slot offsets)
121        // into pointers and access them directly. However checking it at
122        // runtime once seems like a good idea.
123        assert!(
124            (self.rx_slots + self.tx_slots) * self.slot_size <= self.mac_memory_len,
125            "LiteEth: slots would exceed assigned MAC memory area"
126        );
127
128        assert!(self.rx_slots > 0, "LiteEth: no RX slot");
129        assert!(self.tx_slots > 0, "LiteEth: no TX slot");
130
131        // Sanity check the length of the frame_info buffer, must be able to fit
132        // all `tx_slots` requested at runtime.
133        assert!(
134            MAX_TX_SLOTS >= self.tx_slots,
135            "LiteEth: MAX_TX_SLOTS ({}) must be larger or equal to tx_slots ({})",
136            MAX_TX_SLOTS,
137            self.tx_slots,
138        );
139
140        // Disable TX events (first enabled when a frame is sent)
141        self.mac_regs.tx_ev().disable_event(LITEETH_TX_EVENT);
142
143        // Clear all pending RX & TX events (there might be leftovers from the
144        // bootloader or a reboot, for which we don't want to generate an event)
145        //
146        // This is not sufficient to guarantee that all events will be cleared
147        // then. A frame could still be in reception or transmit.
148        while self.mac_regs.rx_ev().event_pending(LITEETH_RX_EVENT) {
149            self.mac_regs.rx_ev().clear_event(LITEETH_RX_EVENT);
150        }
151        while self.mac_regs.tx_ev().event_pending(LITEETH_TX_EVENT) {
152            self.mac_regs.tx_ev().clear_event(LITEETH_TX_EVENT);
153        }
154
155        self.initialized.set(true);
156    }
157
158    #[allow(clippy::mut_from_ref)]
159    unsafe fn get_slot_buffer(&self, tx: bool, slot_id: usize) -> Option<&mut [u8]> {
160        if (tx && slot_id > self.tx_slots) || (!tx && slot_id > self.rx_slots) {
161            return None;
162        }
163
164        let slots_offset = if tx {
165            self.mac_memory_base + self.slot_size * self.rx_slots
166        } else {
167            self.mac_memory_base
168        };
169
170        let slot_addr = slots_offset + slot_id * self.slot_size;
171        Some(slice::from_raw_parts_mut(
172            slot_addr as *mut u8,
173            self.slot_size,
174        ))
175    }
176
177    fn rx_interrupt(&self) {
178        // Get the frame length
179        let pkt_len = self.mac_regs.rx_length.get();
180
181        // Obtain the frame slot id
182        let slot_id: usize = self.mac_regs.rx_slot.get().into();
183
184        // Obtain the frame reception timestamp. The `rx_timestamp` register is
185        // optional and disabled by default.
186        //
187        // let timestamp = self.mac_regs.rx_timestamp.get();
188
189        // Get the slot buffer reference
190        let slot = unsafe {
191            self.get_slot_buffer(false, slot_id)
192                .expect("LiteEth: invalid RX slot id")
193        };
194
195        // Give the client read-only access to the frame data
196        self.client
197            .map(|client| client.received_frame(&slot[..(pkt_len as usize)], None));
198
199        // Since all data is copied, acknowledge the interrupt so that the slot
200        // is ready for use again
201        self.mac_regs.rx_ev().clear_event(LITEETH_RX_EVENT);
202    }
203
204    fn tx_interrupt(&self) {
205        // Store information about the frame that has been sent (from the return
206        // channel). Uncomment the below lines if hardware timestamping is
207        // enabled and frame TX timestamps are supposed to be recorded.
208        //
209        // let res_slot = self.mac_regs.tx_timestamp_slot.get();
210        // let res_timestamp = self.mac_regs.tx_timestamp.get();
211
212        // Acknowledge the event, removing the tx_res fields from the FIFO
213        self.mac_regs.tx_ev().clear_event(LITEETH_TX_EVENT);
214
215        if self.tx_frame.is_none() {
216            debug!("LiteEth: tx interrupt called without tx_frame set");
217        }
218
219        // We use only one slot, so this event is unambiguous
220        let frame = self
221            .tx_frame
222            .take()
223            .expect("LiteEth: TakeCell empty in tx callback");
224
225        // Retrieve the previously stored frame information for this slot.
226        let slot_id = 0; // currently only use one TX slot
227        let (frame_identifier, len) = self
228            .tx_frame_info
229            .map(|pkt_info| pkt_info[slot_id])
230            .unwrap();
231
232        self.client.map(move |client| {
233            client.transmit_frame_done(Ok(()), frame, len, frame_identifier, None)
234        });
235    }
236
237    pub fn service_interrupt(&self) {
238        // The interrupt could've been generated by both a frame being received
239        // or finished transmitting. Check and handle both cases.
240
241        while self.mac_regs.tx_ev().event_asserted(LITEETH_TX_EVENT) {
242            self.tx_interrupt();
243        }
244
245        // `event_asserted` checks that the event is both pending _and_ enabled
246        // (raising a CPU interrupt). This means that reception is enabled, and
247        // we must handle it:
248        while self.mac_regs.rx_ev().event_asserted(LITEETH_RX_EVENT) {
249            self.rx_interrupt();
250        }
251    }
252}
253
254impl<'a, const MAX_TX_SLOTS: usize, R: LiteXSoCRegisterConfiguration> EthernetAdapterDatapath<'a>
255    for LiteEth<'a, MAX_TX_SLOTS, R>
256{
257    fn set_client(&self, client: &'a dyn EthernetAdapterDatapathClient) {
258        self.client.set(client);
259    }
260
261    fn enable_receive(&self) {
262        // Enable RX event interrupts:
263        if !self.initialized.get() {
264            panic!("LiteEth: cannot enable_receive without prior initialization!");
265        }
266
267        self.mac_regs.rx_ev().enable_event(LITEETH_RX_EVENT);
268    }
269
270    fn disable_receive(&self) {
271        // Disable RX event interrupts:
272        self.mac_regs.rx_ev().disable_event(LITEETH_RX_EVENT);
273    }
274
275    /// Transmit an Ethernet frame over the interface
276    ///
277    /// For now this will only use a single slot on the interface and is
278    /// therefore blocking. A client must wait until a callback to `tx_done`
279    /// prior to sending a new frame.
280    fn transmit_frame(
281        &self,
282        frame: &'static mut [u8],
283        len: u16,
284        frame_identifier: usize,
285    ) -> Result<(), (ErrorCode, &'static mut [u8])> {
286        if frame.len() < (len as usize) {
287            return Err((ErrorCode::INVAL, frame));
288        }
289
290        if self.tx_frame.is_some() {
291            return Err((ErrorCode::BUSY, frame));
292        }
293
294        // For now, we always use slot 0
295        let slot_id = 0;
296
297        let slot = unsafe { self.get_slot_buffer(true, slot_id) }.expect("LiteEth: no TX slot");
298        if slot.len() < (len as usize) {
299            return Err((ErrorCode::SIZE, frame));
300        }
301
302        // Set the slot's frame information
303        self.tx_frame_info
304            .map(|pkt_info| {
305                pkt_info[slot_id] = (frame_identifier, len);
306            })
307            .unwrap();
308
309        // Copy the frame into the slot HW buffer
310        slot[..(len as usize)].copy_from_slice(&frame[..(len as usize)]);
311
312        // Put the currently transmitting frame into the designated TakeCell
313        self.tx_frame.replace(frame);
314
315        // Set the slot and frame length
316        self.mac_regs.tx_slot.set(0);
317        self.mac_regs.tx_length.set(len);
318
319        // Wait for the device to be ready to transmit
320        while self.mac_regs.tx_ready.get() == 0 {}
321
322        // Enable TX events
323        self.mac_regs.tx_ev().enable_event(LITEETH_TX_EVENT);
324
325        // Start the transmission
326        self.mac_regs.tx_start.set(1);
327
328        Ok(())
329    }
330}
litex/liteeth.rs

litex/
liteeth.rs
