Skip to content

doc: streamline Error and Argument sections #1603

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc: streamline Error and Argument sections #1603

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
189 changes: 82 additions & 107 deletions uefi/src/boot.rs
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 0 additions & 2 deletions uefi/src/data_types/strs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,7 +362,6 @@ impl CStr16 {
/// Creates a `&CStr16` from a u16 slice, stopping at the first nul character.
///
/// # Errors
///
/// An error is returned if the slice contains invalid UCS-2 characters, or
/// if the slice does not contain any nul character.
pub fn from_u16_until_nul(codes: &[u16]) -> Result<&Self, FromSliceUntilNulError> {
Expand Down Expand Up @@ -411,7 +410,6 @@ impl CStr16 {
/// Creates a `&CStr16` from a [`Char16`] slice, stopping at the first nul character.
///
/// # Errors
///
/// An error is returned if the slice does not contain any nul character.
pub fn from_char16_until_nul(chars: &[Char16]) -> Result<&Self, FromSliceUntilNulError> {
// Find the index of the first null char.
Expand Down
2 changes: 1 addition & 1 deletion uefi/src/mem/memory_map/impl_.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ pub(crate) struct MemoryMapBackingMemory(NonNull<[u8]>);
impl MemoryMapBackingMemory {
/// Constructs a new [`MemoryMapBackingMemory`].
///
/// # Parameters
/// # Arguments
/// - `memory_type`: The memory type for the memory map allocation.
/// Typically, [`MemoryType::LOADER_DATA`] for regular UEFI applications.
pub(crate) fn new(memory_type: MemoryType) -> crate::Result<Self> {
Expand Down
7 changes: 4 additions & 3 deletions uefi/src/proto/console/pointer/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,12 @@ impl Pointer {
/// Resets the pointer device hardware.
///
/// # Arguments
/// The `extended_verification` parameter is used to request that UEFI
/// performs an extended check and reset of the input device.
/// - `extended_verification`: Request that UEFI performs an extended check
/// and reset of the input device.
///
/// # Errors
/// - `DeviceError` if the device is malfunctioning and cannot be reset.
/// - [`Status::DEVICE_ERROR`] if the device is malfunctioning and cannot be
/// reset.
pub fn reset(&mut self, extended_verification: bool) -> Result {
unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
}
Expand Down
10 changes: 5 additions & 5 deletions uefi/src/proto/console/text/input.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,13 @@ pub struct Input(SimpleTextInputProtocol);
impl Input {
/// Resets the input device hardware.
///
/// The `extended_verification` parameter is used to request that UEFI
/// performs an extended check and reset of the input device.
/// # Arguments
/// - `extended_verification`: Request that UEFI performs an extended check
/// and reset of the input device.
///
/// # Errors
///
/// - `DeviceError` if the device is malfunctioning and cannot be reset.
/// - [`Status::DEVICE_ERROR`] if the device is malfunctioning and cannot
/// be reset.
pub fn reset(&mut self, extended_verification: bool) -> Result {
unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
}
Expand All @@ -33,7 +34,6 @@ impl Input {
/// [`wait_for_key_event`]: Self::wait_for_key_event
///
/// # Errors
///
/// - [`Status::DEVICE_ERROR`] if there was an issue with the input device
///
/// # Examples
Expand Down
1 change: 0 additions & 1 deletion uefi/src/proto/device_path/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -401,7 +401,6 @@ impl DevicePath {
/// end-entire node.
///
/// # Errors
///
/// The [`ByteConversionError::InvalidLength`] error will be returned
/// when the length of the given bytes slice cannot contain the full
/// [`DevicePath`] represented by the slice.
Expand Down
55 changes: 30 additions & 25 deletions uefi/src/proto/media/block.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
//! Block I/O protocols.

use crate::proto::unsafe_protocol;
#[cfg(doc)]
use crate::Status;
use crate::{Result, StatusExt};

pub use uefi_raw::protocol::block::{BlockIoProtocol, Lba};
Expand All @@ -23,11 +25,11 @@ impl BlockIO {
/// Resets the block device hardware.
///
/// # Arguments
/// * `extended_verification` Indicates that the driver may perform a more
/// exhaustive verification operation of the device during reset.
/// * `extended_verification`: Request that UEFI performs an extended check
/// and reset of the input device.
///
/// # Errors
/// * `uefi::Status::DEVICE_ERROR` The block device is not functioning
/// * [`Status::DEVICE_ERROR`] if the block device is not functioning
/// correctly and could not be reset.
pub fn reset(&mut self, extended_verification: bool) -> Result {
unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
Expand All @@ -36,18 +38,20 @@ impl BlockIO {
/// Read the requested number of blocks from the device.
///
/// # Arguments
/// * `media_id` - The media ID that the read request is for.
/// * `lba` - The starting logical block address to read from on the device.
/// * `buffer` - The target buffer of the read operation
/// * `media_id`: The media ID that the read request is for.
/// * `lba`: The starting logical block address to read from on the device.
/// * `buffer`: The target buffer of the read operation
///
/// # Errors
/// * `uefi::Status::DEVICE_ERROR` The device reported an error while attempting to perform the read
/// operation.
/// * `uefi::Status::NO_MEDIA` There is no media in the device.
/// * `uefi::Status::MEDIA_CHANGED` The `media_id` is not for the current media.
/// * `uefi::Status::BAD_BUFFER_SIZE` The buffer size parameter is not a multiple of the intrinsic block size of
/// the device.
/// * `uefi::Status::INVALID_PARAMETER` The read request contains LBAs that are not valid, or the buffer is not on
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
/// attempting to perform the read operation.
/// * [`Status::NO_MEDIA`] when there is no media in the device.
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
/// media.
/// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
/// a multiple of the intrinsic block size of the device.
/// * [`Status::INVALID_PARAMETER`] when the read request contains LBAs
/// that are not valid, or the buffer is not on
/// proper alignment.
pub fn read_blocks(&self, media_id: u32, lba: Lba, buffer: &mut [u8]) -> Result {
let buffer_size = buffer.len();
Expand All @@ -66,20 +70,21 @@ impl BlockIO {
/// Writes the requested number of blocks to the device.
///
/// # Arguments
/// * `media_id` The media ID that the write request is for.
/// * `lba` The starting logical block address to be written.
/// * `buffer` Buffer to be written
/// * `media_id`: The media ID that the write request is for.
/// * `lba`: The starting logical block address to be written.
/// * `buffer`: Buffer to be written
///
/// # Errors
/// * `uefi::Status::WRITE_PROTECTED` The device cannot be written to.
/// * `uefi::Status::NO_MEDIA` There is no media in the device.
/// * `uefi::Status::MEDIA_CHANGED` The `media_id` is not for the current media.
/// * `uefi::Status::DEVICE_ERROR` The device reported an error while attempting to perform the write
/// operation.
/// * `uefi::Status::BAD_BUFFER_SIZE` The buffer size parameter is not a multiple of the intrinsic block size
/// of the device.
/// * `uefi::Status::INVALID_PARAMETER` The write request contains LBAs that are not valid, or the buffer is not
/// on proper alignment.
/// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
/// * [`Status::NO_MEDIA`] when there is no media in the device.
/// * [`Status::MEDIA_CHANGED`] when the `media_id` is not for the
/// current media.
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
/// attempting to perform the write operation.
/// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
/// a multiple of the intrinsic block size of the device.
/// * [`Status::INVALID_PARAMETER`] The write request contains LBAs that
/// are not valid, or the buffer is not on proper alignment.
pub fn write_blocks(&mut self, media_id: u32, lba: Lba, buffer: &[u8]) -> Result {
let buffer_size = buffer.len();
unsafe {
Expand Down
123 changes: 70 additions & 53 deletions uefi/src/proto/media/disk.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,19 @@ pub struct DiskIo(DiskIoProtocol);
impl DiskIo {
/// Reads bytes from the disk device.
///
/// # Arguments:
/// * `media_id` - ID of the medium to be read.
/// * `offset` - Starting byte offset on the logical block I/O device to read from.
/// * `buffer` - Pointer to a buffer to read into.
/// # Arguments
/// * `media_id`: ID of the medium to be read.
/// * `offset`: Starting byte offset on the logical block I/O device to read from.
/// * `buffer`: Pointer to a buffer to read into.
///
/// # Errors:
/// * [`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.
/// # Errors
/// * [`Status::INVALID_PARAMETER`] when the read request contains device
/// addresses that are not valid for the device.
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
/// performing the read operation.
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
/// * [`Status::MEDIA_CHANGED`] when `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 @@ -47,17 +50,20 @@ impl DiskIo {

/// Writes bytes to the disk device.
///
/// # Arguments:
/// * `media_id` - ID of the medium to be written.
/// * `offset` - Starting byte offset on the logical block I/O device to write to.
/// * `buffer` - Pointer to a buffer to write from.
/// # Arguments
/// * `media_id`: ID of the medium to be written.
/// * `offset`: Starting byte offset on the logical block I/O device to write to.
/// * `buffer`: Pointer to a buffer to write from.
///
/// # Errors:
/// * [`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.
/// # Errors
/// * [`Status::INVALID_PARAMETER`] when the write request contains device
/// addresses that are not valid for the device.
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
/// performing the write operation.
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
/// * [`Status::MEDIA_CHANGED`] then `media_id` is not for the current
/// medium.
/// * [`Status::WRITE_PROTECTED`] when 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 @@ -94,32 +100,36 @@ pub struct DiskIo2(DiskIo2Protocol);
impl DiskIo2 {
/// Terminates outstanding asynchronous requests to the device.
///
/// # Errors:
/// # Errors
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing
pub fn cancel(&mut self) -> Result {
unsafe { (self.0.cancel)(&mut self.0) }.to_result()
}

/// Reads bytes from the disk device.
///
/// # Arguments:
/// * `media_id` - ID of the medium to be read from.
/// * `offset` - Starting byte offset on the logical block I/O device to read from.
/// * `token` - Transaction token for asynchronous read.
/// * `len` - Buffer size.
/// * `buffer` - Buffer to read into.
/// # Arguments
/// * `media_id`: ID of the medium to be read from.
/// * `offset`: Starting byte offset on the logical block I/O device to read from.
/// * `token`: Transaction token for asynchronous read.
/// * `len`: Buffer size.
/// * `buffer`: Buffer to read into.
///
/// # Safety
///
/// Because of the asynchronous nature of the disk transaction, manual lifetime
/// tracking is required.
///
/// # Errors:
/// * [`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.
/// # Errors
/// * [`Status::INVALID_PARAMETER`] when the read request contains device
/// addresses that are not valid for the device.
/// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
/// due to a lack of resources.
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
/// medium.
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
/// performing the read operation.
pub unsafe fn read_disk_raw(
&self,
media_id: u32,
Expand All @@ -137,25 +147,29 @@ impl DiskIo2 {

/// Writes bytes to the disk device.
///
/// # Arguments:
/// * `media_id` - ID of the medium to write to.
/// * `offset` - Starting byte offset on the logical block I/O device to write to.
/// * `token` - Transaction token for asynchronous write.
/// * `len` - Buffer size.
/// * `buffer` - Buffer to write from.
/// # Arguments
/// * `media_id`: ID of the medium to write to.
/// * `offset`: Starting byte offset on the logical block I/O device to write to.
/// * `token`: Transaction token for asynchronous write.
/// * `len`: Buffer size.
/// * `buffer`: Buffer to write from.
///
/// # Safety
///
/// Because of the asynchronous nature of the disk transaction, manual lifetime
/// tracking is required.
///
/// # Errors:
/// * [`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.
/// # Errors
/// * [`Status::INVALID_PARAMETER`] when the write request contains device
/// addresses that are not valid for the device.
/// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
/// due to a lack of resources.
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
/// medium.
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
/// performing the write operation.
/// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
pub unsafe fn write_disk_raw(
&mut self,
media_id: u32,
Expand All @@ -180,15 +194,18 @@ impl DiskIo2 {

/// Flushes all modified data to the physical device.
///
/// # Arguments:
/// * `token` - Transaction token for the asynchronous flush.
/// # Arguments
/// * `token`: Transaction token for the asynchronous flush.
///
/// # Errors:
/// * [`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.
/// # Errors
/// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
/// due to a lack of resources.
/// * [`Status::MEDIA_CHANGED`] when the medium in the device has changed
/// since the last access.
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
/// performing the flush operation.
/// * [`Status::WRITE_PROTECTED`] when 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
Loading