storage_device/
lib.rs

1// Copyright 2021 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::buffer::{BufferFuture, BufferRef, MutableBufferRef};
6use anyhow::{bail, Error};
7use async_trait::async_trait;
8use block_protocol::WriteOptions;
9use futures::channel::oneshot::{channel, Sender};
10use std::future::Future;
11use std::mem::ManuallyDrop;
12use std::ops::{Deref, Range};
13use std::sync::{Arc, OnceLock};
14
15pub mod buffer;
16pub mod buffer_allocator;
17
18#[cfg(target_os = "fuchsia")]
19pub mod block_device;
20
21#[cfg(target_family = "unix")]
22pub mod file_backed_device;
23
24pub mod fake_device;
25
26#[async_trait]
27/// Device is an abstract representation of an underlying block device.
28pub trait Device: Send + Sync {
29    /// Allocates a transfer buffer of at least |size| bytes for doing I/O with the device.
30    /// The actual size of the buffer will be rounded up to a block-aligned size.
31    fn allocate_buffer(&self, size: usize) -> BufferFuture<'_>;
32
33    /// Returns the block size of the device. Buffers are aligned to block-aligned chunks.
34    fn block_size(&self) -> u32;
35
36    /// Returns the number of blocks of the device.
37    // TODO(jfsulliv): Should this be async and go query the underlying device?
38    fn block_count(&self) -> u64;
39
40    /// Returns the size in bytes of the device.
41    fn size(&self) -> u64 {
42        self.block_size() as u64 * self.block_count()
43    }
44
45    /// Fills |buffer| with blocks read from |offset|.
46    async fn read(&self, offset: u64, buffer: MutableBufferRef<'_>) -> Result<(), Error>;
47
48    /// Writes the contents of |buffer| to the device at |offset|.
49    async fn write(&self, offset: u64, buffer: BufferRef<'_>) -> Result<(), Error> {
50        self.write_with_opts(offset, buffer, WriteOptions::empty()).await
51    }
52
53    /// Writes the contents of |buffer| to the device at |offset|.
54    async fn write_with_opts(
55        &self,
56        offset: u64,
57        buffer: BufferRef<'_>,
58        opts: WriteOptions,
59    ) -> Result<(), Error>;
60
61    /// Trims the given device |range|.
62    async fn trim(&self, range: Range<u64>) -> Result<(), Error>;
63
64    /// Closes the block device. It is an error to continue using the device after this, but close
65    /// itself is idempotent.
66    async fn close(&self) -> Result<(), Error>;
67
68    /// Flush the device.
69    async fn flush(&self) -> Result<(), Error>;
70
71    /// Attach a barrier to the next write made to the device.
72    fn barrier(&self);
73
74    /// Reopens the device, making it usable again. (Only implemented for testing devices.)
75    fn reopen(&self, _read_only: bool) {
76        unreachable!();
77    }
78    /// Returns whether the device is read-only.
79    fn is_read_only(&self) -> bool;
80
81    /// Returns whether the device supports trim.
82    fn supports_trim(&self) -> bool;
83
84    /// Returns a snapshot of the device.
85    fn snapshot(&self) -> Result<DeviceHolder, Error> {
86        bail!("Not supported");
87    }
88
89    /// Discards random blocks since the last flush.
90    fn discard_random_since_last_flush(&self) -> Result<(), Error> {
91        bail!("Not supported");
92    }
93
94    /// Poisons a device to panic on drop. Used to find hanging references.
95    fn poison(&self) -> Result<(), Error> {
96        bail!("Not supported");
97    }
98}
99
100// Arc<dyn Device> can easily be cloned and supports concurrent access, but sometimes exclusive
101// access is required, in which case APIs should accept DeviceHolder.  It doesn't guarantee there
102// aren't some users that hold an Arc<dyn Device> somewhere, but it does mean that something that
103// accepts a DeviceHolder won't be sharing the device with something else that accepts a
104// DeviceHolder.  For example, FxFilesystem accepts a DeviceHolder which means that you cannot
105// create two FxFilesystem instances that are both sharing the same device.
106pub struct DeviceHolder {
107    device: ManuallyDrop<Arc<dyn Device>>,
108    on_drop: OnceLock<Sender<DeviceHolder>>,
109}
110
111impl DeviceHolder {
112    pub fn new(device: impl Device + 'static) -> Self {
113        DeviceHolder { device: ManuallyDrop::new(Arc::new(device)), on_drop: OnceLock::new() }
114    }
115
116    // Ensures there are no dangling references to the device. Useful for tests to ensure orderly
117    // shutdown.
118    pub fn ensure_unique(&self) {
119        assert_eq!(Arc::strong_count(&self.device), 1);
120    }
121
122    pub fn take_when_dropped(&self) -> impl Future<Output = DeviceHolder> {
123        let (sender, receiver) = channel::<DeviceHolder>();
124        self.on_drop
125            .set(sender)
126            .unwrap_or_else(|_| panic!("take_when_dropped should only be called once"));
127        async { receiver.await.unwrap() }
128    }
129}
130
131impl Drop for DeviceHolder {
132    fn drop(&mut self) {
133        if let Some(sender) = self.on_drop.take() {
134            // SAFETY: `device` is not used again.
135            let device = ManuallyDrop::new(unsafe { ManuallyDrop::take(&mut self.device) });
136            // We don't care if this fails to send.
137            let _ = sender.send(DeviceHolder { device, on_drop: OnceLock::new() });
138        } else {
139            // SAFETY: `device` is not used again.
140            unsafe { ManuallyDrop::drop(&mut self.device) }
141        }
142    }
143}
144
145impl Deref for DeviceHolder {
146    type Target = Arc<dyn Device>;
147
148    fn deref(&self) -> &Self::Target {
149        &self.device
150    }
151}
152
153#[cfg(test)]
154mod tests {
155    use super::DeviceHolder;
156    use crate::fake_device::FakeDevice;
157
158    #[fuchsia::test]
159    async fn test_take_when_dropped() {
160        let holder = DeviceHolder::new(FakeDevice::new(1, 512));
161        let fut = holder.take_when_dropped();
162        std::mem::drop(holder);
163        fut.await.ensure_unique();
164    }
165}
storage_device/lib.rs

storage_device/
lib.rs
