From a6663726fbd7b21e45345ae0f6d547d0a6bd3e5b Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sun, 9 Mar 2025 17:09:41 -0400 Subject: [PATCH] uefi: Clean up error docs in media protocols * Fix the path to the status values -- `uefi::status::*` does not exist, it should be `Status::*`. * Drop `EFI_` prefix to match the actual `Status` constants. * Use doc links so that incorrect names are caught by rustdoc. * Reformat some errors to a single line for consistency. --- uefi/src/proto/media/disk.rs | 65 +++++++++++++------------------ uefi/src/proto/media/load_file.rs | 40 ++++++++++--------- 2 files changed, 47 insertions(+), 58 deletions(-) diff --git a/uefi/src/proto/media/disk.rs b/uefi/src/proto/media/disk.rs index a7043987b..80abd8c5a 100644 --- a/uefi/src/proto/media/disk.rs +++ b/uefi/src/proto/media/disk.rs @@ -28,12 +28,10 @@ impl DiskIo { /// * `buffer` - Pointer to a buffer to read into. /// /// # Errors: - /// * `uefi::status::INVALID_PARAMETER` The read request contains device addresses that - /// are not valid for the device. - /// * `uefi::status::DEVICE_ERROR` The device reported an error while performing - /// the read operation. - /// * `uefi::status::NO_MEDIA` There is no medium in the device. - /// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium. + /// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device. + /// * [`Status::DEVICE_ERROR`] The device reported an error while performing the read operation. + /// * [`Status::NO_MEDIA`] There is no medium in the device. + /// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium. pub fn read_disk(&self, media_id: u32, offset: u64, buffer: &mut [u8]) -> Result { unsafe { (self.0.read_disk)( @@ -55,13 +53,11 @@ impl DiskIo { /// * `buffer` - Pointer to a buffer to write from. /// /// # Errors: - /// * `uefi::status::INVALID_PARAMETER` The write request contains device addresses that - /// are not valid for the device. - /// * `uefi::status::DEVICE_ERROR` The device reported an error while performing - /// the write operation. - /// * `uefi::status::NO_MEDIA` There is no medium in the device. - /// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium. - /// * `uefi::status::WRITE_PROTECTED` The device cannot be written to. + /// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device. + /// * [`Status::DEVICE_ERROR`] The device reported an error while performing the write operation. + /// * [`Status::NO_MEDIA`] There is no medium in the device. + /// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium. + /// * [`Status::WRITE_PROTECTED`] The device cannot be written to. pub fn write_disk(&mut self, media_id: u32, offset: u64, buffer: &[u8]) -> Result { unsafe { (self.0.write_disk)( @@ -99,7 +95,7 @@ impl DiskIo2 { /// Terminates outstanding asynchronous requests to the device. /// /// # Errors: - /// * `uefi::status::DEVICE_ERROR` The device reported an error while performing + /// * [`Status::DEVICE_ERROR`] The device reported an error while performing /// the cancel operation. pub fn cancel(&mut self) -> Result { unsafe { (self.0.cancel)(&mut self.0) }.to_result() @@ -120,14 +116,11 @@ impl DiskIo2 { /// tracking is required. /// /// # Errors: - /// * `uefi::status::INVALID_PARAMETER` The read request contains device addresses - /// that are not valid for the device. - /// * `uefi::status::OUT_OF_RESOURCES` The request could not be completed due to - /// a lack of resources. - /// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium. - /// * `uefi::status::NO_MEDIA` There is no medium in the device. - /// * `uefi::status::DEVICE_ERROR` The device reported an error while performing - /// the read operation. + /// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device. + /// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources. + /// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium. + /// * [`Status::NO_MEDIA`] There is no medium in the device. + /// * [`Status::DEVICE_ERROR`] The device reported an error while performing the read operation. pub unsafe fn read_disk_raw( &self, media_id: u32, @@ -156,15 +149,12 @@ impl DiskIo2 { /// tracking is required. /// /// # Errors: - /// * `uefi::status::INVALID_PARAMETER` The write request contains device addresses - /// that are not valid for the device. - /// * `uefi::status::OUT_OF_RESOURCES` The request could not be completed due to - /// a lack of resources. - /// * `uefi::status::MEDIA_CHANGED` `media_id` is not for the current medium. - /// * `uefi::status::NO_MEDIA` There is no medium in the device. - /// * `uefi::status::DEVICE_ERROR` The device reported an error while performing - /// the write operation. - /// * `uefi::status::WRITE_PROTECTED` The device cannot be written to. + /// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device. + /// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources. + /// * [`Status::MEDIA_CHANGED` `media_id` is not for the current medium. + /// * [`Status::NO_MEDIA`] There is no medium in the device. + /// * [`Status::DEVICE_ERROR`] The device reported an error while performing the write operation. + /// * [`Status::WRITE_PROTECTED`] The device cannot be written to. pub unsafe fn write_disk_raw( &mut self, media_id: u32, @@ -191,14 +181,11 @@ impl DiskIo2 { /// * `token` - Transaction token for the asynchronous flush. /// /// # Errors: - /// * `uefi::status::OUT_OF_RESOURCES` The request could not be completed due to - /// a lack of resources. - /// * `uefi::status::MEDIA_CHANGED` The medium in the device has changed since - /// the last access. - /// * `uefi::status::NO_MEDIA` There is no medium in the device. - /// * `uefi::status::DEVICE_ERROR` The device reported an error while performing - /// the flush operation. - /// * `uefi::status::WRITE_PROTECTED` The device cannot be written to. + /// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources. + /// * [`Status::MEDIA_CHANGED`] The medium in the device has changed since the last access. + /// * [`Status::NO_MEDIA`] There is no medium in the device. + /// * [`Status::DEVICE_ERROR`] The device reported an error while performing the flush operation. + /// * [`Status::WRITE_PROTECTED`] The device cannot be written to. pub fn flush_disk(&mut self, token: Option>) -> Result { let token = opt_nonnull_to_ptr(token); unsafe { (self.0.flush_disk_ex)(&mut self.0, token.cast()) }.to_result() diff --git a/uefi/src/proto/media/load_file.rs b/uefi/src/proto/media/load_file.rs index 7be088c2d..665145a46 100644 --- a/uefi/src/proto/media/load_file.rs +++ b/uefi/src/proto/media/load_file.rs @@ -3,6 +3,8 @@ //! LoadFile and LoadFile2 protocols. use crate::proto::unsafe_protocol; +#[cfg(doc)] +use crate::Status; #[cfg(all(feature = "alloc", feature = "unstable"))] use alloc::alloc::Global; use uefi_raw::protocol::media::{LoadFile2Protocol, LoadFileProtocol}; @@ -44,22 +46,22 @@ impl LoadFile { /// - `boot_policy` The [`BootPolicy`] to use. /// /// # Errors - /// - `uefi::status::EFI_SUCCESS` The file was loaded. - /// - `uefi::status::EFI_UNSUPPORTED` The device does not support the + /// - [`Status::SUCCESS`] The file was loaded. + /// - [`Status::UNSUPPORTED`] The device does not support the /// provided BootPolicy. - /// - `uefi::status::EFI_INVALID_PARAMETER` FilePath is not a valid device + /// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device /// path, or BufferSize is NULL. - /// - `uefi::status::EFI_NO_MEDIA` No medium was present to load the file. - /// - `uefi::status::EFI_DEVICE_ERROR` The file was not loaded due to a + /// - [`Status::NO_MEDIA`] No medium was present to load the file. + /// - [`Status::DEVICE_ERROR`] The file was not loaded due to a /// device error. - /// - `uefi::status::EFI_NO_RESPONSE` The remote system did not respond. - /// - `uefi::status::EFI_NOT_FOUND` The file was not found. - /// - `uefi::status::EFI_ABORTED` The file load process was manually + /// - [`Status::NO_RESPONSE`] The remote system did not respond. + /// - [`Status::NOT_FOUND`] The file was not found. + /// - [`Status::ABORTED`] The file load process was manually /// cancelled. - /// - `uefi::status::EFI_BUFFER_TOO_SMALL` The BufferSize is too small to + /// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to /// read the current directory entry. BufferSize has been updated with the /// size needed to complete the request. - /// - `uefi::status::EFI_WARN_FILE_SYSTEM` The resulting Buffer contains + /// - [`Status::WARN_FILE_SYSTEM`] The resulting Buffer contains /// UEFI-compliant file system. /// /// [`BootPolicy`]: uefi::proto::BootPolicy @@ -119,18 +121,18 @@ impl LoadFile2 { /// - `file_path` The device specific path of the file to load. /// /// # Errors - /// - `uefi::status::EFI_SUCCESS` The file was loaded. - /// - `uefi::status::EFI_UNSUPPORTED` BootPolicy is TRUE. - /// - `uefi::status::EFI_INVALID_PARAMETER` FilePath is not a valid device + /// - [`Status::SUCCESS`] The file was loaded. + /// - [`Status::UNSUPPORTED`] BootPolicy is TRUE. + /// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device /// path, or BufferSize is NULL. - /// - `uefi::status::EFI_NO_MEDIA` No medium was present to load the file. - /// - `uefi::status::EFI_DEVICE_ERROR` The file was not loaded due to a + /// - [`Status::NO_MEDIA`] No medium was present to load the file. + /// - [`Status::DEVICE_ERROR`] The file was not loaded due to a /// device error. - /// - `uefi::status::EFI_NO_RESPONSE` The remote system did not respond. - /// - `uefi::status::EFI_NOT_FOUND` The file was not found. - /// - `uefi::status::EFI_ABORTED` The file load process was manually + /// - [`Status::NO_RESPONSE`] The remote system did not respond. + /// - [`Status::NOT_FOUND`] The file was not found. + /// - [`Status::ABORTED`] The file load process was manually /// cancelled. - /// - `uefi::status::EFI_BUFFER_TOO_SMALL` The BufferSize is too small to + /// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to /// read the current directory entry. BufferSize has been updated with the /// size needed to complete the request. #[cfg(feature = "alloc")]