1 // SPDX-License-Identifier: GPL-2.0
2
3 //! Generic disk abstraction.
4 //!
5 //! C header: [`include/linux/blkdev.h`](srctree/include/linux/blkdev.h)
6 //! C header: [`include/linux/blk_mq.h`](srctree/include/linux/blk_mq.h)
7
8 use crate::block::mq::{raw_writer::RawWriter, Operations, TagSet};
9 use crate::{bindings, error::from_err_ptr, error::Result, sync::Arc};
10 use crate::{error, static_lock_class};
11 use core::fmt::{self, Write};
12
13 /// A builder for [`GenDisk`].
14 ///
15 /// Use this struct to configure and add new [`GenDisk`] to the VFS.
16 pub struct GenDiskBuilder {
17 rotational: bool,
18 logical_block_size: u32,
19 physical_block_size: u32,
20 capacity_sectors: u64,
21 }
22
23 impl Default for GenDiskBuilder {
24 fn default() -> Self {
25 Self {
26 rotational: false,
27 logical_block_size: bindings::PAGE_SIZE as u32,
28 physical_block_size: bindings::PAGE_SIZE as u32,
29 capacity_sectors: 0,
30 }
31 }
32 }
33
34 impl GenDiskBuilder {
35 /// Create a new instance.
36 pub fn new() -> Self {
37 Self::default()
38 }
39
40 /// Set the rotational media attribute for the device to be built.
41 pub fn rotational(mut self, rotational: bool) -> Self {
42 self.rotational = rotational;
43 self
44 }
45
46 /// Validate block size by verifying that it is between 512 and `PAGE_SIZE`,
47 /// and that it is a power of two.
48 fn validate_block_size(size: u32) -> Result<()> {
49 if !(512..=bindings::PAGE_SIZE as u32).contains(&size) || !size.is_power_of_two() {
50 Err(error::code::EINVAL)
51 } else {
52 Ok(())
53 }
54 }
55
56 /// Set the logical block size of the device to be built.
57 ///
58 /// This method will check that block size is a power of two and between 512
59 /// and 4096. If not, an error is returned and the block size is not set.
60 ///
61 /// This is the smallest unit the storage device can address. It is
62 /// typically 4096 bytes.
63 pub fn logical_block_size(mut self, block_size: u32) -> Result<Self> {
64 Self::validate_block_size(block_size)?;
65 self.logical_block_size = block_size;
66 Ok(self)
67 }
68
69 /// Set the physical block size of the device to be built.
70 ///
71 /// This method will check that block size is a power of two and between 512
72 /// and 4096. If not, an error is returned and the block size is not set.
73 ///
74 /// This is the smallest unit a physical storage device can write
75 /// atomically. It is usually the same as the logical block size but may be
76 /// bigger. One example is SATA drives with 4096 byte physical block size
77 /// that expose a 512 byte logical block size to the operating system.
78 pub fn physical_block_size(mut self, block_size: u32) -> Result<Self> {
79 Self::validate_block_size(block_size)?;
80 self.physical_block_size = block_size;
81 Ok(self)
82 }
83
84 /// Set the capacity of the device to be built, in sectors (512 bytes).
85 pub fn capacity_sectors(mut self, capacity: u64) -> Self {
86 self.capacity_sectors = capacity;
87 self
88 }
89
90 /// Build a new `GenDisk` and add it to the VFS.
91 pub fn build<T: Operations>(
92 self,
93 name: fmt::Arguments<'_>,
94 tagset: Arc<TagSet<T>>,
95 ) -> Result<GenDisk<T>> {
96 // SAFETY: `bindings::queue_limits` contain only fields that are valid when zeroed.
97 let mut lim: bindings::queue_limits = unsafe { core::mem::zeroed() };
98
99 lim.logical_block_size = self.logical_block_size;
100 lim.physical_block_size = self.physical_block_size;
101 if self.rotational {
102 lim.features = bindings::BLK_FEAT_ROTATIONAL;
103 }
104
105 // SAFETY: `tagset.raw_tag_set()` points to a valid and initialized tag set
106 let gendisk = from_err_ptr(unsafe {
107 bindings::__blk_mq_alloc_disk(
108 tagset.raw_tag_set(),
109 &mut lim,
110 core::ptr::null_mut(),
111 static_lock_class!().as_ptr(),
112 )
113 })?;
114
115 const TABLE: bindings::block_device_operations = bindings::block_device_operations {
116 submit_bio: None,
117 open: None,
118 release: None,
119 ioctl: None,
120 compat_ioctl: None,
121 check_events: None,
122 unlock_native_capacity: None,
123 getgeo: None,
124 set_read_only: None,
125 swap_slot_free_notify: None,
126 report_zones: None,
127 devnode: None,
128 alternative_gpt_sector: None,
129 get_unique_id: None,
130 // TODO: Set to THIS_MODULE. Waiting for const_refs_to_static feature to
131 // be merged (unstable in rustc 1.78 which is staged for linux 6.10)
132 // https://github.com/rust-lang/rust/issues/119618
133 owner: core::ptr::null_mut(),
134 pr_ops: core::ptr::null_mut(),
135 free_disk: None,
136 poll_bio: None,
137 };
138
139 // SAFETY: `gendisk` is a valid pointer as we initialized it above
140 unsafe { (*gendisk).fops = &TABLE };
141
142 let mut raw_writer = RawWriter::from_array(
143 // SAFETY: `gendisk` points to a valid and initialized instance. We
144 // have exclusive access, since the disk is not added to the VFS
145 // yet.
146 unsafe { &mut (*gendisk).disk_name },
147 )?;
148 raw_writer.write_fmt(name)?;
149 raw_writer.write_char('\0')?;
150
151 // SAFETY: `gendisk` points to a valid and initialized instance of
152 // `struct gendisk`. `set_capacity` takes a lock to synchronize this
153 // operation, so we will not race.
154 unsafe { bindings::set_capacity(gendisk, self.capacity_sectors) };
155
156 crate::error::to_result(
157 // SAFETY: `gendisk` points to a valid and initialized instance of
158 // `struct gendisk`.
159 unsafe {
160 bindings::device_add_disk(core::ptr::null_mut(), gendisk, core::ptr::null_mut())
161 },
162 )?;
163
164 // INVARIANT: `gendisk` was initialized above.
165 // INVARIANT: `gendisk` was added to the VFS via `device_add_disk` above.
166 Ok(GenDisk {
167 _tagset: tagset,
168 gendisk,
169 })
170 }
171 }
172
173 /// A generic block device.
174 ///
175 /// # Invariants
176 ///
177 /// - `gendisk` must always point to an initialized and valid `struct gendisk`.
178 /// - `gendisk` was added to the VFS through a call to
179 /// `bindings::device_add_disk`.
180 pub struct GenDisk<T: Operations> {
181 _tagset: Arc<TagSet<T>>,
182 gendisk: *mut bindings::gendisk,
183 }
184
185 // SAFETY: `GenDisk` is an owned pointer to a `struct gendisk` and an `Arc` to a
186 // `TagSet` It is safe to send this to other threads as long as T is Send.
187 unsafe impl<T: Operations + Send> Send for GenDisk<T> {}
188
189 impl<T: Operations> Drop for GenDisk<T> {
190 fn drop(&mut self) {
191 // SAFETY: By type invariant, `self.gendisk` points to a valid and
192 // initialized instance of `struct gendisk`, and it was previously added
193 // to the VFS.
194 unsafe { bindings::del_gendisk(self.gendisk) };
195 }
196 }
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.