html-to-markdown 2.27.2 → 2.28.0

data/rust-vendor/r-efi-5.3.0/src/lib.rs

@@ -0,0 +1,182 @@
+//! UEFI Reference Specification Protocol Constants and Definitions
+//!
+//! This project provides protocol constants and definitions as defined in the UEFI Reference
+//! Specification. The aim is to provide all these constants as C-ABI compatible imports to rust.
+//! Safe rust abstractions over the UEFI API are out of scope of this project. That is, the
+//! purpose is really just to extract all the bits and pieces from the specification and provide
+//! them as rust types and constants.
+//!
+//! While we strongly recommend using safe abstractions to interact with UEFI systems, this
+//! project serves both as base to write those abstractions, but also as last resort if you have
+//! to deal with quirks and peculiarities of UEFI systems directly. Therefore, several examples
+//! are included, which show how to interact with UEFI systems from rust. These serve both as
+//! documentation for anyone interested in how the system works, but also as base for anyone
+//! implementing safe abstractions on top.
+//!
+//! # Target Configuration
+//!
+//! Rust code can be compiled natively for UEFI systems. However, you are quite unlikely to have a
+//! rust compiler running in an UEFI environment. Therefore, you will most likely want to cross
+//! compile your rust code for UEFI systems. To do this, you need a target-configuration for UEFI
+//! systems. As of rust-1.61, upstream rust includes the following UEFI targets:
+//!
+//!  * `aarch64-unknown-uefi`: A native UEFI target for aarch64 systems (64bit ARM).
+//!  * `i686-unknown-uefi`: A native UEFI target for i686 systems (32bit Intel x86).
+//!  * `x86_64-unknown-uefi`: A native UEFI target for x86-64 systems (64bit Intel x86).
+//!
+//! If none of these targets match your architecture, you have to create the target specification
+//! yourself. Feel free to contact the `r-efi` project for help.
+//!
+//! # Transpose Guidelines
+//!
+//! The UEFI specification provides C language symbols and definitions of all
+//! its protocols and features. Those are integral parts of the specification
+//! and UEFI programming is often tightly coupled with the C language. For
+//! better compatibility to existing UEFI documentation, all the rust symbols
+//! are transposed from C following strict rules, aiming for close similarity
+//! to specification. This section gives a rationale on some of the less
+//! obvious choices and tries to describe as many of those rules as possible.
+//!
+//!  * `no enums`: Rust enums do not allow random discriminant values. However,
+//!    many UEFI enumerations use reserved ranges for vendor defined values.
+//!    These cannot be represented with rust enums in an efficient manner.
+//!    Hence, any enumerations are turned into rust constants with an
+//!    accompanying type alias.
+//!
+//!    A detailed discussion can be found in:
+//!
+//!    ```gitlog
+//!        commit 401a91901e860a5c0cd0f92b75dda0a72cf65322
+//!        Author: David Rheinsberg <david.rheinsberg@gmail.com>
+//!        Date:   Wed Apr 21 12:07:07 2021 +0200
+//!
+//!            r-efi: convert enums to constants
+//!    ```
+//!
+//!  * `no incomplete types`: Several structures use incomplete structure types
+//!    by using an unbound array as last member. While rust can easily
+//!    represent those within its type-system, such structures become DSTs,
+//!    hence even raw pointers to them become fat-pointers, and would thus
+//!    violate the UEFI ABI.
+//!
+//!    Instead, we use const-generics to allow compile-time adjustment of the
+//!    variable-sized structures, with a default value of 0. This allows
+//!    computing different sizes of the structures without any runtime overhead.
+//!
+//!  * `nullable callbacks as Option`: Rust has no raw function pointers, but
+//!    just normal Rust function pointers. Those, however, have no valid null
+//!    value. The Rust ABI guarantees that `Option<fn ...>` is an C-ABI
+//!    compatible replacement for nullable function pointers, with `None` being
+//!    mapped to `NULL`. Hence, whenever UEFI APIs require nullable function
+//!    pointers, we use `Option<fn ...>`.
+//!
+//!  * `prefer *mut over *const`: Whenever we transpose pointers from the
+//!    specification into Rust, we prefer `*mut` in almost all cases. `*const`
+//!    should only be used if the underlying value is known not to be accessible
+//!    via any other mutable pointer type. Since this is rarely the case in
+//!    UEFI, we avoid it.
+//!
+//!    The reasoning is that Rust allows coercing immutable types into `*const`
+//!    pointers, without any explicit casting required. However, immutable Rust
+//!    references require that no other mutable reference exists simultaneously.
+//!    This is not a guarantee of `const`-pointers in C / UEFI, hence this
+//!    coercion is usually ill-advised or even wrong.
+//!
+//!    Lastly, note that `*mut` and `*const` and be `as`-casted in both
+//!    directions without violating any Rust guarantees. Any UB concerns always
+//!    stem from the safety guarantees of the surrounding code, not of the
+//!    raw-pointer handling.
+//!
+//! # Specification Details
+//!
+//! This section lists errata of, and general comments on, the UEFI
+//! specification relevant to the development of `r-efi`:
+//!
+//!  * The `Unload` function-pointer of the LoadedImageProtocol can be `NULL`,
+//!    despite the protocol documentation lacking any mention of this. Other
+//!    parts of the specification refer to images lacking an unload function,
+//!    but there is no explicit documentation how this manifests in the
+//!    protocol structure. EDK2 assumes `NULL` indicates a lack of unload
+//!    function, and an errata has been submitted to the UEFI forum.
+//!
+//!  * The specification mandates an 8-byte alignment for the `GUID` structure
+//!    However, all widespread implementations (including EDK2) use a 4-byte
+//!    alignment. An errata has been reported to EDK2 (still pending).
+//!
+//! # Examples
+//!
+//! To write free-standing UEFI applications, you need to disable the entry-point provided by rust
+//! and instead provide your own. Most target-configurations look for a function called `efi_main`
+//! during linking and set it as entry point. If you use the target-configurations provided with
+//! upstream rust, they will pick the function called `efi_main` as entry-point.
+//!
+//! The following example shows a minimal UEFI application, which simply returns success upon
+//! invocation. Note that you must provide your own panic-handler when running without `libstd`.
+//! In our case, we use a trivial implementation that simply loops forever.
+//!
+//! ```ignore
+//! #![no_main]
+//! #![no_std]
+//!
+//! use r_efi::efi;
+//!
+//! #[panic_handler]
+//! fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
+//!     loop {}
+//! }
+//!
+//! #[export_name = "efi_main"]
+//! pub extern fn main(_h: efi::Handle, _st: *mut efi::SystemTable) -> efi::Status {
+//!     efi::Status::SUCCESS
+//! }
+//! ```
+
+// Mark this crate as `no_std`. We have no std::* dependencies (and we better don't have them),
+// so no reason to require it. This does not mean that you cannot use std::* with UEFI. You have
+// to port it to UEFI first, though.
+//
+// In case of unit-test compilation, we pull in `std` and drop the `no_std` marker. This allows
+// basic unit-tests on the compilation host. For integration tests, we have separate compilation
+// units, so they will be unaffected by this.
+#![cfg_attr(not(test), no_std)]
+
+// Import the different core modules. We separate them into different modules to make it easier to
+// work on them and describe what each part implements. This is different to the reference
+// implementation, which uses a flat namespace due to its origins in the C language. For
+// compatibility, we provide this flat namespace as well. See the `efi` submodule.
+#[macro_use]
+pub mod base;
+#[macro_use]
+pub mod hii;
+#[macro_use]
+pub mod system;
+
+// Import the protocols. Each protocol is separated into its own module, readily imported by the
+// meta `protocols` module. Note that this puts all symbols into their respective protocol
+// namespace, thus clearly separating them (unlike the UEFI Specification, which more often than
+// not violates its own namespacing).
+pub mod protocols;
+
+// Import vendor protocols. They are just like protocols in `protocols`, but
+// separated for better namespacing.
+pub mod vendor;
+
+/// Flat EFI Namespace
+///
+/// The EFI namespace re-exports all symbols in a single, flat namespace. This allows mirroring
+/// the entire EFI namespace as given in the specification and makes it easier to refer to them
+/// with the same names as the reference C implementation.
+///
+/// Note that the individual protocols are put into submodules. The specification does this in
+/// most parts as well (by prefixing all symbols). This is not true in all cases, as the
+/// specification suffers from lack of namespaces in the reference C language. However, we decided
+/// to namespace the remaining bits as well, for better consistency throughout the API. This
+/// should be self-explanatory in nearly all cases.
+pub mod efi {
+    pub use crate::base::*;
+    pub use crate::system::*;
+
+    pub use crate::hii;
+    pub use crate::protocols;
+    pub use crate::vendor;
+}

data/rust-vendor/r-efi-5.3.0/src/protocols/absolute_pointer.rs

@@ -0,0 +1,69 @@
+//! Absolute Pointer Protocol
+//!
+//! Provides a simple method for accessing absolute pointer devices. This
+//! includes devices such as touch screens and digitizers. The Absolute Pointer
+//! Protocol allows information about a pointer device to be retrieved. The
+//! protocol is attached to the device handle of an absolute pointer device,
+//! and can be used for input from the user in the preboot environment.
+//!
+//! Supported devices may return 1, 2, or 3 axis of information. The Z axis may
+//! optionally be used to return pressure data measurements derived from user
+//! pen force.
+//!
+//! All supported devices must support a touch-active status. Supported devices
+//! may optionally support a second input button, for example a pen
+//! side-button.
+
+pub const PROTOCOL_GUID: crate::base::Guid = crate::base::Guid::from_fields(
+    0x8d59d32b,
+    0xc655,
+    0x4ae9,
+    0x9b,
+    0x15,
+    &[0xf2, 0x59, 0x04, 0x99, 0x2a, 0x43],
+);
+
+pub const SUPPORTS_ALT_ACTIVE: u32 = 0x00000001;
+pub const SUPPORTS_PRESSURE_AS_Z: u32 = 0x00000002;
+
+#[derive(Clone, Copy, Debug, Default)]
+#[repr(C)]
+pub struct Mode {
+    pub absolute_min_x: u64,
+    pub absolute_min_y: u64,
+    pub absolute_min_z: u64,
+    pub absolute_max_x: u64,
+    pub absolute_max_y: u64,
+    pub absolute_max_z: u64,
+    pub attributes: u32,
+}
+
+pub const TOUCH_ACTIVE: u32 = 0x00000001;
+pub const ALT_ACTIVE: u32 = 0x00000002;
+
+#[derive(Clone, Copy, Debug, Default)]
+#[repr(C)]
+pub struct State {
+    pub current_x: u64,
+    pub current_y: u64,
+    pub current_z: u64,
+    pub active_buttons: u32,
+}
+
+pub type Reset = eficall! {fn(
+    this: *mut Protocol,
+    extended_verification: bool,
+) -> crate::base::Status};
+
+pub type GetState = eficall! {fn(
+    this: *mut Protocol,
+    state: *mut State,
+) -> crate::base::Status};
+
+#[repr(C)]
+pub struct Protocol {
+    pub reset: Reset,
+    pub get_state: GetState,
+    pub wait_for_input: crate::efi::Event,
+    pub mode: *mut Mode,
+}

data/rust-vendor/r-efi-5.3.0/src/protocols/block_io.rs

@@ -0,0 +1,70 @@
+//! Block I/O Protocol
+//!
+//! Used to abstract mass storage devices to allow code running in the EFI boot services environment
+//! to access the storage devices without specific knowledge of the type of device or controller that
+//! manages the device.
+
+pub const PROTOCOL_GUID: crate::base::Guid = crate::base::Guid::from_fields(
+    0x964e5b21,
+    0x6459,
+    0x11d2,
+    0x8e,
+    0x39,
+    &[0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b],
+);
+
+pub const REVISION: u64 = 0x0000000000010000u64;
+pub const REVISION2: u64 = 0x0000000000020001u64;
+pub const REVISION3: u64 = 0x000000000002001fu64;
+
+#[repr(C)]
+#[derive(Clone, Copy, Debug)]
+pub struct Media {
+    pub media_id: u32,
+    pub removable_media: bool,
+    pub media_present: bool,
+    pub logical_partition: bool,
+    pub read_only: bool,
+    pub write_caching: bool,
+    pub block_size: u32,
+    pub io_align: u32,
+    pub last_block: crate::base::Lba,
+    pub lowest_aligned_lba: crate::base::Lba,
+    pub logical_blocks_per_physical_block: u32,
+    pub optimal_transfer_length_granularity: u32,
+}
+
+pub type ProtocolReset = eficall! {fn(
+    *mut Protocol,
+    crate::base::Boolean,
+) -> crate::base::Status};
+
+pub type ProtocolReadBlocks = eficall! {fn(
+    *mut Protocol,
+    u32,
+    crate::base::Lba,
+    usize,
+    *mut core::ffi::c_void,
+) -> crate::base::Status};
+
+pub type ProtocolWriteBlocks = eficall! {fn(
+    *mut Protocol,
+    u32,
+    crate::base::Lba,
+    usize,
+    *mut core::ffi::c_void,
+) -> crate::base::Status};
+
+pub type ProtocolFlushBlocks = eficall! {fn(
+    *mut Protocol,
+) -> crate::base::Status};
+
+#[repr(C)]
+pub struct Protocol {
+    pub revision: u64,
+    pub media: *const Media,
+    pub reset: ProtocolReset,
+    pub read_blocks: ProtocolReadBlocks,
+    pub write_blocks: ProtocolWriteBlocks,
+    pub flush_blocks: ProtocolFlushBlocks,
+}

data/rust-vendor/r-efi-5.3.0/src/protocols/bus_specific_driver_override.rs

@@ -0,0 +1,32 @@
+//! Bus Specific Driver Override Protocol
+//!
+//! This protocol matches one or more drivers to a controller. This protocol is
+//! produced by a bus driver, and it is installed on the child handles of buses
+//! that require a bus specific algorithm for matching drivers to controllers.
+//! This protocol is used by the `EFI_BOOT_SERVICES.ConnectController()` boot
+//! service to select the best driver for a controller. All of the drivers
+//! returned by this protocol have a higher precedence than drivers found in
+//! the general EFI Driver Binding search algorithm, but a lower precedence
+//! than those drivers returned by the EFI Platform Driver Override Protocol.
+//! If more than one driver image handle is returned by this protocol, then the
+//! drivers image handles are returned in order from highest precedence to
+//! lowest precedence.
+
+pub const PROTOCOL_GUID: crate::base::Guid = crate::base::Guid::from_fields(
+    0x3bc1b285,
+    0x8a15,
+    0x4a82,
+    0xaa,
+    0xbf,
+    &[0x4d, 0x7d, 0x13, 0xfb, 0x32, 0x65],
+);
+
+pub type ProtocolGetDriver = eficall! {fn(
+    *mut Protocol,
+    *mut crate::base::Handle,
+) -> crate::base::Status};
+
+#[repr(C)]
+pub struct Protocol {
+    pub get_driver: ProtocolGetDriver,
+}