Skip to content

uefi: Clean up error docs in media protocols #1568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 10, 2025
Merged

uefi: Clean up error docs in media protocols #1568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 26 additions & 39 deletions uefi/src/proto/media/disk.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)(
Expand All @@ -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)(
Expand Down Expand Up @@ -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()
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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<NonNull<DiskIo2Token>>) -> Result {
let token = opt_nonnull_to_ptr(token);
unsafe { (self.0.flush_disk_ex)(&mut self.0, token.cast()) }.to_result()
Expand Down
40 changes: 21 additions & 19 deletions uefi/src/proto/media/load_file.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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")]
Expand Down