litex/event_manager.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 Event Manager
6//!
7//! Documentation on the different LiteX event source, which all
8//! behave differently, can be found in the LiteX repository under
9//! [`litex/soc/interconnect/csr_eventmanager.py`](https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr_eventmanager.py).
10
11use crate::litex_registers::{Read, ReadWrite, UIntLike};
12use core::marker::PhantomData;
13
14/// LiteX event manager abstraction
15///
16/// A LiteX event manager combines and manages event sources of a
17/// LiteX core / peripheral. The event manager itself is connected to
18/// an interrupt source in the CPU.
19///
20/// This is an abstraction over an instance of a LiteX EventManager,
21/// which is exposed to the operating system using three configuration
22/// status registers (LiteX CSRs), as part of the core's /
23/// peripheral's configuration status registers bank.
24pub struct LiteXEventManager<'a, T, S, P, E>
25where
26 T: UIntLike,
27 S: Read<T>,
28 P: ReadWrite<T>,
29 E: ReadWrite<T>,
30{
31 status: &'a S,
32 pending: &'a P,
33 enable: &'a E,
34 _base_type: PhantomData<T>,
35}
36
37impl<'a, T, S, P, E> LiteXEventManager<'a, T, S, P, E>
38where
39 T: UIntLike,
40 S: Read<T>,
41 P: ReadWrite<T>,
42 E: ReadWrite<T>,
43{
44 pub const fn new(status: &'a S, pending: &'a P, enable: &'a E) -> Self {
45 LiteXEventManager {
46 status,
47 pending,
48 enable,
49 _base_type: PhantomData,
50 }
51 }
52
53 /// Disable / suppress all event sources connected to the LiteX
54 /// event manager.
55 ///
56 /// This will prevent any of the event sources from asserting the
57 /// event manager's CPU interrupt.
58 pub fn disable_all(&self) {
59 self.enable.set(T::zero());
60 }
61
62 /// Enable all event sources connected to the LiteX
63 /// event manager.
64 ///
65 /// This will make any asserted (pending) event source assert the
66 /// event manager's CPU interrupt.
67 pub fn enable_all(&self) {
68 self.enable.set(T::max());
69 }
70
71 /// Disable / suppress an event source connected to the LiteX
72 /// event manager.
73 ///
74 /// This will prevent the specific event source from asserting the
75 /// event manager's CPU interrupt.
76 ///
77 /// The event is addressed by its index in the event manager's
78 /// registers (starting at 0).
79 pub fn disable_event(&self, index: usize) {
80 self.enable.set(self.enable.get() & !(T::one() << index));
81 }
82
83 /// Enable an event source connected to the LiteX event manager
84 ///
85 /// This will assert the event manager's CPU interrupt if this or
86 /// any other event source is asserted (pending).
87 ///
88 /// The event is addressed by its index in the event manager's
89 /// registers (starting at 0).
90 pub fn enable_event(&self, index: usize) {
91 self.enable.set(self.enable.get() | (T::one() << index));
92 }
93
94 /// Check whether an event is enabled.
95 ///
96 /// This checks whether an event source may assert the event
97 /// manager's CPU interrupt.
98 ///
99 /// The event is addressed by its index in the event manager's
100 /// registers (starting at 0).
101 pub fn event_enabled(&self, index: usize) -> bool {
102 self.enable.get() & (T::one() << index) != T::zero()
103 }
104
105 /// Get all enabled events.
106 ///
107 /// The enabled events are encoded as bits in the returned integer
108 /// type, starting from the least significant bit for the first
109 /// event source (index 0), where a `1` means enabled and `0`
110 /// means disabled (suppressed).
111 pub fn events_enabled(&self) -> T {
112 self.enable.get()
113 }
114
115 /// Get the input signal to an event source.
116 ///
117 /// This returns whether an event source input is currently
118 /// asserted. This is independent of whether the event is actually
119 /// enabled or pending.
120 ///
121 /// The event source is addressed by its index in the event
122 /// manager's registers (starting at 0).
123 pub fn event_source_input(&self, index: usize) -> bool {
124 self.status.get() & (T::one() << index) != T::zero()
125 }
126
127 /// Check whether any event source is pending.
128 ///
129 /// This returns whether any event source is claiming to be
130 /// pending. This is irrespective of whether an event source has a
131 /// specific input or is enabled.
132 ///
133 /// An example for an event source which can be pending
134 /// irrespective of the current input is an "EventSourceProcess",
135 /// which triggers on a falling edge of the input and stays
136 /// pending until cleared.
137 pub fn any_event_pending(&self) -> bool {
138 self.pending.get() != T::zero()
139 }
140
141 /// Check whether an event source is pending.
142 ///
143 /// This returns whether an event source is claiming to be
144 /// pending. This is irrespective of whether an event source has a
145 /// specific input or is enabled.
146 ///
147 /// An example for an event source which can be pending
148 /// irrespective of the current input is an "EventSourceProcess",
149 /// which triggers on a falling edge of the input and stays
150 /// pending until cleared.
151 ///
152 /// The event source is addressed by its index in the event
153 /// manager's registers (starting at 0).
154 pub fn event_pending(&self, index: usize) -> bool {
155 self.pending.get() & (T::one() << index) != T::zero()
156 }
157
158 /// Get all pending events.
159 ///
160 /// The pending events are encoded as bits in the returned integer
161 /// type, starting from the least significant bit for the first
162 /// event source (index 0), where a `1` means that the event
163 /// source is pending.
164 pub fn events_pending(&self) -> T {
165 self.pending.get()
166 }
167
168 /// Check whether an event source is asserting the event manager's
169 /// CPU interrupt (both enabled and pending).
170 ///
171 ///
172 /// The event source is addressed by its index in the event
173 /// manager's registers (starting at 0).
174 pub fn event_asserted(&self, index: usize) -> bool {
175 self.event_enabled(index) && self.event_pending(index)
176 }
177
178 /// Get the next asserted event, starting from 0.
179 ///
180 /// If an asserted event was found, its index is returned. Otherwise, None
181 /// is returned.
182 ///
183 /// This method works by ANDing the enabled and pending bits and using the
184 /// trailing_zeros intrinsic (of which there may be an optimized version
185 /// with special instructions). Thus this is faster than a naive, loop-based
186 /// version.
187 pub fn next_asserted(&self) -> Option<usize> {
188 let ev_bits = core::mem::size_of::<T>() * 8;
189 let enabled = self.events_enabled();
190 let pending = self.events_pending();
191 let asserted = enabled & pending;
192
193 // If there are no interrupts pending (asserted == 0), T::trailing_zeros
194 // will return the number of bits in T, in which case we need to return
195 // None.
196 let trailing_zeros = T::trailing_zeros(asserted) as usize;
197 if trailing_zeros == ev_bits {
198 None
199 } else {
200 Some(trailing_zeros)
201 }
202 }
203
204 /// Clear a pending event source.
205 ///
206 /// This operation may have side effects in the device (for
207 /// instance, acknowledge the reception of a UART data word).
208 ///
209 /// It is not guaranteed that the event source will be no longer
210 /// pending after clearing (for instance when used with FIFOs and
211 /// pending data, or with an "EventSourceLevel" which can only be
212 /// cleared by driving the input signal low).
213 pub fn clear_event(&self, index: usize) {
214 self.pending.set(T::one() << index);
215 }
216
217 /// Clear all pending event sources.
218 ///
219 /// This operation may have side effects in the device (for
220 /// instance, acknowledge the reception of a UART data word).
221 ///
222 /// It is not guaranteed that the event sources will be no longer
223 /// pending after clearing (for instance when used with FIFOs and
224 /// pending data, or with an "EventSourceLevel" which can only be
225 /// cleared by driving the input signal low).
226 pub fn clear_all(&self) {
227 self.pending.set(T::max());
228 }
229}