Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/device_paths.html b/concepts/device_paths.html
new file mode 100644
index 000000000..029fd2215
--- /dev/null
+++ b/concepts/device_paths.html
@@ -0,0 +1,191 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Boot Stages
+A UEFI system goes through several distinct phases during the boot process.
+-
+
- Platform Initialization. This early-boot phase is mostly outside
+the scope of the
ueficrate. It is described by the UEFI Platform +Initialization Specification, which is separate from the main UEFI +Specification.
+ - Boot Services. This is when UEFI drivers and applications are loaded.
+Functions in both the
bootmodule andruntimemodule can be used. +This stage typically culminates in running a bootloader that loads an +operating system. The stage ends whenboot::exit_boot_servicesis called, +putting the system in Runtime mode.
+ - Runtime. This stage is typically active when running an operating system
+such as Linux or Windows. UEFI functionality is much more limited in the
+Runtime mode. Functions in the
bootmodule can no longer be used, but +functions in theruntimemodule are still available. Once the system is +in Runtime mode, it cannot return to the Boot Services stage until after a +system reset.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/gpt.html b/concepts/gpt.html
new file mode 100644
index 000000000..573a76da1
--- /dev/null
+++ b/concepts/gpt.html
@@ -0,0 +1,215 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Device Paths
+A device path is a very flexible packed data structure for storing paths +to many kinds of device. Note that these device paths are not the same +thing as file system paths, although they can include file system +paths. Like handles, device paths can be used to uniquely identify +resources such as consoles, mice, disks, partitions, and more. Unlike +handles, which are essentially opaque pointers, device paths are +variable-length structures that contain parseable information.
+The uefi::proto::device_path module documentation describes the
+details of how device paths are encoded.
Device paths can also be converted to and from human-readable text +representations that look like this:
+PciRoot(0x0)/Pci(0x1F,0x2)/Sata(0x0,0xFFFF,0x0)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)
+See uefi::proto::device_path::text for details.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/guid.html b/concepts/guid.html
new file mode 100644
index 000000000..44673b610
--- /dev/null
+++ b/concepts/guid.html
@@ -0,0 +1,187 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GPT
+GPT is short for GUID Partition Table. It's a more modern +alternative to MBR (master boot record) partition tables. Although it's +defined in the UEFI specification, it often gets used on non-UEFI +systems too. There are a couple big advantages of using GPT over MBR:
+-
+
- It has a relatively clear and precise standard, unlike MBR where +implementations often just try to match what other implementations do. +
- It supports very large disks and very large numbers of partitions. +
A GPT disk contains a primary header near the beginning of the disk, +followed by a partition entry array. The header and partition entry +array have a secondary copy at the end of the disk for redundancy. The +partition entry arrays contain structures that describe each partition, +including a GUID to identify the individual partition, a partition type +GUID to indicate the purpose of the partition, and start/end block +addresses. In between the entry arrays is the actual partition data.
+System partition
+The system partition is UEFI's version of a bootable partition. The
+system partition is sometimes called the ESP, or EFI System
+Partition. It is identified by a partition type of
+c12a7328-f81f-11d2-ba4b-00a0c93ec93b. The system partition always
+contains a FAT file system. There are various standardized paths that
+can exist within the file system, and of particular importance are the
+boot files. These are the files that UEFI will try to boot from by
+default (in the absence of a different boot configuration set through
+special UEFI variables).
Boot files are under \EFI\BOOT, and are named BOOT<ARCH>.efi, where
+<ARCH> is a short architecture name.
| Architecture | File name |
|---|---|
| Intel 32-bit | BOOTIA32.EFI |
| X86_64 | BOOTX64.EFI |
| Itanium | BOOTIA64.EFI |
| AArch32 | BOOTARM.EFI |
| AArch64 | BOOTAA64.EFI |
| RISC-V 32-bit | BOOTRISCV32.EFI |
| RISC-V 64-bit | BOOTRISCV64.EFI |
| RISC-V 128-bit | BOOTRISCV128.EFI |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/handles_and_protocols.html b/concepts/handles_and_protocols.html
new file mode 100644
index 000000000..f403f063e
--- /dev/null
+++ b/concepts/handles_and_protocols.html
@@ -0,0 +1,201 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GUID
+GUID is short for Globally Unique Identifier. A GUID is always 16 bytes,
+and has a standard string representation format that looks like this:
+313b0d7c-fed4-4de7-99ed-2fe48874a410. The details of the GUID format
+aren't too important, but be aware that the actual byte representation
+is not in the same order as the string representation because the first
+three fields are little-endian. For the most part you can treat GUIDs as
+opaque identifiers.
The UEFI specification uses GUIDs all over the place. GUIDs are used to
+identify protocols, disk partitions, variable groupings, and much
+more. In uefi-rs, GUIDs are represented by the Guid type.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/introduction.html b/concepts/introduction.html
new file mode 100644
index 000000000..a537d28ab
--- /dev/null
+++ b/concepts/introduction.html
@@ -0,0 +1,183 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Handles and Protocols
+Handles and protocols are at the core of what makes UEFI +extensible. Together they are the mechanism by which UEFI can adapt to a +wide array of hardware and boot conditions, while still providing a +consistent interface to drivers and applications.
+Handles
+Handles represent resources. A resource might be a physical device such +as a disk drive or USB device, or something less tangible like a loaded +executable.
+A Handle is an opaque pointer, so you can't do anything with it +directly. To operate on a handle you have to open a protocol.
+Protocols
+Protocols are interfaces that provide functions to interact with a +resource. For example, the BlockIO protocol provides functions to read +and write to block IO devices.
+Protocols are only available during the Boot Services stage; you can't +access them during the Runtime stage.
+The UEFI Specification defines a very large number of protocols. Because
+protocols are inherently very diverse, the best place to learn about
+individual protocols is the UEFI Specification. There are many
+chapters covering various protocols. Not all of these protocols are
+wrapped by uefi-rs yet (contributions welcome!) but many of the most
+commonly useful ones are.
See the Using Protocols how-to for details of the uefi-rs API for
+interacting with protocols.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/tables.html b/concepts/tables.html
new file mode 100644
index 000000000..46bf95cec
--- /dev/null
+++ b/concepts/tables.html
@@ -0,0 +1,204 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Concepts
+The canonical source of information about UEFI is the UEFI specification.
+The specification is huge (currently nearly 2500 pages). Much of that
+content relates to optional services, understanding of which is not
+critical to understanding UEFI as a whole. This chapter summarizes some
+of the more important UEFI concepts and links to the relevant uefi-rs
+documentation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/variables.html b/concepts/variables.html
new file mode 100644
index 000000000..8cc27cd40
--- /dev/null
+++ b/concepts/variables.html
@@ -0,0 +1,203 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Tables
+UEFI has a few table structures. These tables are how you get access to UEFI
+services. In the specification and C API, EFI_SYSTEM_TABLE is the top-level
+table that provides access to the other tables, EFI_BOOT_SERVICES and
+EFI_RUNTIME_SERVICES.
In the uefi crate, these tables are modeled as modules rather than structs. The
+functions in each module make use of a global pointer to the system table that
+is set automatically by the entry macro.
-
+
-
+
+uefi::system(EFI_SYSTEM_TABLEin the specification) provides access to +system information such as the firmware vendor and version. It can also be used +to access stdout/stderr/stdin.
+ -
+
+uefi::boot(EFI_BOOT_SERVICESin the specification) provides access to a +wide array of services such as memory allocation, executable loading, and +optional extension interfaces called protocols. Functions in this module can +only be used while in the Boot Services stage. Afterexit_boot_serviceshas +been called, these functions will panic.
+ -
+
+uefi::runtime(EFI_RUNTIME_SERVICESin the specification) provides access +to a fairly limited set of services, including variable storage, system time, +and virtual-memory mapping. Functions in this module are accessible during both +the Boot Services and Runtime stages.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/css/chrome.css b/css/chrome.css
new file mode 100644
index 000000000..10fa4b365
--- /dev/null
+++ b/css/chrome.css
@@ -0,0 +1,534 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+@import 'variables.css';
+
+::-webkit-scrollbar {
+ background: var(--bg);
+}
+::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+html {
+ scrollbar-color: var(--scrollbar) var(--bg);
+}
+#searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+ color: var(--links);
+}
+
+/* Menu Bar */
+
+#menu-bar,
+#menu-bar-hover-placeholder {
+ z-index: 101;
+ margin: auto calc(0px - var(--page-padding));
+}
+#menu-bar {
+ position: relative;
+ display: flex;
+ flex-wrap: wrap;
+ background-color: var(--bg);
+ border-bottom-color: var(--bg);
+ border-bottom-width: 1px;
+ border-bottom-style: solid;
+}
+#menu-bar.sticky,
+.js #menu-bar-hover-placeholder:hover + #menu-bar,
+.js #menu-bar:hover,
+.js.sidebar-visible #menu-bar {
+ position: -webkit-sticky;
+ position: sticky;
+ top: 0 !important;
+}
+#menu-bar-hover-placeholder {
+ position: sticky;
+ position: -webkit-sticky;
+ top: 0;
+ height: var(--menu-bar-height);
+}
+#menu-bar.bordered {
+ border-bottom-color: var(--table-border-color);
+}
+#menu-bar i, #menu-bar .icon-button {
+ position: relative;
+ padding: 0 8px;
+ z-index: 10;
+ line-height: var(--menu-bar-height);
+ cursor: pointer;
+ transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+ #menu-bar i, #menu-bar .icon-button {
+ padding: 0 5px;
+ }
+}
+
+.icon-button {
+ border: none;
+ background: none;
+ padding: 0;
+ color: inherit;
+}
+.icon-button i {
+ margin: 0;
+}
+
+.right-buttons {
+ margin: 0 15px;
+}
+.right-buttons a {
+ text-decoration: none;
+}
+
+.left-buttons {
+ display: flex;
+ margin: 0 5px;
+}
+.no-js .left-buttons {
+ display: none;
+}
+
+.menu-title {
+ display: inline-block;
+ font-weight: 200;
+ font-size: 2.4rem;
+ line-height: var(--menu-bar-height);
+ text-align: center;
+ margin: 0;
+ flex: 1;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+.js .menu-title {
+ cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a i {
+ color: var(--icons);
+}
+
+.menu-bar i:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters i:hover {
+ color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+
+ position: fixed;
+ top: 0;
+ bottom: 0;
+ margin: 0;
+ max-width: 150px;
+ min-width: 90px;
+
+ display: flex;
+ justify-content: center;
+ align-content: center;
+ flex-direction: column;
+
+ transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+ text-decoration: none;
+ background-color: var(--theme-hover);
+ transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+ margin-top: 50px;
+ display: none;
+}
+
+.mobile-nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+ width: 90px;
+ border-radius: 5px;
+ background-color: var(--sidebar-bg);
+}
+
+.previous {
+ float: left;
+}
+
+.next {
+ float: right;
+ right: var(--page-padding);
+}
+
+@media only screen and (max-width: 1080px) {
+ .nav-wide-wrapper { display: none; }
+ .nav-wrapper { display: block; }
+}
+
+@media only screen and (max-width: 1380px) {
+ .sidebar-visible .nav-wide-wrapper { display: none; }
+ .sidebar-visible .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+ display: inline;
+ padding: 0.1em 0.3em;
+ border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+ color: var(--inline-code-color);
+ overflow-x: initial;
+}
+
+a:hover > .hljs {
+ text-decoration: underline;
+}
+
+pre {
+ position: relative;
+}
+pre > .buttons {
+ position: absolute;
+ z-index: 100;
+ right: 0px;
+ top: 2px;
+ margin: 0px;
+ padding: 2px 0px;
+
+ color: var(--sidebar-fg);
+ cursor: pointer;
+ visibility: hidden;
+ opacity: 0;
+ transition: visibility 0.1s linear, opacity 0.1s linear;
+}
+pre:hover > .buttons {
+ visibility: visible;
+ opacity: 1
+}
+pre > .buttons :hover {
+ color: var(--sidebar-active);
+ border-color: var(--icons-hover);
+ background-color: var(--theme-hover);
+}
+pre > .buttons i {
+ margin-left: 8px;
+}
+pre > .buttons button {
+ cursor: inherit;
+ margin: 0px 5px;
+ padding: 3px 5px;
+ font-size: 14px;
+
+ border-style: solid;
+ border-width: 1px;
+ border-radius: 4px;
+ border-color: var(--icons);
+ background-color: var(--theme-popup-bg);
+ transition: 100ms;
+ transition-property: color,border-color,background-color;
+ color: var(--icons);
+}
+@media (pointer: coarse) {
+ pre > .buttons button {
+ /* On mobile, make it easier to tap buttons. */
+ padding: 0.3rem 1rem;
+ }
+}
+pre > code {
+ padding: 1rem;
+}
+
+/* FIXME: ACE editors overlap their buttons because ACE does absolute
+ positioning within the code block which breaks padding. The only solution I
+ can think of is to move the padding to the outer pre tag (or insert a div
+ wrapper), but that would require fixing a whole bunch of CSS rules.
+*/
+.hljs.ace_editor {
+ padding: 0rem 0rem;
+}
+
+pre > .result {
+ margin-top: 10px;
+}
+
+/* Search */
+
+#searchresults a {
+ text-decoration: none;
+}
+
+mark {
+ border-radius: 2px;
+ padding: 0 3px 1px 3px;
+ margin: 0 -3px -1px -3px;
+ background-color: var(--search-mark-bg);
+ transition: background-color 300ms linear;
+ cursor: pointer;
+}
+
+mark.fade-out {
+ background-color: rgba(0,0,0,0) !important;
+ cursor: auto;
+}
+
+.searchbar-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+
+#searchbar {
+ width: 100%;
+ margin: 5px auto 0px auto;
+ padding: 10px 16px;
+ transition: box-shadow 300ms ease-in-out;
+ border: 1px solid var(--searchbar-border-color);
+ border-radius: 3px;
+ background-color: var(--searchbar-bg);
+ color: var(--searchbar-fg);
+}
+#searchbar:focus,
+#searchbar.active {
+ box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+ font-weight: bold;
+ font-size: 1em;
+ padding: 18px 0 0 5px;
+ color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+ border-bottom: 1px dashed var(--searchresults-border-color);
+}
+
+ul#searchresults {
+ list-style: none;
+ padding-left: 20px;
+}
+ul#searchresults li {
+ margin: 10px 0px;
+ padding: 2px;
+ border-radius: 2px;
+}
+ul#searchresults li.focus {
+ background-color: var(--searchresults-li-bg);
+}
+ul#searchresults span.teaser {
+ display: block;
+ clear: both;
+ margin: 5px 0 0 20px;
+ font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+ font-weight: bold;
+ font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+ position: fixed;
+ left: 0;
+ top: 0;
+ bottom: 0;
+ width: var(--sidebar-width);
+ font-size: 0.875em;
+ box-sizing: border-box;
+ -webkit-overflow-scrolling: touch;
+ overscroll-behavior-y: contain;
+ background-color: var(--sidebar-bg);
+ color: var(--sidebar-fg);
+}
+.sidebar-resizing {
+ -moz-user-select: none;
+ -webkit-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+}
+.js:not(.sidebar-resizing) .sidebar {
+ transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+ line-height: 2em;
+}
+.sidebar .sidebar-scrollbox {
+ overflow-y: auto;
+ position: absolute;
+ top: 0;
+ bottom: 0;
+ left: 0;
+ right: 0;
+ padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+ position: absolute;
+ cursor: col-resize;
+ width: 0;
+ right: 0;
+ top: 0;
+ bottom: 0;
+}
+.js .sidebar .sidebar-resize-handle {
+ cursor: col-resize;
+ width: 5px;
+}
+.sidebar-hidden .sidebar {
+ transform: translateX(calc(0px - var(--sidebar-width)));
+}
+.sidebar::-webkit-scrollbar {
+ background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+
+.sidebar-visible .page-wrapper {
+ transform: translateX(var(--sidebar-width));
+}
+@media only screen and (min-width: 620px) {
+ .sidebar-visible .page-wrapper {
+ transform: none;
+ margin-left: var(--sidebar-width);
+ }
+}
+
+.chapter {
+ list-style: none outside none;
+ padding-left: 0;
+ line-height: 2.2em;
+}
+
+.chapter ol {
+ width: 100%;
+}
+
+.chapter li {
+ display: flex;
+ color: var(--sidebar-non-existant);
+}
+.chapter li a {
+ display: block;
+ padding: 0;
+ text-decoration: none;
+ color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+ color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+ color: var(--sidebar-active);
+}
+
+.chapter li > a.toggle {
+ cursor: pointer;
+ display: block;
+ margin-left: auto;
+ padding: 0 10px;
+ user-select: none;
+ opacity: 0.68;
+}
+
+.chapter li > a.toggle div {
+ transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) + li > ol {
+ display: none;
+}
+
+.chapter li.chapter-item {
+ line-height: 1.5em;
+ margin-top: 0.6em;
+}
+
+.chapter li.expanded > a.toggle div {
+ transform: rotate(90deg);
+}
+
+.spacer {
+ width: 100%;
+ height: 3px;
+ margin: 5px 0px;
+}
+.chapter .spacer {
+ background-color: var(--sidebar-spacer);
+}
+
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+ .chapter li a { padding: 5px 0; }
+ .spacer { margin: 10px 0; }
+}
+
+.section {
+ list-style: none outside none;
+ padding-left: 20px;
+ line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+ position: absolute;
+ left: 10px;
+ top: var(--menu-bar-height);
+ z-index: 1000;
+ border-radius: 4px;
+ font-size: 0.7em;
+ color: var(--fg);
+ background: var(--theme-popup-bg);
+ border: 1px solid var(--theme-popup-border);
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: none;
+}
+.theme-popup .default {
+ color: var(--icons);
+}
+.theme-popup .theme {
+ width: 100%;
+ border: 0;
+ margin: 0;
+ padding: 2px 10px;
+ line-height: 25px;
+ white-space: nowrap;
+ text-align: left;
+ cursor: pointer;
+ color: inherit;
+ background: inherit;
+ font-size: inherit;
+}
+.theme-popup .theme:hover {
+ background-color: var(--theme-hover);
+}
+.theme-popup .theme:hover:first-child,
+.theme-popup .theme:hover:last-child {
+ border-top-left-radius: inherit;
+ border-top-right-radius: inherit;
+}
diff --git a/css/general.css b/css/general.css
new file mode 100644
index 000000000..0e4f07a50
--- /dev/null
+++ b/css/general.css
@@ -0,0 +1,191 @@
+/* Base styles and content styles */
+
+@import 'variables.css';
+
+:root {
+ /* Browser default font-size is 16px, this way 1 rem = 10px */
+ font-size: 62.5%;
+}
+
+html {
+ font-family: "Open Sans", sans-serif;
+ color: var(--fg);
+ background-color: var(--bg);
+ text-size-adjust: none;
+ -webkit-text-size-adjust: none;
+}
+
+body {
+ margin: 0;
+ font-size: 1.6rem;
+ overflow-x: hidden;
+}
+
+code {
+ font-family: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace !important;
+ font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */
+}
+
+/* make long words/inline code not x overflow */
+main {
+ overflow-wrap: break-word;
+}
+
+/* make wide tables scroll if they overflow */
+.table-wrapper {
+ overflow-x: auto;
+}
+
+/* Don't change font size in headers. */
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+ font-size: unset;
+}
+
+.left { float: left; }
+.right { float: right; }
+.boring { opacity: 0.6; }
+.hide-boring .boring { display: none; }
+.hidden { display: none !important; }
+
+h2, h3 { margin-top: 2.5em; }
+h4, h5 { margin-top: 2em; }
+
+.header + .header h3,
+.header + .header h4,
+.header + .header h5 {
+ margin-top: 1em;
+}
+
+h1:target::before,
+h2:target::before,
+h3:target::before,
+h4:target::before,
+h5:target::before,
+h6:target::before {
+ display: inline-block;
+ content: "»";
+ margin-left: -30px;
+ width: 30px;
+}
+
+/* This is broken on Safari as of version 14, but is fixed
+ in Safari Technology Preview 117 which I think will be Safari 14.2.
+ https://bugs.webkit.org/show_bug.cgi?id=218076
+*/
+:target {
+ scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
+}
+
+.page {
+ outline: 0;
+ padding: 0 var(--page-padding);
+ margin-top: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
+}
+.page-wrapper {
+ box-sizing: border-box;
+}
+.js:not(.sidebar-resizing) .page-wrapper {
+ transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+
+.content {
+ overflow-y: auto;
+ padding: 0 5px 50px 5px;
+}
+.content main {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+.content p { line-height: 1.45em; }
+.content ol { line-height: 1.45em; }
+.content ul { line-height: 1.45em; }
+.content a { text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content img, .content video { max-width: 100%; }
+.content .header:link,
+.content .header:visited {
+ color: var(--fg);
+}
+.content .header:link,
+.content .header:visited:hover {
+ text-decoration: none;
+}
+
+table {
+ margin: 0 auto;
+ border-collapse: collapse;
+}
+table td {
+ padding: 3px 20px;
+ border: 1px var(--table-border-color) solid;
+}
+table thead {
+ background: var(--table-header-bg);
+}
+table thead td {
+ font-weight: 700;
+ border: none;
+}
+table thead th {
+ padding: 3px 20px;
+}
+table thead tr {
+ border: 1px var(--table-header-bg) solid;
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+ background: var(--table-alternate-bg);
+}
+
+
+blockquote {
+ margin: 20px 0;
+ padding: 0 20px;
+ color: var(--fg);
+ background-color: var(--quote-bg);
+ border-top: .1em solid var(--quote-border);
+ border-bottom: .1em solid var(--quote-border);
+}
+
+
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+ margin-top: 2em;
+}
+.footnote-definition {
+ font-size: 0.9em;
+ margin: 0.5em 0;
+}
+.footnote-definition p {
+ display: inline;
+}
+
+.tooltiptext {
+ position: absolute;
+ visibility: hidden;
+ color: #fff;
+ background-color: #333;
+ transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
+ left: -8px; /* Half of the width of the icon */
+ top: -35px;
+ font-size: 0.8em;
+ text-align: center;
+ border-radius: 6px;
+ padding: 5px 8px;
+ margin: 5px;
+ z-index: 1000;
+}
+.tooltipped .tooltiptext {
+ visibility: visible;
+}
+
+.chapter li.part-title {
+ color: var(--sidebar-fg);
+ margin: 5px 0px;
+ font-weight: bold;
+}
+
+.result-no-output {
+ font-style: italic;
+}
diff --git a/css/print.css b/css/print.css
new file mode 100644
index 000000000..5e690f755
--- /dev/null
+++ b/css/print.css
@@ -0,0 +1,54 @@
+
+#sidebar,
+#menu-bar,
+.nav-chapters,
+.mobile-nav-chapters {
+ display: none;
+}
+
+#page-wrapper.page-wrapper {
+ transform: none;
+ margin-left: 0px;
+ overflow-y: initial;
+}
+
+#content {
+ max-width: none;
+ margin: 0;
+ padding: 0;
+}
+
+.page {
+ overflow-y: initial;
+}
+
+code {
+ background-color: #666666;
+ border-radius: 5px;
+
+ /* Force background to be printed in Chrome */
+ -webkit-print-color-adjust: exact;
+}
+
+pre > .buttons {
+ z-index: 2;
+}
+
+a, a:visited, a:active, a:hover {
+ color: #4183c4;
+ text-decoration: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ page-break-inside: avoid;
+ page-break-after: avoid;
+}
+
+pre, code {
+ page-break-inside: avoid;
+ white-space: pre-wrap;
+}
+
+.fa {
+ display: none !important;
+}
diff --git a/css/variables.css b/css/variables.css
new file mode 100644
index 000000000..56b634bc3
--- /dev/null
+++ b/css/variables.css
@@ -0,0 +1,253 @@
+
+/* Globals */
+
+:root {
+ --sidebar-width: 300px;
+ --page-padding: 15px;
+ --content-max-width: 750px;
+ --menu-bar-height: 50px;
+}
+
+/* Themes */
+
+.ayu {
+ --bg: hsl(210, 25%, 8%);
+ --fg: #c5c5c5;
+
+ --sidebar-bg: #14191f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #5c6773;
+ --sidebar-active: #ffb454;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #0096cf;
+
+ --inline-code-color: #ffb454;
+
+ --theme-popup-bg: #14191f;
+ --theme-popup-border: #5c6773;
+ --theme-hover: #191f26;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(210, 25%, 13%);
+ --table-header-bg: hsl(210, 25%, 28%);
+ --table-alternate-bg: hsl(210, 25%, 11%);
+
+ --searchbar-border-color: #848484;
+ --searchbar-bg: #424242;
+ --searchbar-fg: #fff;
+ --searchbar-shadow-color: #d4c89f;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #252932;
+ --search-mark-bg: #e3b171;
+}
+
+.coal {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+}
+
+.light {
+ --bg: hsl(0, 0%, 100%);
+ --fg: hsl(0, 0%, 0%);
+
+ --sidebar-bg: #fafafa;
+ --sidebar-fg: hsl(0, 0%, 0%);
+ --sidebar-non-existant: #aaaaaa;
+ --sidebar-active: #1f1fff;
+ --sidebar-spacer: #f4f4f4;
+
+ --scrollbar: #8F8F8F;
+
+ --icons: #747474;
+ --icons-hover: #000000;
+
+ --links: #20609f;
+
+ --inline-code-color: #301900;
+
+ --theme-popup-bg: #fafafa;
+ --theme-popup-border: #cccccc;
+ --theme-hover: #e6e6e6;
+
+ --quote-bg: hsl(197, 37%, 96%);
+ --quote-border: hsl(197, 37%, 91%);
+
+ --table-border-color: hsl(0, 0%, 95%);
+ --table-header-bg: hsl(0, 0%, 80%);
+ --table-alternate-bg: hsl(0, 0%, 97%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #e4f2fe;
+ --search-mark-bg: #a2cff5;
+}
+
+.navy {
+ --bg: hsl(226, 23%, 11%);
+ --fg: #bcbdd0;
+
+ --sidebar-bg: #282d3f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505274;
+ --sidebar-active: #2b79a2;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #161923;
+ --theme-popup-border: #737480;
+ --theme-hover: #282e40;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(226, 23%, 16%);
+ --table-header-bg: hsl(226, 23%, 31%);
+ --table-alternate-bg: hsl(226, 23%, 14%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #aeaec6;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #5f5f71;
+ --searchresults-border-color: #5c5c68;
+ --searchresults-li-bg: #242430;
+ --search-mark-bg: #a2cff5;
+}
+
+.rust {
+ --bg: hsl(60, 9%, 87%);
+ --fg: #262625;
+
+ --sidebar-bg: #3b2e2a;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #e69f67;
+ --sidebar-spacer: #45373a;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #262625;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #6e6b5e;
+
+ --theme-popup-bg: #e1e1db;
+ --theme-popup-border: #b38f6b;
+ --theme-hover: #99908a;
+
+ --quote-bg: hsl(60, 5%, 75%);
+ --quote-border: hsl(60, 5%, 70%);
+
+ --table-border-color: hsl(60, 9%, 82%);
+ --table-header-bg: #b3a497;
+ --table-alternate-bg: hsl(60, 9%, 84%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #dec2a2;
+ --search-mark-bg: #e69f67;
+}
+
+@media (prefers-color-scheme: dark) {
+ .light.no-js {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+ }
+}
diff --git a/elasticlunr.min.js b/elasticlunr.min.js
new file mode 100644
index 000000000..94b20dd2e
--- /dev/null
+++ b/elasticlunr.min.js
@@ -0,0 +1,10 @@
+/**
+ * elasticlunr - http://weixsong.github.io
+ * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5
+ *
+ * Copyright (C) 2017 Oliver Nightingale
+ * Copyright (C) 2017 Wei Song
+ * MIT Licensed
+ * @license
+ */
+!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Variables
+UEFI provides fairly flexible key/value variable storage.
+Each variable is identified by a key consisting of a UCS-2 +null-terminated name plus a vendor GUID. The vendor GUID serves as a +namespace for variables so that different vendors don't accidentally +overwrite or misinterpret another vendor's variable if they happen to +have the same name.
+The data stored in each variable is an arbitrary byte array.
+Attributes
+Each variable has attributes (represented as bit flags) associated with +it that affect how it is stored and how it can be accessed.
+If the BOOTSERVICE_ACCESS and RUNTIME_ACCESS bits are set, the
+variable can be accessed during both the Boot Services and Runtime
+stages. If only BOOTSERVICE_ACCESS is set then the variable can
+neither be read nor written to after exiting boot services.
Another important attribute is the NON_VOLATILE bit. If this bit is
+not set, the variable will be stored in normal memory and will not
+persist across a power cycle. If this bit is set, the variable will be
+stored in special non-volatile memory. You should be careful about
+writing variables of this type, because the non-volatile storage can be
+very limited in size. There have been cases where a vendor's poor UEFI
+implementation caused the machine not too boot once the storage became
+too full. Even figuring out how much space is in use can be tricky due
+to deletion being implemented via garbage collection. Matthew Garret's
+article "Dealing with UEFI non-volatile memory quirks" has more details.
Most of the other attributes relate to authenticated variables, which +can be used to prevent changes to a variable by unauthorized programs.
+ +":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/how_to/drawing.html b/how_to/drawing.html
new file mode 100644
index 000000000..505ab123f
--- /dev/null
+++ b/how_to/drawing.html
@@ -0,0 +1,394 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Building drivers
+There are three types of UEFI images:
+-
+
- Application +
- Boot service driver +
- Runtime driver +
By default, Rust's UEFI targets produce applications. This can be
+changed by passing a subsystem linker flag in rustflags and setting the
+value to efi_boot_service_driver or efi_runtime_driver.
Example:
+# In .cargo/config.toml:
+[build]
+rustflags = ["-C", "link-args=/subsystem:efi_runtime_driver"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/how_to/introduction.html b/how_to/introduction.html
new file mode 100644
index 000000000..f24f2bf33
--- /dev/null
+++ b/how_to/introduction.html
@@ -0,0 +1,178 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Drawing to the Screen
+This example shows how to draw to the screen using the graphics output protocol. +The code will a Sierpiński triangle using the "chaos game" method.
+
The core abstraction used here is a linear buffer:
++#![allow(unused)] +fn main() { +struct Buffer { + width: usize, + height: usize, + pixels: Vec<BltPixel>, +} + +impl Buffer { + /// Create a new `Buffer`. + fn new(width: usize, height: usize) -> Self { + Buffer { + width, + height, + pixels: vec![BltPixel::new(0, 0, 0); width * height], + } + } + + /// Get a single pixel. + fn pixel(&mut self, x: usize, y: usize) -> Option<&mut BltPixel> { + self.pixels.get_mut(y * self.width + x) + } + + /// Blit the buffer to the framebuffer. + fn blit(&self, gop: &mut GraphicsOutput) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::Full, + dest: (0, 0), + dims: (self.width, self.height), + }) + } + + /// Update only a pixel to the framebuffer. + fn blit_pixel( + &self, + gop: &mut GraphicsOutput, + coords: (usize, usize), + ) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::SubRectangle { + coords, + px_stride: self.width, + }, + dest: coords, + dims: (1, 1), + }) + } +} +} +
This Buffer type stores a Vec of BltPixels, which are BGRX
+32-bit pixels (8 bites each for blue, green, and red, followed by 8
+unused bits of padding). We use the pixel method to alter a single
+pixel at a time. This is often not an efficient method; for more complex
+graphics you could use a crate like embedded-graphics.
The Buffer::blit method calls the graphics output protocol's blt
+method to copy the buffer to the screen.
Most of the rest of the code is just implementing the algorithm for +drawing the fractal. Here's the full example:
++#![no_main] +#![no_std] + +extern crate alloc; + +use alloc::vec; +use alloc::vec::Vec; +use core::mem; +use uefi::prelude::*; +use uefi::proto::console::gop::{BltOp, BltPixel, BltRegion, GraphicsOutput}; +use uefi::proto::rng::Rng; +use uefi::{boot, Result}; + +#[derive(Clone, Copy)] +struct Point { + x: f32, + y: f32, +} + +impl Point { + fn new(x: f32, y: f32) -> Self { + Self { x, y } + } +} + +struct Buffer { + width: usize, + height: usize, + pixels: Vec<BltPixel>, +} + +impl Buffer { + /// Create a new `Buffer`. + fn new(width: usize, height: usize) -> Self { + Buffer { + width, + height, + pixels: vec![BltPixel::new(0, 0, 0); width * height], + } + } + + /// Get a single pixel. + fn pixel(&mut self, x: usize, y: usize) -> Option<&mut BltPixel> { + self.pixels.get_mut(y * self.width + x) + } + + /// Blit the buffer to the framebuffer. + fn blit(&self, gop: &mut GraphicsOutput) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::Full, + dest: (0, 0), + dims: (self.width, self.height), + }) + } + + /// Update only a pixel to the framebuffer. + fn blit_pixel( + &self, + gop: &mut GraphicsOutput, + coords: (usize, usize), + ) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::SubRectangle { + coords, + px_stride: self.width, + }, + dest: coords, + dims: (1, 1), + }) + } +} + +/// Get a random `usize` value. +fn get_random_usize(rng: &mut Rng) -> usize { + let mut buf = [0; mem::size_of::<usize>()]; + rng.get_rng(None, &mut buf).expect("get_rng failed"); + usize::from_le_bytes(buf) +} + +fn draw_sierpinski() -> Result { + // Open graphics output protocol. + let gop_handle = boot::get_handle_for_protocol::<GraphicsOutput>()?; + let mut gop = boot::open_protocol_exclusive::<GraphicsOutput>(gop_handle)?; + + // Open random number generator protocol. + let rng_handle = boot::get_handle_for_protocol::<Rng>()?; + let mut rng = boot::open_protocol_exclusive::<Rng>(rng_handle)?; + + // Create a buffer to draw into. + let (width, height) = gop.current_mode_info().resolution(); + let mut buffer = Buffer::new(width, height); + + // Initialize the buffer with a simple gradient background. + for y in 0..height { + let r = ((y as f32) / ((height - 1) as f32)) * 255.0; + for x in 0..width { + let g = ((x as f32) / ((width - 1) as f32)) * 255.0; + let pixel = buffer.pixel(x, y).unwrap(); + pixel.red = r as u8; + pixel.green = g as u8; + pixel.blue = 255; + } + } + + // Draw background. + buffer.blit(&mut gop)?; + + let size = Point::new(width as f32, height as f32); + + // Define the vertices of a big triangle. + let border = 20.0; + let triangle = [ + Point::new(size.x / 2.0, border), + Point::new(border, size.y - border), + Point::new(size.x - border, size.y - border), + ]; + + // `p` is the point to draw. Start at the center of the triangle. + let mut p = Point::new(size.x / 2.0, size.y / 2.0); + + // Loop forever, drawing the frame after each new point is changed. + loop { + // Choose one of the triangle's vertices at random. + let v = triangle[get_random_usize(&mut rng) % 3]; + + // Move `p` halfway to the chosen vertex. + p.x = (p.x + v.x) * 0.5; + p.y = (p.y + v.y) * 0.5; + + // Set `p` to black. + let pixel = buffer.pixel(p.x as usize, p.y as usize).unwrap(); + pixel.red = 0; + pixel.green = 100; + pixel.blue = 0; + + // Draw the buffer to the screen. + buffer.blit_pixel(&mut gop, (p.x as usize, p.y as usize))?; + } +} + +#[entry] +fn main() -> Status { + uefi::helpers::init().unwrap(); + draw_sierpinski().unwrap(); + Status::SUCCESS +} +
You can run this example from the uefi-rs repository with:
+cargo xtask run --example sierpinski
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/how_to/protocols.html b/how_to/protocols.html
new file mode 100644
index 000000000..f4ffcdc3a
--- /dev/null
+++ b/how_to/protocols.html
@@ -0,0 +1,325 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ How-to
+This chapter contains practical how-to guides.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/how_to/rust-std.html b/how_to/rust-std.html
new file mode 100644
index 000000000..636cce1ec
--- /dev/null
+++ b/how_to/rust-std.html
@@ -0,0 +1,226 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Using Protocols
+The open a protocol, you must first get a handle, then open a protocol +on that handle. See Handles and Protocols for an overview of what +these terms mean.
+To get a handle you can use:
+-
+
boot::locate_handle_buffer: this can be used to get all +available handles, or just the handles that support a particular +protocol.
+boot::locate_handle: the same aslocate_handle_buffer, +but you provide the slice that stores the handles.
+boot::locate_device_path: find a handle by Device Path.
+
Once you have obtained a handle, use
+boot::open_protocol_exclusive to open a protocol on that
+handle. This returns a ScopedProtocol, which automatically closes
+the protocol when dropped.
Using boot::open_protocol_exclusive is the safest way to
+open a protocol, but in some cases a protocol cannot be opened in
+exclusive mode. The unsafe boot::open_protocol can be used
+in that case.
Example
+For this example we'll look at a program that opens a couple different
+protocols. This program opens the LoadedImage protocol to get
+information about an executable (the currently-running program in this
+case). It also opens the DevicePathToText protocol to get the file
+system path that the program was launched from.
We'll walk through the details of this program shortly, but first here's +the whole thing:
++#![no_main] +#![no_std] + +use log::info; +use uefi::boot::{self, SearchType}; +use uefi::prelude::*; +use uefi::proto::device_path::text::{ + AllowShortcuts, DevicePathToText, DisplayOnly, +}; +use uefi::proto::loaded_image::LoadedImage; +use uefi::{Identify, Result}; + +#[entry] +fn main() -> Status { + uefi::helpers::init().unwrap(); + + print_image_path().unwrap(); + + boot::stall(10_000_000); + Status::SUCCESS +} + +fn print_image_path() -> Result { + let loaded_image = + boot::open_protocol_exclusive::<LoadedImage>(boot::image_handle())?; + + let device_path_to_text_handle = *boot::locate_handle_buffer( + SearchType::ByProtocol(&DevicePathToText::GUID), + )? + .first() + .expect("DevicePathToText is missing"); + + let device_path_to_text = boot::open_protocol_exclusive::<DevicePathToText>( + device_path_to_text_handle, + )?; + + let image_device_path = + loaded_image.file_path().expect("File path is not set"); + let image_device_path_text = device_path_to_text + .convert_device_path_to_text( + image_device_path, + DisplayOnly(true), + AllowShortcuts(false), + ) + .expect("convert_device_path_to_text failed"); + + info!("Image path: {}", &*image_device_path_text); + Ok(()) +} +
When the program is run it will print something like this:
+[ INFO]: example.rs@058: Image path: \EFI\BOOT\BOOTX64.EFI
+Walkthrough
+The main function looks much like the "Hello world!" example. It
+sets up logging, calls print_image_path, and pauses for ten seconds to
+give you time to read the output. Let's look at print_image_path:
+#![allow(unused)] +fn main() { +fn print_image_path() -> Result { +} +
The return type is a uefi::Result, which is a Result alias that
+combines uefi::Status with the error data. Both the success and
+error data types are () by default.
The function starts by opening the LoadedImage protocol:
+#![allow(unused)] +fn main() { + let loaded_image = + boot::open_protocol_exclusive::<LoadedImage>(boot::image_handle())?; +} +
The boot::open_protocol_exclusive method takes a type parameter, which is
+the type of Protocol you want to open (LoadedImage in this
+case). It also takes one regular argument of type Handle. For this
+example we want the handle of the currently-running image, conveniently
+accessible through boot::image_handle.
Next the program opens the DevicePathToText protocol:
+#![allow(unused)] +fn main() { + let device_path_to_text_handle = *boot::locate_handle_buffer( + SearchType::ByProtocol(&DevicePathToText::GUID), + )? + .first() + .expect("DevicePathToText is missing"); + + let device_path_to_text = boot::open_protocol_exclusive::<DevicePathToText>( + device_path_to_text_handle, + )?; +} +
This protocol isn't available for the image_handle, so we start by
+using boot::locate_handle_buffer to find all handles that support
+DevicePathToText. We only need one handle though, so we call first()
+and discard the rest. Then we call boot::open_protocol_exclusive again. It
+looks more or less like the previous time, but with DevicePathToText
+as the type parameter and device_path_to_text_handle as the handle.
Now that we have both protocols open, we can use them together to get +the program's path and convert it to text:
++#![allow(unused)] +fn main() { + let image_device_path = + loaded_image.file_path().expect("File path is not set"); + let image_device_path_text = device_path_to_text + .convert_device_path_to_text( + image_device_path, + DisplayOnly(true), + AllowShortcuts(false), + ) + .expect("convert_device_path_to_text failed"); + + info!("Image path: {}", &*image_device_path_text); + Ok(()) +} +} +
Since protocols do a wide range of different things, the methods +available to call are very specific to each individual protocol. The +best places to find out what each protocol can do are the uefi-rs +reference documentation and the UEFI Specification.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/index.html b/index.html
new file mode 100644
index 000000000..93a21d05d
--- /dev/null
+++ b/index.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Combining Rust
+
+
+
+
+ Combining Rust std with uefi
+TL;DR
+In Mid-2024, we recommend to stick to our normal guide. Use this document as +guide and outlook for the future of UEFI and Rust.
+About
+Programs created with the uefi crate are typically created with #![no_std]
+and #![no_main]. A #![no_std] crate can use the core and alloc parts of
+Rust's standard library, but not std. A #![no_main] executable does not use
+the standard main entry point, and must define its own entry point; uefi
+provides the #[entry] macro for this purpose.
Rust has added partial support for building UEFI executables without
+#![no_std] and #![no_main], thus, the standard way. Some functionality
+requires a nightly toolchain, they are gated by the uefi_std feature (Rust
+language feature, not uefi crate feature). Follow the
+tracking issue for details.
Code Example
+Please refer to <repo>/uefi-std-example to
+see a specific example. The relevant main.rs looks as follows:
+ +// Note: In Rust 1.82.0-nightly and before, the `uefi_std` feature is +// required for accessing `std::os::uefi::env::*`. The other default +// functionality doesn't need a nightly toolchain (with Rust 1.80 and later), +// but with that limited functionality you - currently - also can't integrate +// the `uefi` crate. +#![feature(uefi_std)] + +use std::os::uefi as uefi_std; +use uefi::runtime::ResetType; +use uefi::{Handle, Status}; + +/// Performs the necessary setup code for the `uefi` crate. +fn setup_uefi_crate() { + let st = uefi_std::env::system_table(); + let ih = uefi_std::env::image_handle(); + + // Mandatory setup code for `uefi` crate. + unsafe { + uefi::table::set_system_table(st.as_ptr().cast()); + + let ih = Handle::from_ptr(ih.as_ptr().cast()).unwrap(); + uefi::boot::set_image_handle(ih); + } +} + +fn main() { + println!("Hello World from uefi_std"); + setup_uefi_crate(); + println!("UEFI-Version is {}", uefi::system::uefi_revision()); + uefi::runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None); +} +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/introduction.html b/introduction.html
new file mode 100644
index 000000000..93a21d05d
--- /dev/null
+++ b/introduction.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+Welcome to the Rust UEFI Book. The focus of this book is how to use
+uefi-rs to build UEFI applications in Rust, but it also describes
+some general UEFI concepts, as well as relevant tools such as QEMU.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mark.min.js b/mark.min.js
new file mode 100644
index 000000000..163623188
--- /dev/null
+++ b/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+Welcome to the Rust UEFI Book. The focus of this book is how to use
+uefi-rs to build UEFI applications in Rust, but it also describes
+some general UEFI concepts, as well as relevant tools such as QEMU.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference.html b/reference.html
new file mode 100644
index 000000000..6533496f0
--- /dev/null
+++ b/reference.html
@@ -0,0 +1,178 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Combining Rust
+
+
+
+
+
+ Introduction
+Welcome to the Rust UEFI Book. The focus of this book is how to use
+uefi-rs to build UEFI applications in Rust, but it also describes
+some general UEFI concepts, as well as relevant tools such as QEMU.
Tutorial
+This tutorial describes the process of creating and running a simple +x86_64 UEFI application in Rust. The application will print "Hello +World", pause for 10 seconds, then exit.
+Creating a UEFI application
+Install dependencies
+Follow the Rust installation instructions to set up Rust.
+Create a minimal application
+Create an empty application and change to that directory:
+cargo new my-uefi-app
+cd my-uefi-app
+Add a few dependencies:
+cargo add log
+cargo add uefi --features logger,panic_handler
+to your Cargo.toml. The resulting Cargo.toml should look like that:
[dependencies]
+log = "0.4.21"
+uefi = { version = "0.33.0", features = [ "panic_handler", "logger" ] }
+Replace the contents of src/main.rs with this:
+#![no_main] +#![no_std] + +use log::info; +use uefi::prelude::*; + +#[entry] +fn main() -> Status { + uefi::helpers::init().unwrap(); + info!("Hello world!"); + boot::stall(10_000_000); + Status::SUCCESS +} +
Walkthrough
+Let's look a quick look at what each part of the program is doing,
+starting with the #![...] lines at the top:
+#![allow(unused)] +#![no_main] +#![no_std] +fn main() { +} +
This is some boilerplate that all Rust UEFI applications will
+need. no_main is needed because the UEFI application entry point is
+different from the standard Rust main function. no_std is needed to
+turn off the std library; the core and alloc crates can still be
+used.
Next up are some use lines. Nothing too exciting here; the
+uefi::prelude module is intended to be glob-imported, and exports a
+number of commonly-used macros, modules, and types.
+#![allow(unused)] +fn main() { +use log::info; +use uefi::prelude::*; +} +
Now we get to the UEFI application main function, and here things look
+a little different from a standard Rust program.
+#[entry] +fn main() -> Status { +
The main function in a UEFI application takes no arguments and returns
+a Status, which is essentially a numeric error (or success) code
+defined by UEFI. The main function must be marked with the #[entry]
+macro.
The first thing we do inside of main is initialize the helpers
+module, which initializes logging:
+#![allow(unused)] +fn main() { + uefi::helpers::init().unwrap(); +} +
Next we use the standard log crate to output "Hello world!". Then we
+call stall to make the system pause for 10 seconds. This just ensures
+you have enough time to see the output.
+#![allow(unused)] +fn main() { + info!("Hello world!"); + boot::stall(10_000_000); +} +
Finally we return Status::SUCCESS indicating that everything completed
+successfully:
+#![allow(unused)] +fn main() { + Status::SUCCESS +} +} +
Building
+Toolchain
+In order to compile for UEFI, an appropriate target must be installed. The
+easiest way to set this up is using a rustup toolchain file. In the root of
+your repository, add rust-toolchain.toml:
[toolchain]
+targets = ["aarch64-unknown-uefi", "i686-unknown-uefi", "x86_64-unknown-uefi"]
+Here we have specified all three of the currently-supported UEFI targets; you +can remove some if you don't need them.
+Build the application
+Run this command to build the application:
+cargo build --target x86_64-unknown-uefi
+This will produce an x86-64 executable:
+target/x86_64-unknown-uefi/debug/my-uefi-app.efi.
Running in a VM
+Install dependencies
+Two dependencies are needed: QEMU, which implements the virtual +machine itself, and OVMF, which provides UEFI firmware that QEMU can +run.
+The details of how to install QEMU and OVMF will vary depending on your +operating system.
+Debian/Ubuntu:
+sudo apt-get install qemu ovmf
+Fedora:
+sudo dnf install qemu-kvm edk2-ovmf
+Firmware files
+The OVMF package provides two firmware files, one for the executable +code and one for variable storage. (The package may provide multiple +variations of these files; refer to the package's documentation for +details of the files it includes.)
+For ease of access we'll copy the OVMF code and vars files to the
+project directory. The location where OVMF is installed depends on your
+operating system; for Debian, Ubuntu and Fedora the files are under
+/usr/share/OVMF.
Copy the files to your project directory:
+cp /usr/share/OVMF/OVMF_CODE.fd .
+cp /usr/share/OVMF/OVMF_VARS.fd .
+System partition
+Now create a directory structure containing the executable to imitate a +UEFI System Partition:
+mkdir -p esp/efi/boot
+cp target/x86_64-unknown-uefi/debug/my-uefi-app.efi esp/efi/boot/bootx64.efi
+Launch the VM
+Now we can launch QEMU, using VVFAT to access the esp directory created above.
qemu-system-x86_64 -enable-kvm \
+ -drive if=pflash,format=raw,readonly=on,file=OVMF_CODE.fd \
+ -drive if=pflash,format=raw,readonly=on,file=OVMF_VARS.fd \
+ -drive format=raw,file=fat:rw:esp
+A QEMU window should appear, and after a few seconds you should see the +log message:
+[ INFO]: src/main.rs@011: Hello world!
+Running on Hardware
+To run on real hardware you'll need a specially-prepared USB drive.
+Preparation
+The general steps to prepare the drive are:
+-
+
- Partition the drive using GPT. +
- Create a partition. +
- Set the partition type GUID to
+
C12A7328-F81F-11D2-BA4B-00A0C93EC93B. That marks it as an EFI +System partition. (On many UEFI implementations this is not strictly +necessary, see note below.)
+ - Format the partition as FAT. +
- Mount the partition. +
- Create the directory path
EFI/BOOTon the partition. (FAT is case +insensitive, so capitalization doesn't matter.)
+ - Copy your EFI application to a file under
EFI/BOOT. The file name +is specific to the architecture. For example, on x86_64 the file name +must beBOOTX64.EFI. See the boot files table for other +architectures.
+
The details of exactly how to do these steps will vary depending on your OS.
+Note that most UEFI implementations do not strictly require GPT +partitioning or the EFI System partition GUID; they will look for any +FAT partition with the appropriate directory structure. This is not +required however; the UEFI Specification says "UEFI implementations may +allow the use of conforming FAT partitions which do not use the ESP +GUID."
+Example on Linux
+Warning: these operations are destructive! Do not run these commands +on a disk if you care about the data it contains.
+# Create the GPT, create a 9MB partition starting at 1MB, and set the
+# partition type to EFI System.
+sgdisk \
+ --clear \
+ --new=1:1M:10M \
+ --typecode=1:C12A7328-F81F-11D2-BA4B-00A0C93EC93B \
+ /path/to/disk
+
+# Format the partition as FAT.
+mkfs.fat /path/to/disk_partition
+
+# Mount the partition.
+mkdir esp
+mount /path/to/disk_partition esp
+
+# Create the boot directory.
+mkdir esp/EFI/BOOT
+
+# Copy in the boot executable.
+cp /path/to/your-executable.efi esp/EFI/BOOT/BOOTX64.EFI
+Booting the USB
+Insert the USB into the target computer. Reboot the machine, then press +the one-time boot key. Which key to press depends on the vendor. For +example, Dell uses F12, HP uses F9, and on Macs you hold down the Option +key.
+Once the one-time boot menu appears, select your USB drive and press enter.
+How-to
+This chapter contains practical how-to guides.
+Using Protocols
+The open a protocol, you must first get a handle, then open a protocol +on that handle. See Handles and Protocols for an overview of what +these terms mean.
+To get a handle you can use:
+-
+
boot::locate_handle_buffer: this can be used to get all +available handles, or just the handles that support a particular +protocol.
+boot::locate_handle: the same aslocate_handle_buffer, +but you provide the slice that stores the handles.
+boot::locate_device_path: find a handle by Device Path.
+
Once you have obtained a handle, use
+boot::open_protocol_exclusive to open a protocol on that
+handle. This returns a ScopedProtocol, which automatically closes
+the protocol when dropped.
Using boot::open_protocol_exclusive is the safest way to
+open a protocol, but in some cases a protocol cannot be opened in
+exclusive mode. The unsafe boot::open_protocol can be used
+in that case.
Example
+For this example we'll look at a program that opens a couple different
+protocols. This program opens the LoadedImage protocol to get
+information about an executable (the currently-running program in this
+case). It also opens the DevicePathToText protocol to get the file
+system path that the program was launched from.
We'll walk through the details of this program shortly, but first here's +the whole thing:
++#![no_main] +#![no_std] + +use log::info; +use uefi::boot::{self, SearchType}; +use uefi::prelude::*; +use uefi::proto::device_path::text::{ + AllowShortcuts, DevicePathToText, DisplayOnly, +}; +use uefi::proto::loaded_image::LoadedImage; +use uefi::{Identify, Result}; + +#[entry] +fn main() -> Status { + uefi::helpers::init().unwrap(); + + print_image_path().unwrap(); + + boot::stall(10_000_000); + Status::SUCCESS +} + +fn print_image_path() -> Result { + let loaded_image = + boot::open_protocol_exclusive::<LoadedImage>(boot::image_handle())?; + + let device_path_to_text_handle = *boot::locate_handle_buffer( + SearchType::ByProtocol(&DevicePathToText::GUID), + )? + .first() + .expect("DevicePathToText is missing"); + + let device_path_to_text = boot::open_protocol_exclusive::<DevicePathToText>( + device_path_to_text_handle, + )?; + + let image_device_path = + loaded_image.file_path().expect("File path is not set"); + let image_device_path_text = device_path_to_text + .convert_device_path_to_text( + image_device_path, + DisplayOnly(true), + AllowShortcuts(false), + ) + .expect("convert_device_path_to_text failed"); + + info!("Image path: {}", &*image_device_path_text); + Ok(()) +} +
When the program is run it will print something like this:
+[ INFO]: example.rs@058: Image path: \EFI\BOOT\BOOTX64.EFI
+Walkthrough
+The main function looks much like the "Hello world!" example. It
+sets up logging, calls print_image_path, and pauses for ten seconds to
+give you time to read the output. Let's look at print_image_path:
+#![allow(unused)] +fn main() { +fn print_image_path() -> Result { +} +
The return type is a uefi::Result, which is a Result alias that
+combines uefi::Status with the error data. Both the success and
+error data types are () by default.
The function starts by opening the LoadedImage protocol:
+#![allow(unused)] +fn main() { + let loaded_image = + boot::open_protocol_exclusive::<LoadedImage>(boot::image_handle())?; +} +
The boot::open_protocol_exclusive method takes a type parameter, which is
+the type of Protocol you want to open (LoadedImage in this
+case). It also takes one regular argument of type Handle. For this
+example we want the handle of the currently-running image, conveniently
+accessible through boot::image_handle.
Next the program opens the DevicePathToText protocol:
+#![allow(unused)] +fn main() { + let device_path_to_text_handle = *boot::locate_handle_buffer( + SearchType::ByProtocol(&DevicePathToText::GUID), + )? + .first() + .expect("DevicePathToText is missing"); + + let device_path_to_text = boot::open_protocol_exclusive::<DevicePathToText>( + device_path_to_text_handle, + )?; +} +
This protocol isn't available for the image_handle, so we start by
+using boot::locate_handle_buffer to find all handles that support
+DevicePathToText. We only need one handle though, so we call first()
+and discard the rest. Then we call boot::open_protocol_exclusive again. It
+looks more or less like the previous time, but with DevicePathToText
+as the type parameter and device_path_to_text_handle as the handle.
Now that we have both protocols open, we can use them together to get +the program's path and convert it to text:
++#![allow(unused)] +fn main() { + let image_device_path = + loaded_image.file_path().expect("File path is not set"); + let image_device_path_text = device_path_to_text + .convert_device_path_to_text( + image_device_path, + DisplayOnly(true), + AllowShortcuts(false), + ) + .expect("convert_device_path_to_text failed"); + + info!("Image path: {}", &*image_device_path_text); + Ok(()) +} +} +
Since protocols do a wide range of different things, the methods +available to call are very specific to each individual protocol. The +best places to find out what each protocol can do are the uefi-rs +reference documentation and the UEFI Specification.
+Drawing to the Screen
+This example shows how to draw to the screen using the graphics output protocol. +The code will a Sierpiński triangle using the "chaos game" method.
+
The core abstraction used here is a linear buffer:
++#![allow(unused)] +fn main() { +struct Buffer { + width: usize, + height: usize, + pixels: Vec<BltPixel>, +} + +impl Buffer { + /// Create a new `Buffer`. + fn new(width: usize, height: usize) -> Self { + Buffer { + width, + height, + pixels: vec![BltPixel::new(0, 0, 0); width * height], + } + } + + /// Get a single pixel. + fn pixel(&mut self, x: usize, y: usize) -> Option<&mut BltPixel> { + self.pixels.get_mut(y * self.width + x) + } + + /// Blit the buffer to the framebuffer. + fn blit(&self, gop: &mut GraphicsOutput) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::Full, + dest: (0, 0), + dims: (self.width, self.height), + }) + } + + /// Update only a pixel to the framebuffer. + fn blit_pixel( + &self, + gop: &mut GraphicsOutput, + coords: (usize, usize), + ) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::SubRectangle { + coords, + px_stride: self.width, + }, + dest: coords, + dims: (1, 1), + }) + } +} +} +
This Buffer type stores a Vec of BltPixels, which are BGRX
+32-bit pixels (8 bites each for blue, green, and red, followed by 8
+unused bits of padding). We use the pixel method to alter a single
+pixel at a time. This is often not an efficient method; for more complex
+graphics you could use a crate like embedded-graphics.
The Buffer::blit method calls the graphics output protocol's blt
+method to copy the buffer to the screen.
Most of the rest of the code is just implementing the algorithm for +drawing the fractal. Here's the full example:
++#![no_main] +#![no_std] + +extern crate alloc; + +use alloc::vec; +use alloc::vec::Vec; +use core::mem; +use uefi::prelude::*; +use uefi::proto::console::gop::{BltOp, BltPixel, BltRegion, GraphicsOutput}; +use uefi::proto::rng::Rng; +use uefi::{boot, Result}; + +#[derive(Clone, Copy)] +struct Point { + x: f32, + y: f32, +} + +impl Point { + fn new(x: f32, y: f32) -> Self { + Self { x, y } + } +} + +struct Buffer { + width: usize, + height: usize, + pixels: Vec<BltPixel>, +} + +impl Buffer { + /// Create a new `Buffer`. + fn new(width: usize, height: usize) -> Self { + Buffer { + width, + height, + pixels: vec![BltPixel::new(0, 0, 0); width * height], + } + } + + /// Get a single pixel. + fn pixel(&mut self, x: usize, y: usize) -> Option<&mut BltPixel> { + self.pixels.get_mut(y * self.width + x) + } + + /// Blit the buffer to the framebuffer. + fn blit(&self, gop: &mut GraphicsOutput) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::Full, + dest: (0, 0), + dims: (self.width, self.height), + }) + } + + /// Update only a pixel to the framebuffer. + fn blit_pixel( + &self, + gop: &mut GraphicsOutput, + coords: (usize, usize), + ) -> Result { + gop.blt(BltOp::BufferToVideo { + buffer: &self.pixels, + src: BltRegion::SubRectangle { + coords, + px_stride: self.width, + }, + dest: coords, + dims: (1, 1), + }) + } +} + +/// Get a random `usize` value. +fn get_random_usize(rng: &mut Rng) -> usize { + let mut buf = [0; mem::size_of::<usize>()]; + rng.get_rng(None, &mut buf).expect("get_rng failed"); + usize::from_le_bytes(buf) +} + +fn draw_sierpinski() -> Result { + // Open graphics output protocol. + let gop_handle = boot::get_handle_for_protocol::<GraphicsOutput>()?; + let mut gop = boot::open_protocol_exclusive::<GraphicsOutput>(gop_handle)?; + + // Open random number generator protocol. + let rng_handle = boot::get_handle_for_protocol::<Rng>()?; + let mut rng = boot::open_protocol_exclusive::<Rng>(rng_handle)?; + + // Create a buffer to draw into. + let (width, height) = gop.current_mode_info().resolution(); + let mut buffer = Buffer::new(width, height); + + // Initialize the buffer with a simple gradient background. + for y in 0..height { + let r = ((y as f32) / ((height - 1) as f32)) * 255.0; + for x in 0..width { + let g = ((x as f32) / ((width - 1) as f32)) * 255.0; + let pixel = buffer.pixel(x, y).unwrap(); + pixel.red = r as u8; + pixel.green = g as u8; + pixel.blue = 255; + } + } + + // Draw background. + buffer.blit(&mut gop)?; + + let size = Point::new(width as f32, height as f32); + + // Define the vertices of a big triangle. + let border = 20.0; + let triangle = [ + Point::new(size.x / 2.0, border), + Point::new(border, size.y - border), + Point::new(size.x - border, size.y - border), + ]; + + // `p` is the point to draw. Start at the center of the triangle. + let mut p = Point::new(size.x / 2.0, size.y / 2.0); + + // Loop forever, drawing the frame after each new point is changed. + loop { + // Choose one of the triangle's vertices at random. + let v = triangle[get_random_usize(&mut rng) % 3]; + + // Move `p` halfway to the chosen vertex. + p.x = (p.x + v.x) * 0.5; + p.y = (p.y + v.y) * 0.5; + + // Set `p` to black. + let pixel = buffer.pixel(p.x as usize, p.y as usize).unwrap(); + pixel.red = 0; + pixel.green = 100; + pixel.blue = 0; + + // Draw the buffer to the screen. + buffer.blit_pixel(&mut gop, (p.x as usize, p.y as usize))?; + } +} + +#[entry] +fn main() -> Status { + uefi::helpers::init().unwrap(); + draw_sierpinski().unwrap(); + Status::SUCCESS +} +
You can run this example from the uefi-rs repository with:
+cargo xtask run --example sierpinski
+Building drivers
+There are three types of UEFI images:
+-
+
- Application +
- Boot service driver +
- Runtime driver +
By default, Rust's UEFI targets produce applications. This can be
+changed by passing a subsystem linker flag in rustflags and setting the
+value to efi_boot_service_driver or efi_runtime_driver.
Example:
+# In .cargo/config.toml:
+[build]
+rustflags = ["-C", "link-args=/subsystem:efi_runtime_driver"]
+Combining Rust std with uefi
+TL;DR
+In Mid-2024, we recommend to stick to our normal guide. Use this document as +guide and outlook for the future of UEFI and Rust.
+About
+Programs created with the uefi crate are typically created with #![no_std]
+and #![no_main]. A #![no_std] crate can use the core and alloc parts of
+Rust's standard library, but not std. A #![no_main] executable does not use
+the standard main entry point, and must define its own entry point; uefi
+provides the #[entry] macro for this purpose.
Rust has added partial support for building UEFI executables without
+#![no_std] and #![no_main], thus, the standard way. Some functionality
+requires a nightly toolchain, they are gated by the uefi_std feature (Rust
+language feature, not uefi crate feature). Follow the
+tracking issue for details.
Code Example
+Please refer to <repo>/uefi-std-example to
+see a specific example. The relevant main.rs looks as follows:
+// Note: In Rust 1.82.0-nightly and before, the `uefi_std` feature is +// required for accessing `std::os::uefi::env::*`. The other default +// functionality doesn't need a nightly toolchain (with Rust 1.80 and later), +// but with that limited functionality you - currently - also can't integrate +// the `uefi` crate. +#![feature(uefi_std)] + +use std::os::uefi as uefi_std; +use uefi::runtime::ResetType; +use uefi::{Handle, Status}; + +/// Performs the necessary setup code for the `uefi` crate. +fn setup_uefi_crate() { + let st = uefi_std::env::system_table(); + let ih = uefi_std::env::image_handle(); + + // Mandatory setup code for `uefi` crate. + unsafe { + uefi::table::set_system_table(st.as_ptr().cast()); + + let ih = Handle::from_ptr(ih.as_ptr().cast()).unwrap(); + uefi::boot::set_image_handle(ih); + } +} + +fn main() { + println!("Hello World from uefi_std"); + setup_uefi_crate(); + println!("UEFI-Version is {}", uefi::system::uefi_revision()); + uefi::runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None); +} +
Concepts
+The canonical source of information about UEFI is the UEFI specification.
+The specification is huge (currently nearly 2500 pages). Much of that
+content relates to optional services, understanding of which is not
+critical to understanding UEFI as a whole. This chapter summarizes some
+of the more important UEFI concepts and links to the relevant uefi-rs
+documentation.
Boot Stages
+A UEFI system goes through several distinct phases during the boot process.
+-
+
- Platform Initialization. This early-boot phase is mostly outside
+the scope of the
ueficrate. It is described by the UEFI Platform +Initialization Specification, which is separate from the main UEFI +Specification.
+ - Boot Services. This is when UEFI drivers and applications are loaded.
+Functions in both the
bootmodule andruntimemodule can be used. +This stage typically culminates in running a bootloader that loads an +operating system. The stage ends whenboot::exit_boot_servicesis called, +putting the system in Runtime mode.
+ - Runtime. This stage is typically active when running an operating system
+such as Linux or Windows. UEFI functionality is much more limited in the
+Runtime mode. Functions in the
bootmodule can no longer be used, but +functions in theruntimemodule are still available. Once the system is +in Runtime mode, it cannot return to the Boot Services stage until after a +system reset.
+
Tables
+UEFI has a few table structures. These tables are how you get access to UEFI
+services. In the specification and C API, EFI_SYSTEM_TABLE is the top-level
+table that provides access to the other tables, EFI_BOOT_SERVICES and
+EFI_RUNTIME_SERVICES.
In the uefi crate, these tables are modeled as modules rather than structs. The
+functions in each module make use of a global pointer to the system table that
+is set automatically by the entry macro.
-
+
-
+
+uefi::system(EFI_SYSTEM_TABLEin the specification) provides access to +system information such as the firmware vendor and version. It can also be used +to access stdout/stderr/stdin.
+ -
+
+uefi::boot(EFI_BOOT_SERVICESin the specification) provides access to a +wide array of services such as memory allocation, executable loading, and +optional extension interfaces called protocols. Functions in this module can +only be used while in the Boot Services stage. Afterexit_boot_serviceshas +been called, these functions will panic.
+ -
+
+uefi::runtime(EFI_RUNTIME_SERVICESin the specification) provides access +to a fairly limited set of services, including variable storage, system time, +and virtual-memory mapping. Functions in this module are accessible during both +the Boot Services and Runtime stages.
+
GUID
+GUID is short for Globally Unique Identifier. A GUID is always 16 bytes,
+and has a standard string representation format that looks like this:
+313b0d7c-fed4-4de7-99ed-2fe48874a410. The details of the GUID format
+aren't too important, but be aware that the actual byte representation
+is not in the same order as the string representation because the first
+three fields are little-endian. For the most part you can treat GUIDs as
+opaque identifiers.
The UEFI specification uses GUIDs all over the place. GUIDs are used to
+identify protocols, disk partitions, variable groupings, and much
+more. In uefi-rs, GUIDs are represented by the Guid type.
Handles and Protocols
+Handles and protocols are at the core of what makes UEFI +extensible. Together they are the mechanism by which UEFI can adapt to a +wide array of hardware and boot conditions, while still providing a +consistent interface to drivers and applications.
+Handles
+Handles represent resources. A resource might be a physical device such +as a disk drive or USB device, or something less tangible like a loaded +executable.
+A Handle is an opaque pointer, so you can't do anything with it +directly. To operate on a handle you have to open a protocol.
+Protocols
+Protocols are interfaces that provide functions to interact with a +resource. For example, the BlockIO protocol provides functions to read +and write to block IO devices.
+Protocols are only available during the Boot Services stage; you can't +access them during the Runtime stage.
+The UEFI Specification defines a very large number of protocols. Because
+protocols are inherently very diverse, the best place to learn about
+individual protocols is the UEFI Specification. There are many
+chapters covering various protocols. Not all of these protocols are
+wrapped by uefi-rs yet (contributions welcome!) but many of the most
+commonly useful ones are.
See the Using Protocols how-to for details of the uefi-rs API for
+interacting with protocols.
Device Paths
+A device path is a very flexible packed data structure for storing paths +to many kinds of device. Note that these device paths are not the same +thing as file system paths, although they can include file system +paths. Like handles, device paths can be used to uniquely identify +resources such as consoles, mice, disks, partitions, and more. Unlike +handles, which are essentially opaque pointers, device paths are +variable-length structures that contain parseable information.
+The uefi::proto::device_path module documentation describes the
+details of how device paths are encoded.
Device paths can also be converted to and from human-readable text +representations that look like this:
+PciRoot(0x0)/Pci(0x1F,0x2)/Sata(0x0,0xFFFF,0x0)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)
+See uefi::proto::device_path::text for details.
Variables
+UEFI provides fairly flexible key/value variable storage.
+Each variable is identified by a key consisting of a UCS-2 +null-terminated name plus a vendor GUID. The vendor GUID serves as a +namespace for variables so that different vendors don't accidentally +overwrite or misinterpret another vendor's variable if they happen to +have the same name.
+The data stored in each variable is an arbitrary byte array.
+Attributes
+Each variable has attributes (represented as bit flags) associated with +it that affect how it is stored and how it can be accessed.
+If the BOOTSERVICE_ACCESS and RUNTIME_ACCESS bits are set, the
+variable can be accessed during both the Boot Services and Runtime
+stages. If only BOOTSERVICE_ACCESS is set then the variable can
+neither be read nor written to after exiting boot services.
Another important attribute is the NON_VOLATILE bit. If this bit is
+not set, the variable will be stored in normal memory and will not
+persist across a power cycle. If this bit is set, the variable will be
+stored in special non-volatile memory. You should be careful about
+writing variables of this type, because the non-volatile storage can be
+very limited in size. There have been cases where a vendor's poor UEFI
+implementation caused the machine not too boot once the storage became
+too full. Even figuring out how much space is in use can be tricky due
+to deletion being implemented via garbage collection. Matthew Garret's
+article "Dealing with UEFI non-volatile memory quirks" has more details.
Most of the other attributes relate to authenticated variables, which +can be used to prevent changes to a variable by unauthorized programs.
+GPT
+GPT is short for GUID Partition Table. It's a more modern +alternative to MBR (master boot record) partition tables. Although it's +defined in the UEFI specification, it often gets used on non-UEFI +systems too. There are a couple big advantages of using GPT over MBR:
+-
+
- It has a relatively clear and precise standard, unlike MBR where +implementations often just try to match what other implementations do. +
- It supports very large disks and very large numbers of partitions. +
A GPT disk contains a primary header near the beginning of the disk, +followed by a partition entry array. The header and partition entry +array have a secondary copy at the end of the disk for redundancy. The +partition entry arrays contain structures that describe each partition, +including a GUID to identify the individual partition, a partition type +GUID to indicate the purpose of the partition, and start/end block +addresses. In between the entry arrays is the actual partition data.
+System partition
+The system partition is UEFI's version of a bootable partition. The
+system partition is sometimes called the ESP, or EFI System
+Partition. It is identified by a partition type of
+c12a7328-f81f-11d2-ba4b-00a0c93ec93b. The system partition always
+contains a FAT file system. There are various standardized paths that
+can exist within the file system, and of particular importance are the
+boot files. These are the files that UEFI will try to boot from by
+default (in the absence of a different boot configuration set through
+special UEFI variables).
Boot files are under \EFI\BOOT, and are named BOOT<ARCH>.efi, where
+<ARCH> is a short architecture name.
| Architecture | File name |
|---|---|
| Intel 32-bit | BOOTIA32.EFI |
| X86_64 | BOOTX64.EFI |
| Itanium | BOOTIA64.EFI |
| AArch32 | BOOTARM.EFI |
| AArch64 | BOOTAA64.EFI |
| RISC-V 32-bit | BOOTRISCV32.EFI |
| RISC-V 64-bit | BOOTRISCV64.EFI |
| RISC-V 128-bit | BOOTRISCV128.EFI |
Reference
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/searcher.js b/searcher.js
new file mode 100644
index 000000000..d2b0aeed3
--- /dev/null
+++ b/searcher.js
@@ -0,0 +1,483 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/tutorial/building.html b/tutorial/building.html
new file mode 100644
index 000000000..a5ae67213
--- /dev/null
+++ b/tutorial/building.html
@@ -0,0 +1,192 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Creating a UEFI application
+Install dependencies
+Follow the Rust installation instructions to set up Rust.
+Create a minimal application
+Create an empty application and change to that directory:
+cargo new my-uefi-app
+cd my-uefi-app
+Add a few dependencies:
+cargo add log
+cargo add uefi --features logger,panic_handler
+to your Cargo.toml. The resulting Cargo.toml should look like that:
[dependencies]
+log = "0.4.21"
+uefi = { version = "0.33.0", features = [ "panic_handler", "logger" ] }
+Replace the contents of src/main.rs with this:
+#![no_main] +#![no_std] + +use log::info; +use uefi::prelude::*; + +#[entry] +fn main() -> Status { + uefi::helpers::init().unwrap(); + info!("Hello world!"); + boot::stall(10_000_000); + Status::SUCCESS +} +
Walkthrough
+Let's look a quick look at what each part of the program is doing,
+starting with the #![...] lines at the top:
+#![allow(unused)] +#![no_main] +#![no_std] +fn main() { +} +
This is some boilerplate that all Rust UEFI applications will
+need. no_main is needed because the UEFI application entry point is
+different from the standard Rust main function. no_std is needed to
+turn off the std library; the core and alloc crates can still be
+used.
Next up are some use lines. Nothing too exciting here; the
+uefi::prelude module is intended to be glob-imported, and exports a
+number of commonly-used macros, modules, and types.
+#![allow(unused)] +fn main() { +use log::info; +use uefi::prelude::*; +} +
Now we get to the UEFI application main function, and here things look
+a little different from a standard Rust program.
+#[entry] +fn main() -> Status { +
The main function in a UEFI application takes no arguments and returns
+a Status, which is essentially a numeric error (or success) code
+defined by UEFI. The main function must be marked with the #[entry]
+macro.
The first thing we do inside of main is initialize the helpers
+module, which initializes logging:
+#![allow(unused)] +fn main() { + uefi::helpers::init().unwrap(); +} +
Next we use the standard log crate to output "Hello world!". Then we
+call stall to make the system pause for 10 seconds. This just ensures
+you have enough time to see the output.
+#![allow(unused)] +fn main() { + info!("Hello world!"); + boot::stall(10_000_000); +} +
Finally we return Status::SUCCESS indicating that everything completed
+successfully:
+ +#![allow(unused)] +fn main() { + Status::SUCCESS +} +} +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/tutorial/hardware.html b/tutorial/hardware.html
new file mode 100644
index 000000000..aec34443a
--- /dev/null
+++ b/tutorial/hardware.html
@@ -0,0 +1,233 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Building
+Toolchain
+In order to compile for UEFI, an appropriate target must be installed. The
+easiest way to set this up is using a rustup toolchain file. In the root of
+your repository, add rust-toolchain.toml:
[toolchain]
+targets = ["aarch64-unknown-uefi", "i686-unknown-uefi", "x86_64-unknown-uefi"]
+Here we have specified all three of the currently-supported UEFI targets; you +can remove some if you don't need them.
+Build the application
+Run this command to build the application:
+cargo build --target x86_64-unknown-uefi
+This will produce an x86-64 executable:
+target/x86_64-unknown-uefi/debug/my-uefi-app.efi.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/tutorial/introduction.html b/tutorial/introduction.html
new file mode 100644
index 000000000..8431635fc
--- /dev/null
+++ b/tutorial/introduction.html
@@ -0,0 +1,180 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Running on Hardware
+To run on real hardware you'll need a specially-prepared USB drive.
+Preparation
+The general steps to prepare the drive are:
+-
+
- Partition the drive using GPT. +
- Create a partition. +
- Set the partition type GUID to
+
C12A7328-F81F-11D2-BA4B-00A0C93EC93B. That marks it as an EFI +System partition. (On many UEFI implementations this is not strictly +necessary, see note below.)
+ - Format the partition as FAT. +
- Mount the partition. +
- Create the directory path
EFI/BOOTon the partition. (FAT is case +insensitive, so capitalization doesn't matter.)
+ - Copy your EFI application to a file under
EFI/BOOT. The file name +is specific to the architecture. For example, on x86_64 the file name +must beBOOTX64.EFI. See the boot files table for other +architectures.
+
The details of exactly how to do these steps will vary depending on your OS.
+Note that most UEFI implementations do not strictly require GPT +partitioning or the EFI System partition GUID; they will look for any +FAT partition with the appropriate directory structure. This is not +required however; the UEFI Specification says "UEFI implementations may +allow the use of conforming FAT partitions which do not use the ESP +GUID."
+Example on Linux
+Warning: these operations are destructive! Do not run these commands +on a disk if you care about the data it contains.
+# Create the GPT, create a 9MB partition starting at 1MB, and set the
+# partition type to EFI System.
+sgdisk \
+ --clear \
+ --new=1:1M:10M \
+ --typecode=1:C12A7328-F81F-11D2-BA4B-00A0C93EC93B \
+ /path/to/disk
+
+# Format the partition as FAT.
+mkfs.fat /path/to/disk_partition
+
+# Mount the partition.
+mkdir esp
+mount /path/to/disk_partition esp
+
+# Create the boot directory.
+mkdir esp/EFI/BOOT
+
+# Copy in the boot executable.
+cp /path/to/your-executable.efi esp/EFI/BOOT/BOOTX64.EFI
+Booting the USB
+Insert the USB into the target computer. Reboot the machine, then press +the one-time boot key. Which key to press depends on the vendor. For +example, Dell uses F12, HP uses F9, and on Macs you hold down the Option +key.
+Once the one-time boot menu appears, select your USB drive and press enter.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/tutorial/vm.html b/tutorial/vm.html
new file mode 100644
index 000000000..b09620558
--- /dev/null
+++ b/tutorial/vm.html
@@ -0,0 +1,219 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Tutorial
+This tutorial describes the process of creating and running a simple +x86_64 UEFI application in Rust. The application will print "Hello +World", pause for 10 seconds, then exit.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Running in a VM
+Install dependencies
+Two dependencies are needed: QEMU, which implements the virtual +machine itself, and OVMF, which provides UEFI firmware that QEMU can +run.
+The details of how to install QEMU and OVMF will vary depending on your +operating system.
+Debian/Ubuntu:
+sudo apt-get install qemu ovmf
+Fedora:
+sudo dnf install qemu-kvm edk2-ovmf
+Firmware files
+The OVMF package provides two firmware files, one for the executable +code and one for variable storage. (The package may provide multiple +variations of these files; refer to the package's documentation for +details of the files it includes.)
+For ease of access we'll copy the OVMF code and vars files to the
+project directory. The location where OVMF is installed depends on your
+operating system; for Debian, Ubuntu and Fedora the files are under
+/usr/share/OVMF.
Copy the files to your project directory:
+cp /usr/share/OVMF/OVMF_CODE.fd .
+cp /usr/share/OVMF/OVMF_VARS.fd .
+System partition
+Now create a directory structure containing the executable to imitate a +UEFI System Partition:
+mkdir -p esp/efi/boot
+cp target/x86_64-unknown-uefi/debug/my-uefi-app.efi esp/efi/boot/bootx64.efi
+Launch the VM
+Now we can launch QEMU, using VVFAT to access the esp directory created above.
qemu-system-x86_64 -enable-kvm \
+ -drive if=pflash,format=raw,readonly=on,file=OVMF_CODE.fd \
+ -drive if=pflash,format=raw,readonly=on,file=OVMF_VARS.fd \
+ -drive format=raw,file=fat:rw:esp
+A QEMU window should appear, and after a few seconds you should see the +log message:
+[ INFO]: src/main.rs@011: Hello world!
+