Skip to content

Commit 31ed902

Browse files
raccognicholasbishop
raccog
authored and
nicholasbishop
committed
Add some documentation for media protocols
Also revised some existing documentation to match the current style of how most errors are documented.
1 parent 93699b8 commit 31ed902

File tree

5 files changed

+108
-56
lines changed

5 files changed

+108
-56
lines changed

‎uefi/src/proto/media/file/dir.rs

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,8 @@ impl Directory {
3838
/// * `buffer` The target buffer of the read operation
3939
///
4040
/// # Errors
41-
/// * `uefi::Status::NO_MEDIA` The device has no media
42-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error, the file was deleted,
43-
/// or the end of the file was reached before the `read()`.
44-
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
45-
/// * `uefi::Status::BUFFER_TOO_SMALL` The buffer is too small to hold a directory entry,
46-
/// the required buffer size is provided into the error.
41+
///
42+
/// All errors come from calls to [`RegularFile::read`].
4743
pub fn read_entry<'buf>(
4844
&mut self,
4945
buffer: &'buf mut [u8],
@@ -120,6 +116,10 @@ impl Directory {
120116
}
121117

122118
/// Start over the process of enumerating directory entries
119+
///
120+
/// # Errors
121+
///
122+
/// All errors come from calls to [`RegularFile::set_position`].
123123
pub fn reset_entry_readout(&mut self) -> Result {
124124
self.0.set_position(0)
125125
}

‎uefi/src/proto/media/file/mod.rs

Lines changed: 53 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -41,16 +41,27 @@ pub trait File: Sized {
4141
/// * `attributes` Only valid when `FILE_MODE_CREATE` is used as a mode
4242
///
4343
/// # Errors
44-
/// * `uefi::Status::INVALID_PARAMETER` The filename exceeds the maximum length of 255 chars
45-
/// * `uefi::Status::NOT_FOUND` Could not find file
46-
/// * `uefi::Status::NO_MEDIA` The device has no media
47-
/// * `uefi::Status::MEDIA_CHANGED` The device has a different medium in it
48-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
49-
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
50-
/// * `uefi::Status::WRITE_PROTECTED` Write/Create attempted on readonly file
51-
/// * `uefi::Status::ACCESS_DENIED` The service denied access to the file
52-
/// * `uefi::Status::OUT_OF_RESOURCES` Not enough resources to open file
53-
/// * `uefi::Status::VOLUME_FULL` The volume is full
44+
///
45+
/// See section `EFI_FILE_PROTOCOL.Open()` in the UEFI Specification for more details.
46+
///
47+
/// ## Note
48+
///
49+
/// Although [`INVALID_PARAMETER`] is not defined as an error in the UEFI Specification,
50+
/// it can be returned if the opened filename exceeds the maximum length of 255 UCS-2
51+
/// characters (not including the null terminator).
52+
///
53+
/// [`INVALID_PARAMETER`]: uefi::Status::INVALID_PARAMETER
54+
///
55+
/// * [`uefi::Status::INVALID_PARAMETER`]
56+
/// * [`uefi::Status::NOT_FOUND`]
57+
/// * [`uefi::Status::NO_MEDIA`]
58+
/// * [`uefi::Status::MEDIA_CHANGED`]
59+
/// * [`uefi::Status::DEVICE_ERROR`]
60+
/// * [`uefi::Status::VOLUME_CORRUPTED`]
61+
/// * [`uefi::Status::WRITE_PROTECTED`]
62+
/// * [`uefi::Status::ACCESS_DENIED`]
63+
/// * [`uefi::Status::OUT_OF_RESOURCES`]
64+
/// * [`uefi::Status::VOLUME_FULL`]
5465
fn open(
5566
&mut self,
5667
filename: &CStr16,
@@ -77,7 +88,10 @@ pub trait File: Sized {
7788
/// Closes and deletes this file
7889
///
7990
/// # Warnings
80-
/// * `uefi::Status::WARN_DELETE_FAILURE` The file was closed, but deletion failed
91+
///
92+
/// See section `EFI_FILE_PROTOCOL.Delete()` in the UEFI Specification for more details.
93+
///
94+
/// * [`uefi::Status::WARN_DELETE_FAILURE`]
8195
fn delete(mut self) -> Result {
8296
let result = (self.imp().delete)(self.imp()).into();
8397
mem::forget(self);
@@ -95,11 +109,14 @@ pub trait File: Sized {
95109
/// * `buffer` Buffer that the information should be written into
96110
///
97111
/// # Errors
98-
/// * `uefi::Status::UNSUPPORTED` The file does not possess this information type
99-
/// * `uefi::Status::NO_MEDIA` The device has no medium
100-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
101-
/// * `uefi::Status::VOLUME_CORRUPTED` The file system structures are corrupted
102-
/// * `uefi::Status::BUFFER_TOO_SMALL` The buffer is too small for the requested
112+
///
113+
/// See section `EFI_FILE_PROTOCOL.GetInfo()` in the UEFI Specification for more details.
114+
///
115+
/// * [`uefi::Status::UNSUPPORTED`]
116+
/// * [`uefi::Status::NO_MEDIA`]
117+
/// * [`uefi::Status::DEVICE_ERROR`]
118+
/// * [`uefi::Status::VOLUME_CORRUPTED`]
119+
/// * [`uefi::Status::BUFFER_TOO_SMALL`]
103120
fn get_info<'buf, Info: FileProtocolInfo + ?Sized>(
104121
&mut self,
105122
buffer: &'buf mut [u8],
@@ -137,13 +154,17 @@ pub trait File: Sized {
137154
/// * `info` Info that should be set for the file
138155
///
139156
/// # Errors
140-
/// * `uefi::Status::UNSUPPORTED` The file does not possess this information type
141-
/// * `uefi::Status::NO_MEDIA` The device has no medium
142-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
143-
/// * `uefi::Status::VOLUME_CORRUPTED` The file system structures are corrupted
144-
/// * `uefi::Status::WRITE_PROTECTED` Attempted to set information on a read-only media
145-
/// * `uefi::Status::ACCESS_DENIED` Requested change is invalid for this information type
146-
/// * `uefi::Status::VOLUME_FULL` Not enough space left on the volume to change the info
157+
///
158+
/// See section `EFI_FILE_PROTOCOL.SetInfo()` in the UEFI Specification for more details.
159+
///
160+
/// * [`uefi::Status::UNSUPPORTED`]
161+
/// * [`uefi::Status::NO_MEDIA`]
162+
/// * [`uefi::Status::DEVICE_ERROR`]
163+
/// * [`uefi::Status::VOLUME_CORRUPTED`]
164+
/// * [`uefi::Status::WRITE_PROTECTED`]
165+
/// * [`uefi::Status::ACCESS_DENIED`]
166+
/// * [`uefi::Status::VOLUME_FULL`]
167+
/// * [`uefi::Status::BAD_BUFFER_SIZE`]
147168
fn set_info<Info: FileProtocolInfo + ?Sized>(&mut self, info: &Info) -> Result {
148169
let info_ptr = (info as *const Info).cast::<c_void>();
149170
let info_size = mem::size_of_val(&info);
@@ -153,12 +174,15 @@ pub trait File: Sized {
153174
/// Flushes all modified data associated with the file handle to the device
154175
///
155176
/// # Errors
156-
/// * `uefi::Status::NO_MEDIA` The device has no media
157-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
158-
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
159-
/// * `uefi::Status::WRITE_PROTECTED` The file or medium is write protected
160-
/// * `uefi::Status::ACCESS_DENIED` The file was opened read only
161-
/// * `uefi::Status::VOLUME_FULL` The volume is full
177+
///
178+
/// See section `EFI_FILE_PROTOCOL.Flush()` in the UEFI Specification for more details.
179+
///
180+
/// * [`uefi::Status::NO_MEDIA`]
181+
/// * [`uefi::Status::DEVICE_ERROR`]
182+
/// * [`uefi::Status::VOLUME_CORRUPTED`]
183+
/// * [`uefi::Status::WRITE_PROTECTED`]
184+
/// * [`uefi::Status::ACCESS_DENIED`]
185+
/// * [`uefi::Status::VOLUME_FULL`]
162186
fn flush(&mut self) -> Result {
163187
(self.imp().flush)(self.imp()).into()
164188
}

‎uefi/src/proto/media/file/regular.rs

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,13 @@ impl RegularFile {
3131
/// * `buffer` The target buffer of the read operation
3232
///
3333
/// # Errors
34-
/// * `uefi::Status::NO_MEDIA` The device has no media
35-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error, the file was deleted,
36-
/// or the end of the file was reached before the `read()`.
37-
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
38-
/// * `uefi::Status::BUFFER_TOO_SMALL` The buffer is too small to hold a directory entry,
39-
/// and the required buffer size is provided as output.
34+
///
35+
/// See section `EFI_FILE_PROTOCOL.Read()` in the UEFI Specification for more details.
36+
///
37+
/// * [`uefi::Status::NO_MEDIA`]
38+
/// * [`uefi::Status::DEVICE_ERROR`]
39+
/// * [`uefi::Status::VOLUME_CORRUPTED`]
40+
/// * [`uefi::Status::BUFFER_TOO_SMALL`]
4041
pub fn read(&mut self, buffer: &mut [u8]) -> Result<usize, Option<usize>> {
4142
let mut buffer_size = buffer.len();
4243
let status =
@@ -67,12 +68,15 @@ impl RegularFile {
6768
/// * `buffer` Buffer to write to file
6869
///
6970
/// # Errors
70-
/// * `uefi::Status::NO_MEDIA` The device has no media
71-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error or the file was deleted.
72-
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
73-
/// * `uefi::Status::WRITE_PROTECTED` Attempt to write to readonly file
74-
/// * `uefi::Status::ACCESS_DENIED` The file was opened read only.
75-
/// * `uefi::Status::VOLUME_FULL` The volume is full
71+
///
72+
/// See section `EFI_FILE_PROTOCOL.Write()` in the UEFI Specification for more details.
73+
///
74+
/// * [`uefi::Status::NO_MEDIA`]
75+
/// * [`uefi::Status::DEVICE_ERROR`]
76+
/// * [`uefi::Status::VOLUME_CORRUPTED`]
77+
/// * [`uefi::Status::WRITE_PROTECTED`]
78+
/// * [`uefi::Status::ACCESS_DENIED`]
79+
/// * [`uefi::Status::VOLUME_FULL`]
7680
pub fn write(&mut self, buffer: &[u8]) -> Result<(), usize> {
7781
let mut buffer_size = buffer.len();
7882
unsafe { (self.imp().write)(self.imp(), &mut buffer_size, buffer.as_ptr()) }
@@ -82,7 +86,10 @@ impl RegularFile {
8286
/// Get the file's current position
8387
///
8488
/// # Errors
85-
/// * `uefi::Status::DEVICE_ERROR` An attempt was made to get the position of a deleted file
89+
///
90+
/// See section `EFI_FILE_PROTOCOL.GetPosition()` in the UEFI Specification for more details.
91+
///
92+
/// * [`uefi::Status::DEVICE_ERROR`]
8693
pub fn get_position(&mut self) -> Result<u64> {
8794
let mut pos = 0u64;
8895
(self.imp().get_position)(self.imp(), &mut pos).into_with_val(|| pos)
@@ -99,7 +106,10 @@ impl RegularFile {
99106
/// * `position` The new absolution position of the file handle
100107
///
101108
/// # Errors
102-
/// * `uefi::Status::DEVICE_ERROR` An attempt was made to set the position of a deleted file
109+
///
110+
/// See section `EFI_FILE_PROTOCOL.SetPosition()` in the UEFI Specification for more details.
111+
///
112+
/// * [`uefi::Status::DEVICE_ERROR`]
103113
pub fn set_position(&mut self, position: u64) -> Result {
104114
(self.imp().set_position)(self.imp(), position).into()
105115
}

‎uefi/src/proto/media/fs.rs

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,21 @@ impl SimpleFileSystem {
3131
/// Open the root directory on a volume.
3232
///
3333
/// # Errors
34-
/// * `uefi::Status::UNSUPPORTED` - The volume does not support the requested filesystem type
35-
/// * `uefi::Status::NO_MEDIA` - The device has no media
36-
/// * `uefi::Status::DEVICE_ERROR` - The device reported an error
37-
/// * `uefi::Status::VOLUME_CORRUPTED` - The file system structures are corrupted
38-
/// * `uefi::Status::ACCESS_DENIED` - The service denied access to the file
39-
/// * `uefi::Status::OUT_OF_RESOURCES` - The volume was not opened
40-
/// * `uefi::Status::MEDIA_CHANGED` - The device has a different medium in it
34+
///
35+
/// See section `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()` in the UEFI Specification
36+
/// for more details.
37+
///
38+
/// If you can't find the function definition, try searching for
39+
/// `EFI_SIMPLE_FILE SYSTEM_PROTOCOL.OpenVolume()` (this has a space in between FILE and
40+
/// SYSTEM; it could be a typo in the UEFI spec).
41+
///
42+
/// * [`uefi::Status::UNSUPPORTED`]
43+
/// * [`uefi::Status::NO_MEDIA`]
44+
/// * [`uefi::Status::DEVICE_ERROR`]
45+
/// * [`uefi::Status::VOLUME_CORRUPTED`]
46+
/// * [`uefi::Status::ACCESS_DENIED`]
47+
/// * [`uefi::Status::OUT_OF_RESOURCES`]
48+
/// * [`uefi::Status::MEDIA_CHANGED`]
4149
pub fn open_volume(&mut self) -> Result<Directory> {
4250
let mut ptr = ptr::null_mut();
4351
(self.open_volume)(self, &mut ptr)

‎uefi/src/table/boot.rs

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -996,6 +996,10 @@ impl BootServices {
996996
/// # Ok(())
997997
/// # }
998998
/// ```
999+
///
1000+
/// # Errors
1001+
///
1002+
/// Returns [`NOT_FOUND`] if no handles support the requested protocol.
9991003
pub fn get_handle_for_protocol<P: Protocol>(&self) -> Result<Handle> {
10001004
// Delegate to a non-generic function to potentially reduce code size.
10011005
self.get_handle_for_protocol_impl(&P::GUID)
@@ -1523,6 +1527,12 @@ impl BootServices {
15231527
#[cfg(feature = "alloc")]
15241528
impl BootServices {
15251529
/// Returns all the handles implementing a certain protocol.
1530+
///
1531+
/// # Errors
1532+
///
1533+
/// All errors come from calls to [`locate_handle`].
1534+
///
1535+
/// [`locate_handle`]: Self::locate_handle
15261536
pub fn find_handles<P: Protocol>(&self) -> Result<Vec<Handle>> {
15271537
// Search by protocol.
15281538
let search_type = SearchType::from_proto::<P>();

0 commit comments

Comments
 (0)