Skip to content

Add some documentation for media protocols #614

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 2 commits into from
Dec 28, 2022
Merged

Add some documentation for media protocols #614

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
001b16e
Add some documentation for media protocols
raccog Dec 21, 2022
21c2a42
Fix error documentation for `File::open`
raccog Dec 27, 2022
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
12 changes: 6 additions & 6 deletions uefi/src/proto/media/file/dir.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,12 +38,8 @@ impl Directory {
/// * `buffer` The target buffer of the read operation
///
/// # Errors
/// * `uefi::Status::NO_MEDIA` The device has no media
/// * `uefi::Status::DEVICE_ERROR` The device reported an error, the file was deleted,
/// or the end of the file was reached before the `read()`.
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
/// * `uefi::Status::BUFFER_TOO_SMALL` The buffer is too small to hold a directory entry,
/// the required buffer size is provided into the error.
///
/// All errors come from calls to [`RegularFile::read`].
pub fn read_entry<'buf>(
&mut self,
buffer: &'buf mut [u8],
Expand Down Expand Up @@ -120,6 +116,10 @@ impl Directory {
}

/// Start over the process of enumerating directory entries
///
/// # Errors
///
/// All errors come from calls to [`RegularFile::set_position`].
pub fn reset_entry_readout(&mut self) -> Result {
self.0.set_position(0)
}
Expand Down
79 changes: 50 additions & 29 deletions uefi/src/proto/media/file/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,16 +41,24 @@ pub trait File: Sized {
/// * `attributes` Only valid when `FILE_MODE_CREATE` is used as a mode
///
/// # Errors
/// * `uefi::Status::INVALID_PARAMETER` The filename exceeds the maximum length of 255 chars
/// * `uefi::Status::NOT_FOUND` Could not find file
/// * `uefi::Status::NO_MEDIA` The device has no media
/// * `uefi::Status::MEDIA_CHANGED` The device has a different medium in it
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
/// * `uefi::Status::WRITE_PROTECTED` Write/Create attempted on readonly file
/// * `uefi::Status::ACCESS_DENIED` The service denied access to the file
/// * `uefi::Status::OUT_OF_RESOURCES` Not enough resources to open file
/// * `uefi::Status::VOLUME_FULL` The volume is full
///
/// See section `EFI_FILE_PROTOCOL.Open()` in the UEFI Specification for more details.
/// Note that [`INVALID_PARAMETER`] is not listed in the specification as one of the
/// errors returned by this function, but some implementations (such as EDK2) perform
/// additional validation and may return that status for invalid inputs.
///
/// [`INVALID_PARAMETER`]: uefi::Status::INVALID_PARAMETER
///
/// * [`uefi::Status::INVALID_PARAMETER`]
/// * [`uefi::Status::NOT_FOUND`]
/// * [`uefi::Status::NO_MEDIA`]
/// * [`uefi::Status::MEDIA_CHANGED`]
/// * [`uefi::Status::DEVICE_ERROR`]
/// * [`uefi::Status::VOLUME_CORRUPTED`]
/// * [`uefi::Status::WRITE_PROTECTED`]
/// * [`uefi::Status::ACCESS_DENIED`]
/// * [`uefi::Status::OUT_OF_RESOURCES`]
/// * [`uefi::Status::VOLUME_FULL`]
fn open(
&mut self,
filename: &CStr16,
Expand All @@ -77,7 +85,10 @@ pub trait File: Sized {
/// Closes and deletes this file
///
/// # Warnings
/// * `uefi::Status::WARN_DELETE_FAILURE` The file was closed, but deletion failed
///
/// See section `EFI_FILE_PROTOCOL.Delete()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::WARN_DELETE_FAILURE`]
fn delete(mut self) -> Result {
let result = (self.imp().delete)(self.imp()).into();
mem::forget(self);
Expand All @@ -95,11 +106,14 @@ pub trait File: Sized {
/// * `buffer` Buffer that the information should be written into
///
/// # Errors
/// * `uefi::Status::UNSUPPORTED` The file does not possess this information type
/// * `uefi::Status::NO_MEDIA` The device has no medium
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
/// * `uefi::Status::VOLUME_CORRUPTED` The file system structures are corrupted
/// * `uefi::Status::BUFFER_TOO_SMALL` The buffer is too small for the requested
///
/// See section `EFI_FILE_PROTOCOL.GetInfo()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::UNSUPPORTED`]
/// * [`uefi::Status::NO_MEDIA`]
/// * [`uefi::Status::DEVICE_ERROR`]
/// * [`uefi::Status::VOLUME_CORRUPTED`]
/// * [`uefi::Status::BUFFER_TOO_SMALL`]
fn get_info<'buf, Info: FileProtocolInfo + ?Sized>(
&mut self,
buffer: &'buf mut [u8],
Expand Down Expand Up @@ -137,13 +151,17 @@ pub trait File: Sized {
/// * `info` Info that should be set for the file
///
/// # Errors
/// * `uefi::Status::UNSUPPORTED` The file does not possess this information type
/// * `uefi::Status::NO_MEDIA` The device has no medium
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
/// * `uefi::Status::VOLUME_CORRUPTED` The file system structures are corrupted
/// * `uefi::Status::WRITE_PROTECTED` Attempted to set information on a read-only media
/// * `uefi::Status::ACCESS_DENIED` Requested change is invalid for this information type
/// * `uefi::Status::VOLUME_FULL` Not enough space left on the volume to change the info
///
/// See section `EFI_FILE_PROTOCOL.SetInfo()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::UNSUPPORTED`]
/// * [`uefi::Status::NO_MEDIA`]
/// * [`uefi::Status::DEVICE_ERROR`]
/// * [`uefi::Status::VOLUME_CORRUPTED`]
/// * [`uefi::Status::WRITE_PROTECTED`]
/// * [`uefi::Status::ACCESS_DENIED`]
/// * [`uefi::Status::VOLUME_FULL`]
/// * [`uefi::Status::BAD_BUFFER_SIZE`]
fn set_info<Info: FileProtocolInfo + ?Sized>(&mut self, info: &Info) -> Result {
let info_ptr = (info as *const Info).cast::<c_void>();
let info_size = mem::size_of_val(&info);
Expand All @@ -153,12 +171,15 @@ pub trait File: Sized {
/// Flushes all modified data associated with the file handle to the device
///
/// # Errors
/// * `uefi::Status::NO_MEDIA` The device has no media
/// * `uefi::Status::DEVICE_ERROR` The device reported an error
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
/// * `uefi::Status::WRITE_PROTECTED` The file or medium is write protected
/// * `uefi::Status::ACCESS_DENIED` The file was opened read only
/// * `uefi::Status::VOLUME_FULL` The volume is full
///
/// See section `EFI_FILE_PROTOCOL.Flush()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::NO_MEDIA`]
/// * [`uefi::Status::DEVICE_ERROR`]
/// * [`uefi::Status::VOLUME_CORRUPTED`]
/// * [`uefi::Status::WRITE_PROTECTED`]
/// * [`uefi::Status::ACCESS_DENIED`]
/// * [`uefi::Status::VOLUME_FULL`]
fn flush(&mut self) -> Result {
(self.imp().flush)(self.imp()).into()
}
Expand Down
38 changes: 24 additions & 14 deletions uefi/src/proto/media/file/regular.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,13 @@ impl RegularFile {
/// * `buffer` The target buffer of the read operation
///
/// # Errors
/// * `uefi::Status::NO_MEDIA` The device has no media
/// * `uefi::Status::DEVICE_ERROR` The device reported an error, the file was deleted,
/// or the end of the file was reached before the `read()`.
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
/// * `uefi::Status::BUFFER_TOO_SMALL` The buffer is too small to hold a directory entry,
/// and the required buffer size is provided as output.
///
/// See section `EFI_FILE_PROTOCOL.Read()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::NO_MEDIA`]
/// * [`uefi::Status::DEVICE_ERROR`]
/// * [`uefi::Status::VOLUME_CORRUPTED`]
/// * [`uefi::Status::BUFFER_TOO_SMALL`]
pub fn read(&mut self, buffer: &mut [u8]) -> Result<usize, Option<usize>> {
let mut buffer_size = buffer.len();
let status =
Expand Down Expand Up @@ -67,12 +68,15 @@ impl RegularFile {
/// * `buffer` Buffer to write to file
///
/// # Errors
/// * `uefi::Status::NO_MEDIA` The device has no media
/// * `uefi::Status::DEVICE_ERROR` The device reported an error or the file was deleted.
/// * `uefi::Status::VOLUME_CORRUPTED` The filesystem structures are corrupted
/// * `uefi::Status::WRITE_PROTECTED` Attempt to write to readonly file
/// * `uefi::Status::ACCESS_DENIED` The file was opened read only.
/// * `uefi::Status::VOLUME_FULL` The volume is full
///
/// See section `EFI_FILE_PROTOCOL.Write()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::NO_MEDIA`]
/// * [`uefi::Status::DEVICE_ERROR`]
/// * [`uefi::Status::VOLUME_CORRUPTED`]
/// * [`uefi::Status::WRITE_PROTECTED`]
/// * [`uefi::Status::ACCESS_DENIED`]
/// * [`uefi::Status::VOLUME_FULL`]
pub fn write(&mut self, buffer: &[u8]) -> Result<(), usize> {
let mut buffer_size = buffer.len();
unsafe { (self.imp().write)(self.imp(), &mut buffer_size, buffer.as_ptr()) }
Expand All @@ -82,7 +86,10 @@ impl RegularFile {
/// Get the file's current position
///
/// # Errors
/// * `uefi::Status::DEVICE_ERROR` An attempt was made to get the position of a deleted file
///
/// See section `EFI_FILE_PROTOCOL.GetPosition()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::DEVICE_ERROR`]
pub fn get_position(&mut self) -> Result<u64> {
let mut pos = 0u64;
(self.imp().get_position)(self.imp(), &mut pos).into_with_val(|| pos)
Expand All @@ -99,7 +106,10 @@ impl RegularFile {
/// * `position` The new absolution position of the file handle
///
/// # Errors
/// * `uefi::Status::DEVICE_ERROR` An attempt was made to set the position of a deleted file
///
/// See section `EFI_FILE_PROTOCOL.SetPosition()` in the UEFI Specification for more details.
///
/// * [`uefi::Status::DEVICE_ERROR`]
pub fn set_position(&mut self, position: u64) -> Result {
(self.imp().set_position)(self.imp(), position).into()
}
Expand Down
22 changes: 15 additions & 7 deletions uefi/src/proto/media/fs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,21 @@ impl SimpleFileSystem {
/// Open the root directory on a volume.
///
/// # Errors
/// * `uefi::Status::UNSUPPORTED` - The volume does not support the requested filesystem type
/// * `uefi::Status::NO_MEDIA` - The device has no media
/// * `uefi::Status::DEVICE_ERROR` - The device reported an error
/// * `uefi::Status::VOLUME_CORRUPTED` - The file system structures are corrupted
/// * `uefi::Status::ACCESS_DENIED` - The service denied access to the file
/// * `uefi::Status::OUT_OF_RESOURCES` - The volume was not opened
/// * `uefi::Status::MEDIA_CHANGED` - The device has a different medium in it
///
/// See section `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()` in the UEFI Specification
/// for more details.
///
/// If you can't find the function definition, try searching for
/// `EFI_SIMPLE_FILE SYSTEM_PROTOCOL.OpenVolume()` (this has a space in between FILE and
/// SYSTEM; it could be a typo in the UEFI spec).
///
/// * [`uefi::Status::UNSUPPORTED`]
/// * [`uefi::Status::NO_MEDIA`]
/// * [`uefi::Status::DEVICE_ERROR`]
/// * [`uefi::Status::VOLUME_CORRUPTED`]
/// * [`uefi::Status::ACCESS_DENIED`]
/// * [`uefi::Status::OUT_OF_RESOURCES`]
/// * [`uefi::Status::MEDIA_CHANGED`]
pub fn open_volume(&mut self) -> Result<Directory> {
let mut ptr = ptr::null_mut();
(self.open_volume)(self, &mut ptr)
Expand Down
10 changes: 10 additions & 0 deletions uefi/src/table/boot.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -996,6 +996,10 @@ impl BootServices {
/// # Ok(())
/// # }
/// ```
///
/// # Errors
///
/// Returns [`NOT_FOUND`] if no handles support the requested protocol.
pub fn get_handle_for_protocol<P: Protocol>(&self) -> Result<Handle> {
// Delegate to a non-generic function to potentially reduce code size.
self.get_handle_for_protocol_impl(&P::GUID)
Expand Down Expand Up @@ -1523,6 +1527,12 @@ impl BootServices {
#[cfg(feature = "alloc")]
impl BootServices {
/// Returns all the handles implementing a certain protocol.
///
/// # Errors
///
/// All errors come from calls to [`locate_handle`].
///
/// [`locate_handle`]: Self::locate_handle
pub fn find_handles<P: Protocol>(&self) -> Result<Vec<Handle>> {
// Search by protocol.
let search_type = SearchType::from_proto::<P>();
Expand Down