Skip to main content

storvsp/
test_helpers.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! StorVSP test helpers.
5//!
6//! These are used both by unit tests and by benchmarks.
7
8// Benchmarks do not use all the code here, but unit tests should.
9#![cfg_attr(not(test), expect(dead_code))]
10
11use crate::InitState;
12use crate::PacketError;
13use crate::Protocol;
14use crate::ProtocolState;
15use crate::ScsiController;
16use crate::ScsiPath;
17use crate::Worker;
18use crate::WorkerError;
19use guestmem::GuestMemory;
20use guestmem::MemoryRead;
21use guestmem::ranges::PagedRange;
22use pal_async::task::Spawn;
23use pal_async::task::Task;
24use parking_lot::RwLock;
25use scsi::ScsiOp;
26use scsi::srb::SrbStatus;
27use scsi_defs as scsi;
28use std::sync::Arc;
29use vmbus_async::queue::IncomingPacket;
30use vmbus_async::queue::OutgoingPacket;
31use vmbus_async::queue::Queue;
32use vmbus_channel::RawAsyncChannel;
33use vmbus_ring as ring;
34use vmbus_ring::FlatRingMem;
35use vmbus_ring::OutgoingPacketType;
36use vmbus_ring::PAGE_SIZE;
37use zerocopy::FromZeros;
38use zerocopy::IntoBytes;
39
40pub struct TestWorker {
41    task: Task<Result<(), WorkerError>>,
42}
43
44impl TestWorker {
45    pub(crate) async fn teardown(self) -> Result<(), WorkerError> {
46        self.task.await
47    }
48
49    /// Like `teardown`, but ignore the result. Nice for the fuzzer,
50    /// so that the `storvsp` crate doesn't need to expose `WorkerError`
51    /// as pub.
52    #[cfg(feature = "test")]
53    pub async fn teardown_ignore(self) {
54        let _ = self.task.await;
55    }
56
57    /// Like `teardown`, but panic if there's a failure. Nice for integration tests, so that the
58    /// `storvsp` crate doesn't need to expose `WorkerError` as pub.
59    #[cfg(feature = "test")]
60    pub async fn teardown_or_panic(self) {
61        match self.task.await {
62            Ok(()) => {}
63            Err(WorkerError::Queue(err)) if err.is_closed_error() => {}
64            Err(err) => {
65                panic!("Worker did not teardown gracefully: {:?}", err);
66            }
67        }
68    }
69
70    pub fn start<T: ring::RingMem + 'static + Sync>(
71        controller: ScsiController,
72        spawner: impl Spawn,
73        mem: GuestMemory,
74        channel: RawAsyncChannel<T>,
75        io_queue_depth: Option<u32>,
76    ) -> Self {
77        let task = spawner.spawn("test", async move {
78            let mut worker = Worker::new(
79                controller.state.clone(),
80                channel,
81                0,
82                mem,
83                Default::default(),
84                io_queue_depth.unwrap_or(256),
85                Arc::new(Protocol {
86                    state: RwLock::new(ProtocolState::Init(InitState::Begin)),
87                    ready: Default::default(),
88                }),
89                None,
90            )
91            .unwrap();
92            task_control::StopTask::run_unstoppable(async |stop| {
93                let check = stop.check_handle().unwrap();
94                worker.process_primary(&check).await
95            })
96            .await
97        });
98
99        Self { task }
100    }
101}
102
103pub(crate) fn parse_guest_completion_check_flags_status<T: ring::RingMem>(
104    packet: &IncomingPacket<'_, T>,
105    flags: u32,
106    status: storvsp_protocol::NtStatus,
107) -> Result<(), PacketError> {
108    match packet {
109        IncomingPacket::Completion(compl) => {
110            let mut reader = compl.reader();
111            let header: storvsp_protocol::Packet =
112                reader.read_plain().map_err(PacketError::Access)?;
113            assert_eq!(header.flags, flags, "mismatched flags");
114            assert_eq!(header.status, status, "mismatched status");
115            assert_eq!(
116                header.operation,
117                storvsp_protocol::Operation::COMPLETE_IO,
118                "mismatched operation"
119            );
120            Ok(())
121        }
122        IncomingPacket::Data(_) => Err(PacketError::InvalidPacketType),
123    }
124}
125
126pub(crate) fn parse_guest_completion<T: ring::RingMem>(
127    packet: &IncomingPacket<'_, T>,
128) -> Result<(), PacketError> {
129    parse_guest_completion_check_flags_status(packet, 0, storvsp_protocol::NtStatus::SUCCESS)
130}
131
132pub(crate) fn parse_guest_completed_io<T: ring::RingMem>(
133    packet: &IncomingPacket<'_, T>,
134    expected_srb_status: SrbStatus,
135) -> Result<(), PacketError> {
136    parse_guest_completed_io_check_tx_len(packet, expected_srb_status, None)
137}
138
139pub(crate) fn parse_guest_completed_io_check_tx_len<T: ring::RingMem>(
140    packet: &IncomingPacket<'_, T>,
141    expected_srb_status: SrbStatus,
142    expected_data_tx_length: Option<usize>,
143) -> Result<(), PacketError> {
144    match packet {
145        IncomingPacket::Completion(compl) => {
146            let mut reader = compl.reader();
147            let header: storvsp_protocol::Packet =
148                reader.read_plain().map_err(PacketError::Access)?;
149            if header.operation != storvsp_protocol::Operation::COMPLETE_IO {
150                Err(PacketError::UnrecognizedOperation(header.operation))
151            } else {
152                if expected_srb_status == SrbStatus::SUCCESS {
153                    assert_eq!(header.status, storvsp_protocol::NtStatus::SUCCESS);
154                    if let Some(expected_data_tx_length) = expected_data_tx_length {
155                        let payload: storvsp_protocol::ScsiRequest =
156                            reader.read_plain().map_err(PacketError::Access)?;
157                        assert_eq!(
158                            payload.data_transfer_length as usize,
159                            expected_data_tx_length
160                        );
161                    }
162                } else {
163                    assert_ne!(header.status, storvsp_protocol::NtStatus::SUCCESS);
164                    let payload: storvsp_protocol::ScsiRequest =
165                        reader.read_plain().map_err(PacketError::Access)?;
166                    assert_eq!(payload.srb_status.status(), expected_srb_status);
167                }
168                Ok(())
169            }
170        }
171        _ => Err(PacketError::InvalidPacketType),
172    }
173}
174
175pub(crate) fn parse_guest_enumerate_bus<T: ring::RingMem>(
176    packet: &IncomingPacket<'_, T>,
177) -> Result<(), PacketError> {
178    match packet {
179        IncomingPacket::Data(p) => {
180            let mut reader = p.reader();
181            let header: storvsp_protocol::Packet =
182                reader.read_plain().map_err(PacketError::Access)?;
183            if header.operation != storvsp_protocol::Operation::ENUMERATE_BUS {
184                Err(PacketError::UnrecognizedOperation(header.operation))
185            } else {
186                assert_eq!(header.status, storvsp_protocol::NtStatus::SUCCESS);
187                Ok(())
188            }
189        }
190        _ => Err(PacketError::InvalidPacketType),
191    }
192}
193
194pub struct TestGuest {
195    pub queue: Queue<FlatRingMem>,
196    pub transaction_id: u64,
197}
198
199impl TestGuest {
200    pub async fn send_data_packet_sync(&mut self, payload: &[&[u8]]) {
201        self.queue
202            .split()
203            .1
204            .write(OutgoingPacket {
205                packet_type: OutgoingPacketType::InBandWithCompletion,
206                transaction_id: self.transaction_id,
207                payload,
208            })
209            .await
210            .unwrap();
211
212        self.transaction_id += 1;
213    }
214
215    pub async fn send_gpa_direct_packet_sync(
216        &mut self,
217        payload: &[&[u8]],
218        gpa_start: u64,
219        byte_len: usize,
220    ) {
221        let start_page: u64 = gpa_start / PAGE_SIZE as u64;
222        let end_page: u64 = (gpa_start + (byte_len + PAGE_SIZE - 1) as u64) / PAGE_SIZE as u64;
223        let gpas: Vec<u64> = (start_page..end_page).collect();
224        let pages =
225            PagedRange::new(gpa_start as usize % PAGE_SIZE, byte_len, gpas.as_slice()).unwrap();
226        self.queue
227            .split()
228            .1
229            .write(OutgoingPacket {
230                packet_type: OutgoingPacketType::GpaDirect(&[pages]),
231                transaction_id: self.transaction_id,
232                payload,
233            })
234            .await
235            .unwrap();
236
237        self.transaction_id += 1;
238    }
239
240    // This function assumes the sector size is 512.
241    pub async fn send_write_packet(
242        &mut self,
243        path: ScsiPath,
244        buf_gpa: u64,
245        block: u32,
246        byte_len: usize,
247    ) {
248        let write_packet = storvsp_protocol::Packet {
249            operation: storvsp_protocol::Operation::EXECUTE_SRB,
250            flags: 0,
251            status: storvsp_protocol::NtStatus::SUCCESS,
252        };
253
254        let cdb = scsi::Cdb10 {
255            operation_code: ScsiOp::WRITE,
256            logical_block: block.into(),
257            transfer_blocks: ((byte_len / 512) as u16).into(),
258            ..FromZeros::new_zeroed()
259        };
260
261        let mut scsi_req = storvsp_protocol::ScsiRequest {
262            target_id: path.target,
263            path_id: path.path,
264            lun: path.lun,
265            length: storvsp_protocol::SCSI_REQUEST_LEN_V2 as u16,
266            cdb_length: size_of::<scsi::Cdb10>() as u8,
267            data_transfer_length: byte_len as u32,
268            ..FromZeros::new_zeroed()
269        };
270
271        scsi_req.payload[0..10].copy_from_slice(cdb.as_bytes());
272
273        // send the gpa packet
274        self.send_gpa_direct_packet_sync(
275            &[write_packet.as_bytes(), scsi_req.as_bytes()],
276            buf_gpa,
277            byte_len,
278        )
279        .await;
280    }
281
282    // This function assumes the sector size is 512.
283    pub async fn send_read_packet(
284        &mut self,
285        path: ScsiPath,
286        read_gpa: u64,
287        block: u32,
288        byte_len: usize,
289    ) {
290        let read_packet = storvsp_protocol::Packet {
291            operation: storvsp_protocol::Operation::EXECUTE_SRB,
292            flags: 0,
293            status: storvsp_protocol::NtStatus::SUCCESS,
294        };
295
296        let cdb = scsi::Cdb10 {
297            operation_code: ScsiOp::READ,
298            logical_block: block.into(),
299            transfer_blocks: ((byte_len / 512) as u16).into(),
300            ..FromZeros::new_zeroed()
301        };
302
303        let mut scsi_req = storvsp_protocol::ScsiRequest {
304            target_id: path.target,
305            path_id: path.path,
306            lun: path.lun,
307            length: storvsp_protocol::SCSI_REQUEST_LEN_V2 as u16,
308            cdb_length: size_of::<scsi::Cdb10>() as u8,
309            data_transfer_length: byte_len as u32,
310            data_in: 1,
311            ..FromZeros::new_zeroed()
312        };
313
314        scsi_req.payload[0..10].copy_from_slice(cdb.as_bytes());
315
316        // send the gpa packet
317        self.send_gpa_direct_packet_sync(
318            &[read_packet.as_bytes(), scsi_req.as_bytes()],
319            read_gpa,
320            byte_len,
321        )
322        .await;
323    }
324
325    pub async fn send_report_luns_packet(
326        &mut self,
327        path: ScsiPath,
328        data_buffer_gpa: u64,
329        data_buffer_len: usize,
330    ) {
331        let packet = storvsp_protocol::Packet {
332            operation: storvsp_protocol::Operation::EXECUTE_SRB,
333            flags: 0,
334            status: storvsp_protocol::NtStatus::SUCCESS,
335        };
336
337        let cdb = scsi::Cdb10 {
338            operation_code: ScsiOp::REPORT_LUNS,
339            ..FromZeros::new_zeroed()
340        };
341
342        let mut scsi_req = storvsp_protocol::ScsiRequest {
343            target_id: path.target,
344            path_id: path.path,
345            lun: path.lun,
346            length: storvsp_protocol::SCSI_REQUEST_LEN_V2 as u16,
347            cdb_length: size_of::<scsi::Cdb10>() as u8,
348            data_transfer_length: data_buffer_len as u32,
349            data_in: 1,
350            ..FromZeros::new_zeroed()
351        };
352
353        scsi_req.payload[0..10].copy_from_slice(cdb.as_bytes());
354
355        self.send_gpa_direct_packet_sync(
356            &[packet.as_bytes(), scsi_req.as_bytes()],
357            data_buffer_gpa,
358            data_buffer_len,
359        )
360        .await;
361    }
362
363    pub(crate) async fn verify_completion<F>(&mut self, f: F)
364    where
365        F: Clone + FnOnce(&IncomingPacket<'_, FlatRingMem>) -> Result<(), PacketError>,
366    {
367        let (mut reader, _) = self.queue.split();
368        let packet = reader.read().await.unwrap();
369        f(&packet).unwrap();
370    }
371
372    // Send protocol negotiation packets for a test guest.
373    pub async fn perform_protocol_negotiation(&mut self) {
374        let negotiate_packet = storvsp_protocol::Packet {
375            operation: storvsp_protocol::Operation::BEGIN_INITIALIZATION,
376            flags: 0,
377            status: storvsp_protocol::NtStatus::SUCCESS,
378        };
379        self.send_data_packet_sync(&[negotiate_packet.as_bytes()])
380            .await;
381        self.verify_completion(parse_guest_completion).await;
382
383        let version_packet = storvsp_protocol::Packet {
384            operation: storvsp_protocol::Operation::QUERY_PROTOCOL_VERSION,
385            flags: 0,
386            status: storvsp_protocol::NtStatus::SUCCESS,
387        };
388        let version = storvsp_protocol::ProtocolVersion {
389            major_minor: storvsp_protocol::VERSION_BLUE,
390            reserved: 0,
391        };
392        self.send_data_packet_sync(&[version_packet.as_bytes(), version.as_bytes()])
393            .await;
394        self.verify_completion(parse_guest_completion).await;
395
396        let properties_packet = storvsp_protocol::Packet {
397            operation: storvsp_protocol::Operation::QUERY_PROPERTIES,
398            flags: 0,
399            status: storvsp_protocol::NtStatus::SUCCESS,
400        };
401        self.send_data_packet_sync(&[properties_packet.as_bytes()])
402            .await;
403        self.verify_completion(parse_guest_completion).await;
404
405        let negotiate_packet = storvsp_protocol::Packet {
406            operation: storvsp_protocol::Operation::END_INITIALIZATION,
407            flags: 0,
408            status: storvsp_protocol::NtStatus::SUCCESS,
409        };
410        self.send_data_packet_sync(&[negotiate_packet.as_bytes()])
411            .await;
412        self.verify_completion(parse_guest_completion).await;
413    }
414
415    pub(crate) async fn verify_graceful_close(self, worker: TestWorker) {
416        drop(self);
417        match worker.task.await {
418            Err(WorkerError::Queue(err)) if err.is_closed_error() => (),
419            _ => panic!("Worker thread did not complete gracefully!"),
420        }
421    }
422}