Skip to content

Commit a2fd496

Browse files
phip1611phip1611
authored
Merge pull request #1568 from rust-osdev/bishop-clean-up-err-docs
uefi: Clean up error docs in media protocols
2 parents 4838fde + a666372 commit a2fd496

File tree

2 files changed

+47
-58
lines changed

2 files changed

+47
-58
lines changed

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

Lines changed: 26 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,10 @@ impl DiskIo {
2828
/// * `buffer` - Pointer to a buffer to read into.
2929
///
3030
/// # Errors:
31-
/// * `uefi::status::INVALID_PARAMETER` The read request contains device addresses that
32-
/// are not valid for the device.
33-
/// * `uefi::status::DEVICE_ERROR` The device reported an error while performing
34-
/// the read operation.
35-
/// * `uefi::status::NO_MEDIA` There is no medium in the device.
36-
/// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium.
31+
/// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device.
32+
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the read operation.
33+
/// * [`Status::NO_MEDIA`] There is no medium in the device.
34+
/// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium.
3735
pub fn read_disk(&self, media_id: u32, offset: u64, buffer: &mut [u8]) -> Result {
3836
unsafe {
3937
(self.0.read_disk)(
@@ -55,13 +53,11 @@ impl DiskIo {
5553
/// * `buffer` - Pointer to a buffer to write from.
5654
///
5755
/// # Errors:
58-
/// * `uefi::status::INVALID_PARAMETER` The write request contains device addresses that
59-
/// are not valid for the device.
60-
/// * `uefi::status::DEVICE_ERROR` The device reported an error while performing
61-
/// the write operation.
62-
/// * `uefi::status::NO_MEDIA` There is no medium in the device.
63-
/// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium.
64-
/// * `uefi::status::WRITE_PROTECTED` The device cannot be written to.
56+
/// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device.
57+
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the write operation.
58+
/// * [`Status::NO_MEDIA`] There is no medium in the device.
59+
/// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium.
60+
/// * [`Status::WRITE_PROTECTED`] The device cannot be written to.
6561
pub fn write_disk(&mut self, media_id: u32, offset: u64, buffer: &[u8]) -> Result {
6662
unsafe {
6763
(self.0.write_disk)(
@@ -99,7 +95,7 @@ impl DiskIo2 {
9995
/// Terminates outstanding asynchronous requests to the device.
10096
///
10197
/// # Errors:
102-
/// * `uefi::status::DEVICE_ERROR` The device reported an error while performing
98+
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing
10399
/// the cancel operation.
104100
pub fn cancel(&mut self) -> Result {
105101
unsafe { (self.0.cancel)(&mut self.0) }.to_result()
@@ -120,14 +116,11 @@ impl DiskIo2 {
120116
/// tracking is required.
121117
///
122118
/// # Errors:
123-
/// * `uefi::status::INVALID_PARAMETER` The read request contains device addresses
124-
/// that are not valid for the device.
125-
/// * `uefi::status::OUT_OF_RESOURCES` The request could not be completed due to
126-
/// a lack of resources.
127-
/// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium.
128-
/// * `uefi::status::NO_MEDIA` There is no medium in the device.
129-
/// * `uefi::status::DEVICE_ERROR` The device reported an error while performing
130-
/// the read operation.
119+
/// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device.
120+
/// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources.
121+
/// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium.
122+
/// * [`Status::NO_MEDIA`] There is no medium in the device.
123+
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the read operation.
131124
pub unsafe fn read_disk_raw(
132125
&self,
133126
media_id: u32,
@@ -156,15 +149,12 @@ impl DiskIo2 {
156149
/// tracking is required.
157150
///
158151
/// # Errors:
159-
/// * `uefi::status::INVALID_PARAMETER` The write request contains device addresses
160-
/// that are not valid for the device.
161-
/// * `uefi::status::OUT_OF_RESOURCES` The request could not be completed due to
162-
/// a lack of resources.
163-
/// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium.
164-
/// * `uefi::status::NO_MEDIA` There is no medium in the device.
165-
/// * `uefi::status::DEVICE_ERROR` The device reported an error while performing
166-
/// the write operation.
167-
/// * `uefi::status::WRITE_PROTECTED` The device cannot be written to.
152+
/// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device.
153+
/// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources.
154+
/// * [`Status::MEDIA_CHANGED` `media_id` is not for the current medium.
155+
/// * [`Status::NO_MEDIA`] There is no medium in the device.
156+
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the write operation.
157+
/// * [`Status::WRITE_PROTECTED`] The device cannot be written to.
168158
pub unsafe fn write_disk_raw(
169159
&mut self,
170160
media_id: u32,
@@ -191,14 +181,11 @@ impl DiskIo2 {
191181
/// * `token` - Transaction token for the asynchronous flush.
192182
///
193183
/// # Errors:
194-
/// * `uefi::status::OUT_OF_RESOURCES` The request could not be completed due to
195-
/// a lack of resources.
196-
/// * `uefi::status::MEDIA_CHANGED` The medium in the device has changed since
197-
/// the last access.
198-
/// * `uefi::status::NO_MEDIA` There is no medium in the device.
199-
/// * `uefi::status::DEVICE_ERROR` The device reported an error while performing
200-
/// the flush operation.
201-
/// * `uefi::status::WRITE_PROTECTED` The device cannot be written to.
184+
/// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources.
185+
/// * [`Status::MEDIA_CHANGED`] The medium in the device has changed since the last access.
186+
/// * [`Status::NO_MEDIA`] There is no medium in the device.
187+
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the flush operation.
188+
/// * [`Status::WRITE_PROTECTED`] The device cannot be written to.
202189
pub fn flush_disk(&mut self, token: Option<NonNull<DiskIo2Token>>) -> Result {
203190
let token = opt_nonnull_to_ptr(token);
204191
unsafe { (self.0.flush_disk_ex)(&mut self.0, token.cast()) }.to_result()

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

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
//! LoadFile and LoadFile2 protocols.
44
55
use crate::proto::unsafe_protocol;
6+
#[cfg(doc)]
7+
use crate::Status;
68
#[cfg(all(feature = "alloc", feature = "unstable"))]
79
use alloc::alloc::Global;
810
use uefi_raw::protocol::media::{LoadFile2Protocol, LoadFileProtocol};
@@ -44,22 +46,22 @@ impl LoadFile {
4446
/// - `boot_policy` The [`BootPolicy`] to use.
4547
///
4648
/// # Errors
47-
/// - `uefi::status::EFI_SUCCESS` The file was loaded.
48-
/// - `uefi::status::EFI_UNSUPPORTED` The device does not support the
49+
/// - [`Status::SUCCESS`] The file was loaded.
50+
/// - [`Status::UNSUPPORTED`] The device does not support the
4951
/// provided BootPolicy.
50-
/// - `uefi::status::EFI_INVALID_PARAMETER` FilePath is not a valid device
52+
/// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device
5153
/// path, or BufferSize is NULL.
52-
/// - `uefi::status::EFI_NO_MEDIA` No medium was present to load the file.
53-
/// - `uefi::status::EFI_DEVICE_ERROR` The file was not loaded due to a
54+
/// - [`Status::NO_MEDIA`] No medium was present to load the file.
55+
/// - [`Status::DEVICE_ERROR`] The file was not loaded due to a
5456
/// device error.
55-
/// - `uefi::status::EFI_NO_RESPONSE` The remote system did not respond.
56-
/// - `uefi::status::EFI_NOT_FOUND` The file was not found.
57-
/// - `uefi::status::EFI_ABORTED` The file load process was manually
57+
/// - [`Status::NO_RESPONSE`] The remote system did not respond.
58+
/// - [`Status::NOT_FOUND`] The file was not found.
59+
/// - [`Status::ABORTED`] The file load process was manually
5860
/// cancelled.
59-
/// - `uefi::status::EFI_BUFFER_TOO_SMALL` The BufferSize is too small to
61+
/// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to
6062
/// read the current directory entry. BufferSize has been updated with the
6163
/// size needed to complete the request.
62-
/// - `uefi::status::EFI_WARN_FILE_SYSTEM` The resulting Buffer contains
64+
/// - [`Status::WARN_FILE_SYSTEM`] The resulting Buffer contains
6365
/// UEFI-compliant file system.
6466
///
6567
/// [`BootPolicy`]: uefi::proto::BootPolicy
@@ -119,18 +121,18 @@ impl LoadFile2 {
119121
/// - `file_path` The device specific path of the file to load.
120122
///
121123
/// # Errors
122-
/// - `uefi::status::EFI_SUCCESS` The file was loaded.
123-
/// - `uefi::status::EFI_UNSUPPORTED` BootPolicy is TRUE.
124-
/// - `uefi::status::EFI_INVALID_PARAMETER` FilePath is not a valid device
124+
/// - [`Status::SUCCESS`] The file was loaded.
125+
/// - [`Status::UNSUPPORTED`] BootPolicy is TRUE.
126+
/// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device
125127
/// path, or BufferSize is NULL.
126-
/// - `uefi::status::EFI_NO_MEDIA` No medium was present to load the file.
127-
/// - `uefi::status::EFI_DEVICE_ERROR` The file was not loaded due to a
128+
/// - [`Status::NO_MEDIA`] No medium was present to load the file.
129+
/// - [`Status::DEVICE_ERROR`] The file was not loaded due to a
128130
/// device error.
129-
/// - `uefi::status::EFI_NO_RESPONSE` The remote system did not respond.
130-
/// - `uefi::status::EFI_NOT_FOUND` The file was not found.
131-
/// - `uefi::status::EFI_ABORTED` The file load process was manually
131+
/// - [`Status::NO_RESPONSE`] The remote system did not respond.
132+
/// - [`Status::NOT_FOUND`] The file was not found.
133+
/// - [`Status::ABORTED`] The file load process was manually
132134
/// cancelled.
133-
/// - `uefi::status::EFI_BUFFER_TOO_SMALL` The BufferSize is too small to
135+
/// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to
134136
/// read the current directory entry. BufferSize has been updated with the
135137
/// size needed to complete the request.
136138
#[cfg(feature = "alloc")]

0 commit comments

Comments
 (0)