storage_device/
buffer.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

use crate::buffer_allocator::BufferAllocator;
use std::ops::{Bound, Range, RangeBounds};
use std::slice::SliceIndex;

pub use crate::buffer_allocator::BufferFuture;

pub(super) fn round_down<T>(value: T, granularity: T) -> T
where
    T: num::Num + Copy,
{
    value - value % granularity
}

pub(super) fn round_up<T>(value: T, granularity: T) -> T
where
    T: num::Num + Copy,
{
    round_down(value + granularity - T::one(), granularity)
}

// Returns a range within a range.
// For example, subrange(100..200, 20..30) = 120..130.
fn subrange<R: RangeBounds<usize>>(source: &Range<usize>, bounds: &R) -> Range<usize> {
    let subrange = (match bounds.start_bound() {
        Bound::Included(&s) => source.start + s,
        Bound::Excluded(&s) => source.start + s + 1,
        Bound::Unbounded => source.start,
    })..(match bounds.end_bound() {
        Bound::Included(&e) => source.start + e + 1,
        Bound::Excluded(&e) => source.start + e,
        Bound::Unbounded => source.end,
    });
    assert!(subrange.end <= source.end);
    subrange
}

fn split_range(range: &Range<usize>, mid: usize) -> (Range<usize>, Range<usize>) {
    let l = range.end - range.start;
    let base = range.start;
    (base..base + mid, base + mid..base + l)
}

// TODO(jfsulliv): Eventually we will want zero-copy buffers which are provided by filesystem
// clients (e.g. via zx::stream) and which we either splice pages into or out of from a transfer
// buffer, or which we directly connect to the block device, or which we read and write to in some
// different way (involving changes to the block interface).

/// Buffer is a read-write buffer that can be used for I/O with the block device. They are created
/// by a BufferAllocator, and automatically deallocate themselves when they go out of scope.
///
/// Most usage will be on the unowned BufferRef and MutableBufferRef types, since these types are
/// used for Device::read and Device::write.
///
/// Buffers are always block-aligned (both in offset and length), but unaligned slices can be made
/// with the reference types. That said, the Device trait requires aligned BufferRef and
/// MutableBufferRef objects, so alignment must be restored by the time a device read/write is
/// requested.
///
/// For example, when writing an unaligned amount of data to the device, generally two Buffers
/// would need to be involved; the input Buffer could be used to write everything up to the last
/// block, and a second single-block alignment Buffer would be used to read-modify-update the last
/// block.
#[derive(Debug)]
pub struct Buffer<'a>(MutableBufferRef<'a>);

// Alias for the traits which need to be satisfied for |subslice| and friends.
// This trait is automatically satisfied for most typical uses (a..b, a.., ..b, ..).
pub trait SliceRange: Clone + RangeBounds<usize> + SliceIndex<[u8], Output = [u8]> {}
impl<T> SliceRange for T where T: Clone + RangeBounds<usize> + SliceIndex<[u8], Output = [u8]> {}

impl<'a> Buffer<'a> {
    pub(super) fn new(
        slice: &'a mut [u8],
        range: Range<usize>,
        allocator: &'a BufferAllocator,
    ) -> Self {
        Self(MutableBufferRef { slice, range, allocator })
    }

    /// Takes a read-only reference to this buffer.
    pub fn as_ref(&self) -> BufferRef<'_> {
        self.subslice(..)
    }

    /// Takes a read-only reference to this buffer over |range| (which must be within the size of
    /// the buffer).
    pub fn subslice<R: SliceRange>(&self, range: R) -> BufferRef<'_> {
        self.0.subslice(range)
    }

    /// Takes a read-write reference to this buffer.
    pub fn as_mut(&mut self) -> MutableBufferRef<'_> {
        self.subslice_mut(..)
    }

    /// Takes a read-write reference to this buffer over |range| (which must be within the size of
    /// the buffer).
    pub fn subslice_mut<R: SliceRange>(&mut self, range: R) -> MutableBufferRef<'_> {
        self.0.reborrow().subslice_mut(range)
    }

    /// Returns the buffer's capacity.
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Returns a slice of the buffer's contents.
    pub fn as_slice(&self) -> &[u8] {
        self.0.as_slice()
    }

    /// Returns a mutable slice of the buffer's contents.
    pub fn as_mut_slice(&mut self) -> &mut [u8] {
        self.0.as_mut_slice()
    }

    /// Returns the range in the underlying BufferSource that this buffer covers.
    pub fn range(&self) -> Range<usize> {
        self.0.range()
    }

    /// Returns a reference to the allocator.
    pub fn allocator(&self) -> &BufferAllocator {
        self.0.allocator
    }
}

impl<'a> Drop for Buffer<'a> {
    fn drop(&mut self) {
        self.0.allocator.free_buffer(self.range());
    }
}

/// BufferRef is an unowned, read-only view over a Buffer.
#[derive(Clone, Copy, Debug)]
pub struct BufferRef<'a> {
    slice: &'a [u8],
    start: usize, // Not range so that we get Copy.
    end: usize,
    allocator: &'a BufferAllocator,
}

impl<'a> BufferRef<'a> {
    /// Returns the buffer's capacity.
    pub fn len(&self) -> usize {
        self.end - self.start
    }

    pub fn is_empty(&self) -> bool {
        self.end == self.start
    }

    /// Returns a slice of the buffer's contents.
    pub fn as_slice(&self) -> &[u8] {
        self.slice
    }

    /// Slices and consumes this reference. See Buffer::subslice.
    pub fn subslice<R: SliceRange>(&self, range: R) -> BufferRef<'_> {
        let slice = &self.slice[range.clone()];
        let range = subrange(&self.range(), &range);
        BufferRef { slice, start: range.start, end: range.end, allocator: self.allocator }
    }

    /// Splits at |mid| (included in the right child), yielding two BufferRefs.
    pub fn split_at(&self, mid: usize) -> (BufferRef<'_>, BufferRef<'_>) {
        let slices = self.slice.split_at(mid);
        let ranges = split_range(&self.range(), mid);
        (
            BufferRef {
                slice: slices.0,
                start: ranges.0.start,
                end: ranges.0.end,
                allocator: self.allocator,
            },
            BufferRef {
                slice: slices.1,
                start: ranges.1.start,
                end: ranges.1.end,
                allocator: self.allocator,
            },
        )
    }

    /// Returns the range in the underlying BufferSource that this BufferRef covers.
    /// TODO(jfsulliv): Currently unused in host code. Remove when there is a real Device impl.
    #[allow(dead_code)]
    pub fn range(&self) -> Range<usize> {
        self.start..self.end
    }
}

/// MutableBufferRef is an unowned, read-write view of a Buffer.
#[derive(Debug)]
pub struct MutableBufferRef<'a> {
    slice: &'a mut [u8],
    range: Range<usize>,
    allocator: &'a BufferAllocator,
}

impl<'a> MutableBufferRef<'a> {
    /// Returns the buffer's capacity.
    pub fn len(&self) -> usize {
        self.range.end - self.range.start
    }

    pub fn is_empty(&self) -> bool {
        self.range.end == self.range.start
    }

    pub fn as_ref(&self) -> BufferRef<'_> {
        self.subslice(..)
    }

    pub fn into_ref(self) -> BufferRef<'a> {
        BufferRef {
            slice: self.slice,
            start: self.range.start,
            end: self.range.end,
            allocator: self.allocator,
        }
    }

    /// Returns a slice of the buffer's contents.
    pub fn as_slice(&self) -> &[u8] {
        self.slice
    }

    /// Returns a mutable slice of the buffer's contents.
    pub fn as_mut_slice(&mut self) -> &mut [u8] {
        self.slice
    }

    /// Reborrows this reference with a lesser lifetime. This mirrors the usual borrowing semantics
    /// (i.e. the borrow ends when the new reference goes out of scope), and exists so that a
    /// MutableBufferRef can be subsliced without consuming it.
    ///
    /// For example:
    ///    let mut buf: MutableBufferRef<'_> = ...;
    ///    {
    ///        let sub = buf.reborrow().subslice_mut(a..b);
    ///    }
    pub fn reborrow(&mut self) -> MutableBufferRef<'_> {
        MutableBufferRef { slice: self.slice, range: self.range.clone(), allocator: self.allocator }
    }

    /// Slices this reference. See Buffer::subslice.
    pub fn subslice<R: SliceRange>(&self, range: R) -> BufferRef<'_> {
        let slice = &self.slice[range.clone()];
        let range = subrange(&self.range, &range);
        BufferRef { slice, start: range.start, end: range.end, allocator: self.allocator }
    }

    /// Slices and consumes this reference. See Buffer::subslice_mut.
    pub fn subslice_mut<R: SliceRange>(mut self, range: R) -> MutableBufferRef<'a> {
        self.slice = &mut self.slice[range.clone()];
        self.range = subrange(&self.range, &range);
        self
    }

    /// Splits at |mid| (included in the right child), yielding two BufferRefs.
    pub fn split_at(&self, mid: usize) -> (BufferRef<'_>, BufferRef<'_>) {
        let slices = self.slice.split_at(mid);
        let ranges = split_range(&self.range, mid);
        (
            BufferRef {
                slice: slices.0,
                start: ranges.0.start,
                end: ranges.0.end,
                allocator: self.allocator,
            },
            BufferRef {
                slice: slices.1,
                start: ranges.1.start,
                end: ranges.1.end,
                allocator: self.allocator,
            },
        )
    }

    /// Consumes the reference and splits it at |mid| (included in the right child), yielding two
    /// MutableBufferRefs.
    pub fn split_at_mut(self, mid: usize) -> (MutableBufferRef<'a>, MutableBufferRef<'a>) {
        let slices = self.slice.split_at_mut(mid);
        let ranges = split_range(&self.range, mid);
        (
            MutableBufferRef { slice: slices.0, range: ranges.0, allocator: self.allocator },
            MutableBufferRef { slice: slices.1, range: ranges.1, allocator: self.allocator },
        )
    }

    /// Returns the range in the underlying BufferSource that this MutableBufferRef covers.
    /// TODO(jfsulliv): Currently unused in host code. Remove when there is a real Device impl.
    #[allow(dead_code)]
    pub fn range(&self) -> Range<usize> {
        self.range.clone()
    }
}