hyperlight_common/virtq/
desc.rs1use bitflags::bitflags;
11use bytemuck::{Pod, Zeroable};
12
13use super::MemOps;
14
15bitflags! {
16 #[repr(transparent)]
21 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
22 pub struct DescFlags: u16 {
23 const NEXT = 1 << 0;
25 const WRITE = 1 << 1;
27 const INDIRECT = 1 << 2;
29 const AVAIL = 1 << 7;
31 const USED = 1 << 15;
33 }
34}
35
36impl DescFlags {
37 #[inline]
40 pub fn is_avail(self, wrap: bool) -> bool {
41 let avail = self.contains(DescFlags::AVAIL);
42 let used = self.contains(DescFlags::USED);
43 avail == wrap && used != wrap
44 }
45
46 #[inline]
49 pub fn is_used(self, wrap: bool) -> bool {
50 let avail = self.contains(DescFlags::AVAIL);
51 let used = self.contains(DescFlags::USED);
52 avail == wrap && used == wrap
53 }
54}
55
56#[repr(C)]
57#[derive(Clone, Copy, Debug, Pod, Zeroable, PartialEq, Eq, Hash)]
58pub struct Descriptor {
59 pub addr: u64,
61 pub len: u32,
64 pub id: u16,
67 pub flags: u16,
69}
70
71const _: () = assert!(core::mem::size_of::<Descriptor>() == 16);
72const _: () = assert!(Descriptor::ALIGN == 16);
73const _: () = assert!(Descriptor::ADDR_OFFSET == 0);
74const _: () = assert!(Descriptor::LEN_OFFSET == 8);
75const _: () = assert!(Descriptor::ID_OFFSET == 12);
76const _: () = assert!(Descriptor::FLAGS_OFFSET == 14);
77
78impl Descriptor {
79 pub const ALIGN: usize = 16;
81 pub const SIZE: usize = core::mem::size_of::<Self>();
82
83 pub const ADDR_OFFSET: usize = core::mem::offset_of!(Self, addr);
84 pub const LEN_OFFSET: usize = core::mem::offset_of!(Self, len);
85 pub const ID_OFFSET: usize = core::mem::offset_of!(Self, id);
86 pub const FLAGS_OFFSET: usize = core::mem::offset_of!(Self, flags);
87
88 pub fn new(addr: u64, len: u32, id: u16, flags: DescFlags) -> Self {
89 Self {
90 addr,
91 len,
92 id,
93 flags: flags.bits(),
94 }
95 }
96
97 #[inline]
99 pub fn flags(&self) -> DescFlags {
100 DescFlags::from_bits_truncate(self.flags)
101 }
102
103 #[inline]
105 pub fn is_avail(&self, wrap: bool) -> bool {
106 self.flags().is_avail(wrap)
107 }
108
109 #[inline]
111 pub fn is_used(&self, wrap: bool) -> bool {
112 self.flags().is_used(wrap)
113 }
114
115 #[inline]
117 pub fn is_writable(&self) -> bool {
118 self.flags().contains(DescFlags::WRITE)
119 }
120
121 #[inline]
123 pub fn is_next(&self) -> bool {
124 self.flags().contains(DescFlags::NEXT)
125 }
126
127 #[inline]
132 pub fn mark_avail(&mut self, wrap: bool) {
133 if wrap {
134 self.flags |= DescFlags::AVAIL.bits();
135 self.flags &= !DescFlags::USED.bits();
136 } else {
137 self.flags &= !DescFlags::AVAIL.bits();
138 self.flags |= DescFlags::USED.bits();
139 }
140 }
141
142 #[inline]
145 pub fn mark_used(&mut self, wrap: bool) {
146 if wrap {
147 self.flags |= DescFlags::USED.bits();
148 self.flags |= DescFlags::AVAIL.bits();
149 } else {
150 self.flags &= !DescFlags::USED.bits();
151 self.flags &= !DescFlags::AVAIL.bits();
152 }
153 }
154
155 pub fn write_release<M: MemOps>(&self, mem: &M, addr: u64) -> Result<(), M::Error> {
163 mem.write_val(addr + Self::ADDR_OFFSET as u64, self.addr)?;
164 mem.write_val(addr + Self::LEN_OFFSET as u64, self.len)?;
165 mem.write_val(addr + Self::ID_OFFSET as u64, self.id)?;
166 mem.store_release(addr + Self::FLAGS_OFFSET as u64, self.flags)?;
168 Ok(())
169 }
170
171 pub fn read_flags_acquire<M: MemOps>(mem: &M, addr: u64) -> Result<DescFlags, M::Error> {
174 let flags = mem.load_acquire(addr + Self::FLAGS_OFFSET as u64)?;
175 Ok(DescFlags::from_bits_truncate(flags))
176 }
177
178 pub fn read_body<M: MemOps>(mem: &M, addr: u64, flags: DescFlags) -> Result<Self, M::Error> {
181 let addr_val: u64 = mem.read_val(addr + Self::ADDR_OFFSET as u64)?;
182 let len: u32 = mem.read_val(addr + Self::LEN_OFFSET as u64)?;
183 let id: u16 = mem.read_val(addr + Self::ID_OFFSET as u64)?;
184
185 Ok(Self {
186 addr: addr_val,
187 len,
188 id,
189 flags: flags.bits(),
190 })
191 }
192}
193
194#[derive(Debug, Clone, Copy)]
196pub struct DescTable {
197 base_addr: u64,
198 len: usize,
199}
200
201impl DescTable {
202 pub const DEFAULT_LEN: usize = 256;
203
204 pub unsafe fn from_raw_parts(base_addr: u64, len: usize) -> Self {
213 debug_assert!(base_addr.is_multiple_of(Descriptor::ALIGN as u64));
214 debug_assert!(len <= u16::MAX as usize);
215
216 Self { base_addr, len }
217 }
218
219 pub fn desc_addr(&self, idx: u16) -> Option<u64> {
221 if idx >= self.len as u16 {
222 return None;
223 }
224
225 Some(self.base_addr + (idx as u64 * Descriptor::SIZE as u64))
226 }
227
228 pub fn clear<M: MemOps>(&self, mem: &M) -> Result<(), M::Error> {
230 let zeroed = Descriptor::zeroed();
231 for idx in 0..self.len {
232 let addr = self.base_addr + (idx as u64 * Descriptor::SIZE as u64);
233 zeroed.write_release(mem, addr)?;
234 }
235 Ok(())
236 }
237
238 pub fn len(&self) -> usize {
240 self.len
241 }
242
243 pub fn is_empty(&self) -> bool {
245 self.len == 0
246 }
247
248 pub fn base_addr(&self) -> u64 {
250 self.base_addr
251 }
252
253 pub const fn default_len() -> usize {
254 Self::DEFAULT_LEN
255 }
256}
257
258#[cfg(test)]
259mod tests {
260 use super::*;
261
262 #[test]
263 fn mark_avail_sets_bits_correctly_wrap_true() {
264 let mut d = Descriptor::zeroed();
265 d.flags = DescFlags::WRITE.bits() | DescFlags::NEXT.bits();
266 d.mark_avail(true);
267 let f = d.flags();
268 assert!(f.contains(DescFlags::AVAIL));
269 assert!(!f.contains(DescFlags::USED));
270 assert!(f.contains(DescFlags::WRITE));
271 assert!(f.contains(DescFlags::NEXT));
272 }
273
274 #[test]
275 fn mark_avail_sets_bits_correctly_wrap_false() {
276 let mut d = Descriptor::zeroed();
277 d.mark_avail(false);
278 let f = d.flags();
279 assert!(!f.contains(DescFlags::AVAIL));
280 assert!(f.contains(DescFlags::USED));
281 }
282
283 #[test]
284 fn mark_used_sets_both_bits_match_wrap_true() {
285 let mut d = Descriptor::zeroed();
286 d.mark_used(true);
287 let f = d.flags();
288 assert!(f.contains(DescFlags::AVAIL));
289 assert!(f.contains(DescFlags::USED));
290 }
291
292 #[test]
293 fn mark_used_sets_both_bits_match_wrap_false() {
294 let mut d = Descriptor::zeroed();
295 d.mark_used(false);
296 let f = d.flags();
297 assert!(!f.contains(DescFlags::AVAIL));
298 assert!(!f.contains(DescFlags::USED));
299 }
300
301 #[test]
302 fn is_avail_and_is_used() {
303 let mut d = Descriptor::zeroed();
304 d.mark_avail(true);
305 assert!(d.is_avail(true));
306 assert!(!d.is_used(true));
307 d.mark_used(true);
308 assert!(d.is_used(true));
309 assert!(!d.is_avail(true));
310 d.mark_avail(false);
311 assert!(d.is_avail(false));
312 assert!(!d.is_used(false));
313 d.mark_used(false);
314 assert!(d.is_used(false));
315 assert!(!d.is_avail(false));
316 }
317
318 #[test]
319 fn writable_and_next_helpers() {
320 let mut d = Descriptor::zeroed();
321 d.flags = (DescFlags::WRITE | DescFlags::NEXT).bits();
322 assert!(d.is_writable());
323 assert!(d.is_next());
324 d.flags = 0;
325 assert!(!d.is_writable());
326 assert!(!d.is_next());
327 }
328
329 #[test]
330 fn avail_then_used_wrap_flip_sequence() {
331 let mut d = Descriptor::zeroed();
332 d.mark_avail(true);
333 assert!(d.is_avail(true));
334 d.mark_used(false);
335 assert!(d.is_used(false));
336 assert!(!d.is_avail(false));
337 d.mark_avail(true);
338 assert!(d.is_avail(true));
339 }
340
341 #[test]
342 fn desc_table_get_out_of_bounds() {
343 let mut buf = vec![0u8; 4 * Descriptor::SIZE + Descriptor::ALIGN];
346 let base = buf.as_mut_ptr() as usize;
347 let aligned = (base + Descriptor::ALIGN - 1) & !(Descriptor::ALIGN - 1);
348 let table = unsafe { DescTable::from_raw_parts(aligned as u64, 4) };
349 assert!(table.desc_addr(3).is_some());
350 assert!(table.desc_addr(4).is_none());
351 }
352}