html-to-markdown 2.27.2 → 2.27.3

data/rust-vendor/r-efi-5.3.0/NEWS.md

@@ -0,0 +1,301 @@
+# r-efi - UEFI Reference Specification Protocol Constants and Definitions
+
+## CHANGES WITH 5.3.0:
+
+        * Remove the optional dependency on `compiler-builtins`, which was
+          needed to build r-efi as part of rustc. This is no longer necessary.
+
+        Contributions from: David Rheinsberg, Trevor Gross
+
+        - Dußlingen, 2025-06-17
+
+## CHANGES WITH 5.2.0:
+
+        * Add the memory attribute protocol.
+
+        Contributions from: David Rheinsberg, Oliver Smith-Denny
+
+        - Dußlingen, 2024-12-22
+
+## CHANGES WITH 5.1.0:
+
+        * Mark `Guid::as_bytes` and `Guid::from_bytes` as `const fn`, aligning
+          them with the other methods on `Guid`. This helps creating constant
+          GUIDs via macros or other external helpers.
+
+        Contributions from: Christopher Zurcher, David Rheinsberg
+
+        - Dußlingen, 2024-09-01
+
+## CHANGES WITH 5.0.0:
+
+        * Change the type of the `unload` function-pointer of the Loaded Image
+          Protocol to `Option<Unload>`, given that it can be `NULL` to indicate
+          that the image cannot be unloaded.
+          This is a major API break, but any users very likely need to adjust
+          anyway to avoid NULL-derefs.
+
+        Contributions from: David Rheinsberg, John Schock
+
+        - Dußlingen, 2024-07-30
+
+## CHANGES WITH 4.5.0:
+
+        * Implement or derive more standard traits for UEFI base types. In
+          particular, implement `[Partial]Eq`, `Hash`, `[Partial]Ord` for
+          `Boolean`, `Status`, `Guid`, and network address types.
+
+        * Fix the signature of `BootUninstallMultipleProtocolInterfaces` to
+          match the UEFI specification. Note that it uses var-args and is thus
+          not fully usable from stable Rust.
+
+        Contributions from: Ayush Singh, David Rheinsberg, John Schock
+
+        - Dußlingen, 2024-05-23
+
+## CHANGES WITH 4.4.0:
+
+        * Add definitions for `UNACCEPTED_MEMORY_TYPE`, media device subtypes
+          for device paths, before-EBS and after-RTB event groups, missing
+          memory attributes.
+
+        * Add memory masks for common memory attribute classes. The symbol
+          names are takend from EDK2, yet their purpose is defined in the
+          specification.
+
+        * New protocols: platform_driver_override, bus_specific_driver_override,
+          driver_family_override, load_file, load_file2, pci-io
+
+        Contributions from: David Rheinsberg, Dmitry Mostovenko, John Schock,
+                            Michael Kubacki
+
+        - Dußlingen, 2024-03-27
+
+## CHANGES WITH 4.3.0:
+
+        * Change alignment of `Guid` to 4 (was 8 before). This deviates from
+          the specification, but aligns with EDK2. This should fix alignment
+          mismatches when combining r-efi with EDK2, or other UEFI
+          implementations.
+
+        * `Guid` gained a new constructor `from_bytes()` to allow creating
+          GUID-abstractions from foreign types based on the standardized
+          memory representation.
+
+        * Add all configuration-table GUIDs mentioned in the spec. These are
+          often rooted in external specifications, but are strongly related
+          to UEFI.
+
+        * Add configuration-table definitions for RT_PROPERTIES and
+          CONFORMANCE_PROFILES.
+
+        * New protocols: hii_package_list, absolute_pointer
+
+        Contributions from: David Rheinsberg, John Schock, Michael Kubacki,
+                            Nicholas Bishop
+
+        - Dußlingen, 2023-10-18
+
+## CHANGES WITH 4.2.0:
+
+        * Bump required compiler version to: rust-1.68
+
+        * New Protocols: debugport, debug-support, driver-diagnostics2,
+                         mp-services, shell, shell-dynamic-command,
+                         shell-parameters, udp-4, udp-6
+
+        * Use const-generics instead of ZSTs to represent dynamic trailing
+          members in C structs.
+
+        * The `examples` feature has been renamed to `native` (a backwards
+          compatible feature is left in place).
+
+        * Add support for riscv64.
+
+        * Use the official rust `efiapi` calling convention. This was
+          stabilized with rust-1.68.
+
+        Contributions from: Ayush Singh, David Rheinsberg, Rob Bradford
+
+        - Dußlingen, 2023-03-20
+
+## CHANGES WITH 4.1.0:
+
+        * New Protocols: device-path-{from,to}-text, ip4, ip6, managed-network,
+                         rng, service-binding, tcp4, tcp6, timestamp
+
+        * `ImageEntryPoint` is now correctly annotated as `eficall`.
+
+        * `Time` now derives `Default`.
+
+        * Fix nullable function pointers to use `Option<fn ...>`.
+
+        * Function prototypes now have an explicit type definition and can be
+          used independent of their protocol definition.
+
+        * The new `rust-dep-of-std` feature option allows pulling in r-efi
+          into the rust standard library. It prepares the crate workspace to
+          be suitable for the standard library. It has no use outside of this.
+
+        * Adopt the MIT license as 3rd licensing option to allow for
+          integration into the rust compiler and ecosystem.
+
+        Contributions from: Ayush Singh, David Rheinsberg, Joe Richey
+
+        - Tübingen, 2022-08-23
+
+## CHANGES WITH 4.0.0:
+
+        * Convert all enums to constants with type-aliases. This is an API
+          break, but it is needed for spec-compliance. With the old enums, one
+          couldn't encode all the possible values defined by the spec.
+          Especially, the vendor-reserved ranges were unable to be encoded in
+          a safe manner. Also see commit 401a91901e860 for a detailed
+          discussion.
+          API users likely need to convert their CamelCase enum usage to the
+          new UPPER_CASE constants.
+
+        * Convert all incomplete types to empty arrays. This affects all
+          structures that use trailing unbound arrays. These are actually ABI
+          incompatible with UEFI, since rust represents raw-pointers to such
+          types as fat-pointers. Such arrays have now been converted to empty
+          arrays, which should still allow accessing the memory location and
+          retaining structure properties, but avoids fat-pointers.
+          This is an API break, so you might have to adjust your accessors of
+          those trailing structure members.
+
+        * Implement `Clone` and `Copy` for most basic structures. Since these
+          are used as plain carriers, no higher clone/copy logic is needed. It
+          should be clear from the project-description, that only basic UEFI
+          compatibility is provided.
+
+        * Add the console-control vendor protocol. This protocol allows
+          controlling console properties. It is not part of the UEFI
+          specification, but rather defined by the TianoCore project.
+
+        * Add a new example showing how to use the GOP functions to query the
+          active graphics device.
+
+        Contributions from: David Rheinsberg, GGRei, Hiroki Tokunaga,
+                            Richard Wiedenhöft
+
+        - Tübingen, 2021-06-23
+
+## CHANGES WITH 3.2.0:
+
+        * Add new protocols: DiskIo, DiskIo2, BlockIo, DriverBinding
+
+        * Extend the Device-Path payload structure and add the HardDriveMedia
+          payload.
+
+        * Add HII definitions: A new top-level module `hii` with all the basic
+          HII constants, as well as a handful of HII protocols (hii_database,
+          hii_font, hii_string)
+
+        * Document new `-Zbuild-std` based cross-compilation, serving as
+          official rust alternative to cargo-xbuild.
+
+        Contributions from: Alex James, Bret Barkelew, David Rheinsberg,
+                            Michael Kubacki
+
+        - Tübingen, 2020-10-23
+
+## CHANGES WITH 3.1.0:
+
+        * Add the basic networking types to `r_efi::base`. This includes MAC
+          and IP address types.
+
+        * Add the EFI_SIMPLE_NETWORK_PROTOCOL definitions and all required
+          constants to make basic networking available.
+
+        * Add a new uefi-cross example, which is copied from upstream rustc
+          sources, so we can test local modifications to it.
+
+        Contributions from: Alex James, David Rheinsberg
+
+        - Tübingen, 2020-09-10
+
+## CHANGES WITH 3.0.0:
+
+        * Fix a missing parameter in `BootServices::locate_device_path()`. The
+          prototype incorrectly had 2 arguments, while the official version
+          takes 3. The final `handle` argument was missing.
+          This is an API break in `r-efi`. It should have a limited impact,
+          since the function was mostly useless without a handle.
+          Thanks to Michael Kubacki for catching this!
+
+        * Adjust the `device_path` parameter in a bunch of `BootServices`
+          calls. This used to take a `*mut c_void` parameter, since the device
+          path protocol was not implemented.
+          Since we have to bump the major version anyway, we use this to also
+          fix these argument-types to the correct device-path protocol type,
+          which has been implemented some time ago.
+
+        Contributions from: David Rheinsberg, Michael Kubacki
+
+        - Tübingen, 2020-04-24
+
+## CHANGES WITH 2.2.0:
+
+        * Provide `as_usize()` accessor for `efi::Status` types. This allows
+          accessing the raw underlying value of a status object.
+
+        * The project moved to its new home at: github.com/r-efi/r-efi
+
+        Contributions from: David Rheinsberg, Joe Richey
+
+        - Tübingen, 2020-04-16
+
+## CHANGES WITH 2.1.0:
+
+        * Add the graphics-output-protocol.
+
+        * Expose reserved fields in open structures, otherwise they cannot be
+          instantiated from outside the crate itself.
+
+        Contributions from: David Herrmann, Richard Wiedenhöft, Rob Bradford
+
+        - Tübingen, 2019-03-20
+
+## CHANGES WITH 2.0.0:
+
+        * Add a set of UEFI protocols, including simple-text-input,
+          file-protocol, simple-file-system, device-path, and more.
+
+        * Fix signature of `BootServices::allocate_pages`.
+
+        Contributions from: David Rheinsberg, Richard Wiedenhöft, Tom Gundersen
+
+        - Tübingen, 2019-03-01
+
+## CHANGES WITH 1.0.0:
+
+        * Enhance the basic UEFI type integration with the rust ecosystem. Add
+          `Debug`, `Eq`, `Ord`, ... derivations, provide converters to/from the
+          core library, and document the internal workings.
+
+        * Fix `Boolean` to use `newtype(u8)` to make it ABI compatible to UEFI.
+          This now accepts any byte value that UEFI accetps without any
+          conversion required.
+
+        Contributions from: Boris-Chengbiao Zhou, David Rheinsberg, Tom
+                            Gundersen
+
+        - Tübingen, 2019-02-14
+
+## CHANGES WITH 0.1.1:
+
+        * Feature gate examples to make `cargo test` work on non-UEFI systems
+          like CI.
+
+        Contributions from: David Herrmann
+
+        - Tübingen, 2018-12-10
+
+## CHANGES WITH 0.1.0:
+
+        * Initial release of r-efi.
+
+        Contributions from: David Herrmann
+
+        - Tübingen, 2018-12-10

data/rust-vendor/r-efi-5.3.0/README.md

@@ -0,0 +1,99 @@
+r-efi
+=====
+
+UEFI Reference Specification Protocol Constants and Definitions
+
+The r-efi project provides the protocol constants and definitions of the
+UEFI Reference Specification as native rust code. The scope of this project is
+limited to those protocol definitions. The protocols are not actually
+implemented. As such, this project serves as base for any UEFI application that
+needs to interact with UEFI, or implement (parts of) the UEFI specification.
+
+### Project
+
+ * **Website**: <https://github.com/r-efi/r-efi/wiki>
+ * **Bug Tracker**: <https://github.com/r-efi/r-efi/issues>
+
+### Requirements
+
+The requirements for this project are:
+
+ * `rustc >= 1.68.0`
+
+### Build
+
+To build this project, run:
+
+```sh
+cargo build
+```
+
+Available configuration options are:
+
+ * **native**: This feature-selector enables compilation of modules and
+               examples that require native UEFI targets. Those will not
+               compile on foreign targets and thus are guarded by this flag.
+
+##### Build via: official toolchains
+
+Starting with rust-version 1.68, rustup distributes pre-compiled toolchains for
+many UEFI targets. You can enumerate and install them via `rustup`. This
+example shows how to enumerate all available targets for your stable toolchain
+and then install the UEFI target for the `x86_64` architecture:
+
+```sh
+rustup target list --toolchain=stable
+rustup target add --toolchain=stable x86_64-unknown-uefi
+```
+
+This project can then be compiled directly for the selected target:
+
+```sh
+cargo +stable build \
+    --examples \
+    --features native \
+    --lib \
+    --target x86_64-unknown-uefi
+```
+
+##### Build via: cargo/rustc nightly with -Zbuild-std
+
+If no pre-compiled toolchains are available for your selected target, you can
+compile the project and the required parts of the standard library via the
+experimental `-Zbuild-std` feature of rustc. This requires a nightly compiler:
+
+```sh
+cargo +nightly build \
+    -Zbuild-std=core,compiler_builtins,alloc \
+    -Zbuild-std-features=compiler-builtins-mem \
+    --examples \
+    --features native \
+    --lib \
+    --target x86_64-unknown-uefi
+```
+
+##### Build via: foreign target
+
+The project can be built for non-UEFI targets via the standard rust toolchains.
+This allows non-UEFI targets to interact with UEFI systems or otherwise host
+UEFI operations. Furthermore, this allows running the foreign test-suite of
+this project as long as the target supports the full standard library:
+
+```sh
+cargo +stable build --all-targets
+cargo +stable test --all-targets
+```
+
+Note that the `native` feature must not be enabled for foreign targets as it
+will not compile on non-UEFI systems.
+
+### Repository:
+
+ - **web**:   <https://github.com/r-efi/r-efi>
+ - **https**: `https://github.com/r-efi/r-efi.git`
+ - **ssh**:   `git@github.com:r-efi/r-efi.git`
+
+### License:
+
+ - **MIT** OR **Apache-2.0** OR **LGPL-2.1-or-later**
+ - See AUTHORS file for details.

data/rust-vendor/r-efi-5.3.0/examples/freestanding.rs

@@ -0,0 +1,34 @@
+// Example: Freestanding
+//
+// This example is a plain UEFI application without any external requirements
+// but `core`. It immediately returns control to the caller upon execution,
+// yielding the exit code 0.
+//
+// The `main` function serves as entry-point. Depending on your
+// target-configuration, it must be exported with a pre-configured name so the
+// linker will correctly mark it as entry-point. The target configurations
+// shipped with upstream rust-lang use `efi_main` as symbol name.
+//
+// Additionally, a panic handler is provided. This is executed by rust on
+// panic. For simplicity, we simply end up in an infinite loop. For real
+// applications, this method should probably call into
+// `SystemTable->boot_services->exit()` to exit the UEFI application. Note,
+// however, that UEFI applications are likely to run in the same address space
+// as the entire firmware. Hence, halting the machine might be a viable
+// alternative. All that is out-of-scope for this example, though.
+//
+// Note that as of rust-1.31.0, all features used here are stabilized. No
+// unstable features are required, nor do we rely on nightly compilers.
+
+#![no_main]
+#![no_std]
+
+#[panic_handler]
+fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
+    loop {}
+}
+
+#[export_name = "efi_main"]
+pub extern "C" fn main(_h: *mut core::ffi::c_void, _st: *mut core::ffi::c_void) -> usize {
+    0
+}

data/rust-vendor/r-efi-5.3.0/examples/gop-query.rs

@@ -0,0 +1,188 @@
+// Example: Graphics Query
+//
+// This is a slightly more complex UEFI application than `hello-world`. It
+// locates the graphics-output-protocol, queries its current mode and prints
+// the current resolution to the UEFI console.
+//
+// This example should make everyone aware that UEFI programing in Rust really
+// asks for helper layers. While the C/FFI/Spec API can be used directly, it
+// is quite cumbersome. Especially the error handling is overly difficult.
+//
+// Nevertheless, this example shows how to find UEFI protocol and invoke
+// their member functions.
+//
+// Like all the other r-efi examples, it is a standalone example. That is, no
+// UTF-16 helpers are pulled in, nor any allocators or panic frameworks. For
+// real world scenarios, you really should choose such helpers.
+
+#![no_main]
+#![no_std]
+
+use r_efi::efi;
+
+#[panic_handler]
+fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
+    loop {}
+}
+
+fn fail(_r: efi::Status) -> ! {
+    panic!();
+}
+
+// A simple `itoa()`-ish function that takes a u32 and turns it into a UTF-16
+// string. It always prints exactly 10 characters, so leading zeroes are used
+// for small numbers.
+fn utoa(mut u: u32, a: &mut [u16]) {
+    for i in 0..10 {
+        a[9 - i] = 0x0030u16 + ((u % 10) as u16);
+        u = u / 10;
+    }
+}
+
+// A simple helper that takes two integers and prints them to the UEFI console
+// with a short prefix. It uses a UTF-16 buffer and fills in the numbers before
+// printing the entire buffer.
+fn print_xy(st: *mut efi::SystemTable, x: u32, y: u32) {
+    let mut s = [
+        0x0058u16, 0x0059u16, 0x003au16, //            "XY:"
+        0x0020u16, //                                  " "
+        0x0020u16, 0x0020u16, 0x0020u16, 0x0020u16, // "    "
+        0x0020u16, 0x0020u16, 0x0020u16, 0x0020u16, // "    "
+        0x0020u16, 0x0020u16, //                       "    "
+        0x0078u16, //                                  "x"
+        0x0020u16, 0x0020u16, 0x0020u16, 0x0020u16, // "    "
+        0x0020u16, 0x0020u16, 0x0020u16, 0x0020u16, // "    "
+        0x0020u16, 0x0020u16, //                       "    "
+        0x000au16, //                                  "\n"
+        0x0000u16, //                                  NUL
+    ];
+
+    utoa(x, &mut s[4..14]);
+    utoa(y, &mut s[15..25]);
+
+    unsafe {
+        let r = ((*(*st).con_out).output_string)((*st).con_out, s.as_ptr() as *mut efi::Char16);
+        if r.is_error() {
+            fail(r);
+        }
+    }
+}
+
+// This function locates singleton UEFI protocols. Those protocols do not
+// require to register listener handles, but are globally available to all
+// UEFI applications. It takes a GUID of the protocol to locate and returns
+// the protocol pointer on success.
+fn locate_singleton(
+    st: *mut efi::SystemTable,
+    guid: *const efi::Guid,
+) -> Result<*mut core::ffi::c_void, efi::Status> {
+    let mut interface: *mut core::ffi::c_void = core::ptr::null_mut();
+    let mut handles: *mut efi::Handle = core::ptr::null_mut();
+    let mut n_handles: usize = 0;
+    let mut r: efi::Status;
+
+    // Use `locate_handle_buffer()` to find all handles that support the
+    // specified protocol.
+    unsafe {
+        if (*st).hdr.revision < efi::SYSTEM_TABLE_REVISION_1_10 {
+            // We use `LocateHandleBuffer`, which was introduced in 1.10.
+            return Err(efi::Status::UNSUPPORTED);
+        }
+
+        let r = ((*(*st).boot_services).locate_handle_buffer)(
+            efi::BY_PROTOCOL,
+            guid as *mut _,
+            core::ptr::null_mut(),
+            &mut n_handles,
+            &mut handles,
+        );
+        match r {
+            efi::Status::SUCCESS => {}
+            efi::Status::NOT_FOUND => return Err(r),
+            efi::Status::OUT_OF_RESOURCES => return Err(r),
+            _ => panic!(),
+        };
+    }
+
+    // Now that we have all handles with the specified protocol, query it for
+    // the protocol interface. We loop here, even though every item should
+    // succeed. Lets be on the safe side.
+    // Secondly, we use `handle_protocol()` here, but really should be using
+    // `open_protocol()`. But for singleton protocols, this does not matter,
+    // so lets use the simple path for now.
+    unsafe {
+        r = efi::Status::NOT_FOUND;
+        for i in 0..n_handles {
+            r = ((*(*st).boot_services).handle_protocol)(
+                *handles.offset(core::convert::TryFrom::<usize>::try_from(i).unwrap()),
+                guid as *mut _,
+                &mut interface,
+            );
+            match r {
+                efi::Status::SUCCESS => break,
+                efi::Status::UNSUPPORTED => continue,
+                _ => panic!(),
+            };
+        }
+    }
+
+    // Free the allocated buffer memory of `handles`. This was allocated on the
+    // pool by `locate_handle_buffer()`.
+    unsafe {
+        let r = ((*(*st).boot_services).free_pool)(handles as *mut core::ffi::c_void);
+        assert!(!r.is_error());
+    }
+
+    // In case we found nothing, return `NOT_FOUND`, otherwise return the
+    // interface identifier.
+    match r {
+        efi::Status::SUCCESS => Ok(interface),
+        _ => Err(efi::Status::NOT_FOUND),
+    }
+}
+
+// A simple helper that queries the current mode of the GraphicsOutputProtocol
+// and returns the x and y dimensions on success.
+fn query_gop(
+    gop: *mut efi::protocols::graphics_output::Protocol,
+) -> Result<(u32, u32), efi::Status> {
+    let mut info: *mut efi::protocols::graphics_output::ModeInformation = core::ptr::null_mut();
+    let mut z_info: usize = 0;
+
+    unsafe {
+        // We could just look at `gop->mode->info`, but lets query the mode
+        // instead to show how to query other modes than the active one.
+        let r = ((*gop).query_mode)(gop, (*(*gop).mode).mode, &mut z_info, &mut info);
+        match r {
+            efi::Status::SUCCESS => {}
+            efi::Status::DEVICE_ERROR => return Err(r),
+            _ => panic!(),
+        };
+        if z_info < core::mem::size_of_val(&*info) {
+            return Err(efi::Status::UNSUPPORTED);
+        }
+
+        Ok(((*info).horizontal_resolution, (*info).vertical_resolution))
+    }
+}
+
+// This is the UEFI application entrypoint. We use it to locate the GOP
+// pointer, query the current mode, and then print it to the system console.
+#[export_name = "efi_main"]
+pub extern "C" fn main(_h: efi::Handle, st: *mut efi::SystemTable) -> efi::Status {
+    let r = locate_singleton(st, &efi::protocols::graphics_output::PROTOCOL_GUID);
+    let gop = match r {
+        Ok(v) => v,
+        Err(r) => fail(r),
+    };
+
+    let r = query_gop(gop as _);
+    let v = match r {
+        Ok(v) => v,
+        Err(r) => fail(r),
+    };
+
+    print_xy(st, v.0, v.1);
+
+    efi::Status::SUCCESS
+}

data/rust-vendor/r-efi-5.3.0/examples/hello-world.rs

@@ -0,0 +1,55 @@
+// Example: Hello World!
+//
+// This is an example UEFI application that prints "Hello World!", then waits
+// for key input before it exits. It serves as base example how to write UEFI
+// applications without any helper modules other than the UEFI protocol
+// definitions.
+//
+// This example builds upon the `freestanding.rs` example, using the same setup
+// and rust integration. See there for details on the panic-handler and entry
+// point configuration.
+//
+// Note that UEFI uses UTF-16 strings. Since rust literals are UTF-8, we have
+// to use an open-coded, zero-terminated, UTF-16 array as argument to
+// `output_string()`. Similarly to the panic handler, real applications should
+// rather use UTF-16 modules.
+
+#![no_main]
+#![no_std]
+
+use r_efi::efi;
+
+#[panic_handler]
+fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
+    loop {}
+}
+
+#[export_name = "efi_main"]
+pub extern "C" fn main(_h: efi::Handle, st: *mut efi::SystemTable) -> efi::Status {
+    let s = [
+        0x0048u16, 0x0065u16, 0x006cu16, 0x006cu16, 0x006fu16, // "Hello"
+        0x0020u16, //                                             " "
+        0x0057u16, 0x006fu16, 0x0072u16, 0x006cu16, 0x0064u16, // "World"
+        0x0021u16, //                                             "!"
+        0x000au16, //                                             "\n"
+        0x0000u16, //                                             NUL
+    ];
+
+    // Print "Hello World!".
+    let r =
+        unsafe { ((*(*st).con_out).output_string)((*st).con_out, s.as_ptr() as *mut efi::Char16) };
+    if r.is_error() {
+        return r;
+    }
+
+    // Wait for key input, by waiting on the `wait_for_key` event hook.
+    let r = unsafe {
+        let mut x: usize = 0;
+        ((*(*st).boot_services).wait_for_event)(1, &mut (*(*st).con_in).wait_for_key, &mut x)
+    };
+    if r.is_error() {
+        return r;
+    }
+
+    efi::Status::SUCCESS
+}