From e6eae25053581032f7b26cb86fa6c8c84465e1c8 Mon Sep 17 00:00:00 2001
From: Nick Erdmann <n@nirf.de>
Date: Wed, 16 Oct 2019 19:42:44 +0200
Subject: std/os/uefi: add documentation

---
 lib/std/os/uefi.zig                                | 30 +++++++++++++++-
 .../uefi/protocols/absolute_pointer_protocol.zig   | 12 ++++---
 lib/std/os/uefi/protocols/edid_active_protocol.zig |  2 +-
 .../os/uefi/protocols/edid_discovered_protocol.zig |  2 +-
 .../os/uefi/protocols/edid_override_protocol.zig   |  3 +-
 .../os/uefi/protocols/graphics_output_protocol.zig |  5 ++-
 lib/std/os/uefi/protocols/hii.zig                  |  3 ++
 .../os/uefi/protocols/hii_database_protocol.zig    |  5 +++
 lib/std/os/uefi/protocols/hii_popup_protocol.zig   |  2 ++
 lib/std/os/uefi/protocols/rng_protocol.zig         |  4 ++-
 .../os/uefi/protocols/simple_pointer_protocol.zig  |  4 ++-
 .../protocols/simple_text_input_ex_protocol.zig    |  7 +++-
 .../uefi/protocols/simple_text_output_protocol.zig | 11 +++++-
 lib/std/os/uefi/status.zig                         | 42 +++++++++++++++++++++-
 lib/std/os/uefi/tables/boot_services.zig           | 21 ++++++++---
 lib/std/os/uefi/tables/configuration_table.zig     |  2 --
 lib/std/os/uefi/tables/runtime_services.zig        | 13 ++++---
 lib/std/os/uefi/tables/system_table.zig            |  7 ++--
 lib/std/os/uefi/tables/table_header.zig            |  2 +-
 19 files changed, 147 insertions(+), 30 deletions(-)

(limited to 'lib')

diff --git a/lib/std/os/uefi.zig b/lib/std/os/uefi.zig
index c1835b3f23..f42dae5fad 100644
--- a/lib/std/os/uefi.zig
+++ b/lib/std/os/uefi.zig
@@ -1,4 +1,6 @@
+/// A protocol is an interface identified by a GUID.
 pub const protocols = @import("uefi/protocols.zig");
+/// Status codes returned by EFI interfaces
 pub const status = @import("uefi/status.zig");
 pub const tables = @import("uefi/tables.zig");
 
@@ -7,11 +9,15 @@ const fmt = @import("std").fmt;
 const builtin = @import("builtin");
 pub const is_the_target = builtin.os == .uefi;
 
+/// The EFI image's handle that is passed to its entry point.
 pub var handle: Handle = undefined;
+/// A pointer to the EFI System Table that is passed to the EFI image's entry point.
 pub var system_table: *tables.SystemTable = undefined;
 
+/// A handle to an event structure.
 pub const Event = *@OpaqueType();
-// GUIDs must be align(8)
+
+/// GUIDs must be align(8)
 pub const Guid = extern struct {
     time_low: u32,
     time_mid: u16,
@@ -20,6 +26,7 @@ pub const Guid = extern struct {
     clock_seq_low: u8,
     node: [6]u8,
 
+    /// Format GUID into hexadecimal lowercase xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format
     pub fn format(
         self: @This(),
         comptime f: []const u8,
@@ -35,28 +42,49 @@ pub const Guid = extern struct {
         }
     }
 };
+
+/// An EFI Handle represents a collection of related interfaces.
 pub const Handle = *@OpaqueType();
+
+/// This structure represents time information.
 pub const Time = extern struct {
+    /// 1900 - 9999
     year: u16,
+    /// 1 - 12
     month: u8,
+    /// 1 - 31
     day: u8,
+    /// 0 - 23
     hour: u8,
+    /// 0 - 59
     minute: u8,
+    /// 0 - 59
     second: u8,
     _pad1: u8,
+    /// 0 - 999999999
     nanosecond: u32,
+    /// The time's offset in minutes from UTC.
+    /// Allowed values are -1440 to 1440 or unspecified_timezone
     timezone: i16,
     daylight: packed struct {
         _pad1: u6,
+        /// If true, the time has been adjusted for daylight savings time.
         in_daylight: bool,
+        /// If true, the time is affected by daylight savings time.
         adjust_daylight: bool,
     },
     _pad2: u8,
 
+    /// Time is to be interpreted as local time
     pub const unspecified_timezone: i16 = 0x7ff;
 };
+
+/// Capabilities of the clock device
 pub const TimeCapabilities = extern struct {
+    /// Resolution in Hz
     resolution: u32,
+    /// Accuracy in an error rate of 1e-6 parts per million.
     accuracy: u32,
+    /// If true, a time set operation clears the device's time below the resolution level.
     sets_to_zero: bool,
 };
diff --git a/lib/std/os/uefi/protocols/absolute_pointer_protocol.zig b/lib/std/os/uefi/protocols/absolute_pointer_protocol.zig
index df5a930319..722972a202 100644
--- a/lib/std/os/uefi/protocols/absolute_pointer_protocol.zig
+++ b/lib/std/os/uefi/protocols/absolute_pointer_protocol.zig
@@ -2,17 +2,19 @@ const uefi = @import("std").os.uefi;
 const Event = uefi.Event;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 12.7
+/// Protocol for touchscreens
 pub const AbsolutePointerProtocol = extern struct {
     _reset: extern fn (*const AbsolutePointerProtocol, bool) usize,
     _get_state: extern fn (*const AbsolutePointerProtocol, *AbsolutePointerState) usize,
     wait_for_input: Event,
     mode: *AbsolutePointerMode,
 
+    /// Resets the pointer device hardware.
     pub fn reset(self: *const AbsolutePointerProtocol, verify: bool) usize {
         return self._reset(self, verify);
     }
 
+    /// Retrieves the current state of a pointer device.
     pub fn getState(self: *const AbsolutePointerProtocol, state: *AbsolutePointerState) usize {
         return self._get_state(self, state);
     }
@@ -42,12 +44,12 @@ pub const AbsolutePointerMode = extern struct {
 };
 
 pub const AbsolutePointerState = extern struct {
-    current_x: u64 = undefined,
-    current_y: u64 = undefined,
-    current_z: u64 = undefined,
+    current_x: u64,
+    current_y: u64,
+    current_z: u64,
     active_buttons: packed struct {
         touch_active: bool,
         alt_active: bool,
         _pad1: u30,
-    } = undefined,
+    },
 };
diff --git a/lib/std/os/uefi/protocols/edid_active_protocol.zig b/lib/std/os/uefi/protocols/edid_active_protocol.zig
index 1a96cb6cd5..fcdef78d83 100644
--- a/lib/std/os/uefi/protocols/edid_active_protocol.zig
+++ b/lib/std/os/uefi/protocols/edid_active_protocol.zig
@@ -1,7 +1,7 @@
 const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 12.9
+/// EDID information for an active video output device
 pub const EdidActiveProtocol = extern struct {
     size_of_edid: u32,
     edid: ?[*]u8,
diff --git a/lib/std/os/uefi/protocols/edid_discovered_protocol.zig b/lib/std/os/uefi/protocols/edid_discovered_protocol.zig
index f68b0fa3d6..00b59cb6c8 100644
--- a/lib/std/os/uefi/protocols/edid_discovered_protocol.zig
+++ b/lib/std/os/uefi/protocols/edid_discovered_protocol.zig
@@ -1,7 +1,7 @@
 const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 12.9
+/// EDID information for a video output device
 pub const EdidDiscoveredProtocol = extern struct {
     size_of_edid: u32,
     edid: ?[*]u8,
diff --git a/lib/std/os/uefi/protocols/edid_override_protocol.zig b/lib/std/os/uefi/protocols/edid_override_protocol.zig
index ad2eec1207..c11af8f0a1 100644
--- a/lib/std/os/uefi/protocols/edid_override_protocol.zig
+++ b/lib/std/os/uefi/protocols/edid_override_protocol.zig
@@ -2,10 +2,11 @@ const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 const Handle = uefi.Handle;
 
-/// UEFI Specification, Version 2.8, 12.9
+/// Override EDID information
 pub const EdidOverrideProtocol = extern struct {
     _get_edid: extern fn (*const EdidOverrideProtocol, Handle, *u32, *usize, *?[*]u8) usize,
 
+    /// Returns policy information and potentially a replacement EDID for the specified video output device.
     /// attributes must be align(4)
     pub fn getEdid(self: *const EdidOverrideProtocol, handle: Handle, attributes: *EdidOverrideProtocolAttributes, edid_size: *usize, edid: *?[*]u8) usize {
         return self._get_edid(self, handle, attributes, edid_size, edid);
diff --git a/lib/std/os/uefi/protocols/graphics_output_protocol.zig b/lib/std/os/uefi/protocols/graphics_output_protocol.zig
index 4713df0501..f63f9d12dc 100644
--- a/lib/std/os/uefi/protocols/graphics_output_protocol.zig
+++ b/lib/std/os/uefi/protocols/graphics_output_protocol.zig
@@ -1,21 +1,24 @@
 const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 12.9
+/// Graphics output
 pub const GraphicsOutputProtocol = extern struct {
     _query_mode: extern fn (*const GraphicsOutputProtocol, u32, *usize, **GraphicsOutputModeInformation) usize,
     _set_mode: extern fn (*const GraphicsOutputProtocol, u32) usize,
     _blt: extern fn (*const GraphicsOutputProtocol, ?[*]GraphicsOutputBltPixel, GraphicsOutputBltOperation, usize, usize, usize, usize, usize, usize, usize) usize,
     mode: *GraphicsOutputProtocolMode,
 
+    /// Returns information for an available graphics mode that the graphics device and the set of active video output devices supports.
     pub fn queryMode(self: *const GraphicsOutputProtocol, mode: u32, size_of_info: *usize, info: **GraphicsOutputModeInformation) usize {
         return self._query_mode(self, mode, size_of_info, info);
     }
 
+    /// Set the video device into the specified mode and clears the visible portions of the output display to black.
     pub fn setMode(self: *const GraphicsOutputProtocol, mode: u32) usize {
         return self._set_mode(self, mode);
     }
 
+    /// Blt a rectangle of pixels on the graphics screen. Blt stands for BLock Transfer.
     pub fn blt(self: *const GraphicsOutputProtocol, blt_buffer: ?[*]GraphicsOutputBltPixel, blt_operation: GraphicsOutputBltOperation, source_x: usize, source_y: usize, destination_x: usize, destination_y: usize, width: usize, height: usize, delta: usize) usize {
         return self._blt(self, blt_buffer, blt_operation, source_x, source_y, destination_x, destination_y, width, height, delta);
     }
diff --git a/lib/std/os/uefi/protocols/hii.zig b/lib/std/os/uefi/protocols/hii.zig
index 64d03b57cf..5dd9095d14 100644
--- a/lib/std/os/uefi/protocols/hii.zig
+++ b/lib/std/os/uefi/protocols/hii.zig
@@ -3,6 +3,7 @@ const Guid = uefi.Guid;
 
 pub const HIIHandle = *@OpaqueType();
 
+/// The header found at the start of each package.
 pub const HIIPackageHeader = packed struct {
     length: u24,
     type: u8,
@@ -22,8 +23,10 @@ pub const HIIPackageHeader = packed struct {
     pub const type_system_end: u8 = 0xff;
 };
 
+/// The header found at the start of each package list.
 pub const HIIPackageList = extern struct {
     package_list_guid: Guid,
+    /// The size of the package list (in bytes), including the header.
     package_list_length: u32,
 
     // TODO implement iterator
diff --git a/lib/std/os/uefi/protocols/hii_database_protocol.zig b/lib/std/os/uefi/protocols/hii_database_protocol.zig
index 5e0f835cf5..aaacce8462 100644
--- a/lib/std/os/uefi/protocols/hii_database_protocol.zig
+++ b/lib/std/os/uefi/protocols/hii_database_protocol.zig
@@ -2,6 +2,7 @@ const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 const hii = uefi.protocols.hii;
 
+/// Database manager for HII-related data structures.
 pub const HIIDatabaseProtocol = extern struct {
     _new_package_list: usize, // TODO
     _remove_package_list: extern fn (*const HIIDatabaseProtocol, hii.HIIHandle) usize,
@@ -15,18 +16,22 @@ pub const HIIDatabaseProtocol = extern struct {
     _set_keyboard_layout: usize, // TODO
     _get_package_list_handle: usize, // TODO
 
+    /// Removes a package list from the HII database.
     pub fn removePackageList(self: *const HIIDatabaseProtocol, handle: hii.HIIHandle) usize {
         return self._remove_package_list(self, handle);
     }
 
+    /// Update a package list in the HII database.
     pub fn updatePackageList(self: *const HIIDatabaseProtocol, handle: hii.HIIHandle, buffer: *const hii.HIIPackageList) usize {
         return self._update_package_list(self, handle, buffer);
     }
 
+    /// Determines the handles that are currently active in the database.
     pub fn listPackageLists(self: *const HIIDatabaseProtocol, package_type: u8, package_guid: ?*const Guid, buffer_length: *usize, handles: [*]hii.HIIHandle) usize {
         return self._list_package_lists(self, package_type, package_guid, buffer_length, handles);
     }
 
+    /// Exports the contents of one or all package lists in the HII database into a buffer.
     pub fn exportPackageLists(self: *const HIIDatabaseProtocol, handle: ?hii.HIIHandle, buffer_size: *usize, buffer: *hii.HIIPackageList) usize {
         return self._export_package_lists(self, handle, buffer_size, buffer);
     }
diff --git a/lib/std/os/uefi/protocols/hii_popup_protocol.zig b/lib/std/os/uefi/protocols/hii_popup_protocol.zig
index ee12d359fe..3152a8b7a8 100644
--- a/lib/std/os/uefi/protocols/hii_popup_protocol.zig
+++ b/lib/std/os/uefi/protocols/hii_popup_protocol.zig
@@ -2,10 +2,12 @@ const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 const hii = uefi.protocols.hii;
 
+/// Display a popup window
 pub const HIIPopupProtocol = extern struct {
     revision: u64,
     _create_popup: extern fn (*const HIIPopupProtocol, HIIPopupStyle, HIIPopupType, hii.HIIHandle, u16, ?*HIIPopupSelection) usize,
 
+    /// Displays a popup window.
     pub fn createPopup(self: *const HIIPopupProtocol, style: HIIPopupStyle, popup_type: HIIPopupType, handle: hii.HIIHandle, msg: u16, user_selection: ?*HIIPopupSelection) usize {
         return self._create_popup(self, style, popup_type, handle, msg, user_selection);
     }
diff --git a/lib/std/os/uefi/protocols/rng_protocol.zig b/lib/std/os/uefi/protocols/rng_protocol.zig
index f7c756fb05..65eb882afb 100644
--- a/lib/std/os/uefi/protocols/rng_protocol.zig
+++ b/lib/std/os/uefi/protocols/rng_protocol.zig
@@ -1,15 +1,17 @@
 const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 37.5
+/// Random Number Generator protocol
 pub const RNGProtocol = extern struct {
     _get_info: extern fn (*const RNGProtocol, *usize, [*]align(8) Guid) usize,
     _get_rng: extern fn (*const RNGProtocol, ?*align(8) const Guid, usize, [*]u8) usize,
 
+    /// Returns information about the random number generation implementation.
     pub fn getInfo(self: *const RNGProtocol, list_size: *usize, list: [*]align(8) Guid) usize {
         return self._get_info(self, list_size, list);
     }
 
+    /// Produces and returns an RNG value using either the default or specified RNG algorithm.
     pub fn getRNG(self: *const RNGProtocol, algo: ?*align(8) const Guid, value_length: usize, value: [*]u8) usize {
         return self._get_rng(self, algo, value_length, value);
     }
diff --git a/lib/std/os/uefi/protocols/simple_pointer_protocol.zig b/lib/std/os/uefi/protocols/simple_pointer_protocol.zig
index 369bc76aaa..e0cb4ba354 100644
--- a/lib/std/os/uefi/protocols/simple_pointer_protocol.zig
+++ b/lib/std/os/uefi/protocols/simple_pointer_protocol.zig
@@ -2,17 +2,19 @@ const uefi = @import("std").os.uefi;
 const Event = uefi.Event;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 12.5
+/// Protocol for mice
 pub const SimplePointerProtocol = struct {
     _reset: extern fn (*const SimplePointerProtocol, bool) usize,
     _get_state: extern fn (*const SimplePointerProtocol, *SimplePointerState) usize,
     wait_for_input: Event,
     mode: *SimplePointerMode,
 
+    /// Resets the pointer device hardware.
     pub fn reset(self: *const SimplePointerProtocol, verify: bool) usize {
         return self._reset(self, verify);
     }
 
+    /// Retrieves the current state of a pointer device.
     pub fn getState(self: *const SimplePointerProtocol, state: *SimplePointerState) usize {
         return self._get_state(self, state);
     }
diff --git a/lib/std/os/uefi/protocols/simple_text_input_ex_protocol.zig b/lib/std/os/uefi/protocols/simple_text_input_ex_protocol.zig
index 5507b8950c..e2c4be7847 100644
--- a/lib/std/os/uefi/protocols/simple_text_input_ex_protocol.zig
+++ b/lib/std/os/uefi/protocols/simple_text_input_ex_protocol.zig
@@ -2,7 +2,7 @@ const uefi = @import("std").os.uefi;
 const Event = uefi.Event;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 12.3
+/// Character input devices, e.g. Keyboard
 pub const SimpleTextInputExProtocol = extern struct {
     _reset: extern fn (*const SimpleTextInputExProtocol, bool) usize,
     _read_key_stroke_ex: extern fn (*const SimpleTextInputExProtocol, *KeyData) usize,
@@ -11,22 +11,27 @@ pub const SimpleTextInputExProtocol = extern struct {
     _register_key_notify: extern fn (*const SimpleTextInputExProtocol, *const KeyData, extern fn (*const KeyData) usize, **c_void) usize,
     _unregister_key_notify: extern fn (*const SimpleTextInputExProtocol, *const c_void) usize,
 
+    /// Resets the input device hardware.
     pub fn reset(self: *const SimpleTextInputExProtocol, verify: bool) usize {
         return self._reset(self, verify);
     }
 
+    /// Reads the next keystroke from the input device.
     pub fn readKeyStrokeEx(self: *const SimpleTextInputExProtocol, key_data: *KeyData) usize {
         return self._read_key_stroke_ex(self, key_data);
     }
 
+    /// Set certain state for the input device.
     pub fn setState(self: *const SimpleTextInputExProtocol, state: *const u8) usize {
         return self._set_state(self, state);
     }
 
+    /// Register a notification function for a particular keystroke for the input device.
     pub fn registerKeyNotify(self: *const SimpleTextInputExProtocol, key_data: *const KeyData, notify: extern fn (*const KeyData) usize, handle: **c_void) usize {
         return self._register_key_notify(self, key_data, notify, handle);
     }
 
+    /// Remove the notification that was previously registered.
     pub fn unregisterKeyNotify(self: *const SimpleTextInputExProtocol, handle: *const c_void) usize {
         return self._unregister_key_notify(self, handle);
     }
diff --git a/lib/std/os/uefi/protocols/simple_text_output_protocol.zig b/lib/std/os/uefi/protocols/simple_text_output_protocol.zig
index e6b2e21c70..78358214a2 100644
--- a/lib/std/os/uefi/protocols/simple_text_output_protocol.zig
+++ b/lib/std/os/uefi/protocols/simple_text_output_protocol.zig
@@ -1,7 +1,7 @@
 const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 12.4
+/// Character output devices
 pub const SimpleTextOutputProtocol = extern struct {
     _reset: extern fn (*const SimpleTextOutputProtocol, bool) usize,
     _output_string: extern fn (*const SimpleTextOutputProtocol, [*]const u16) usize,
@@ -14,38 +14,47 @@ pub const SimpleTextOutputProtocol = extern struct {
     _enable_cursor: extern fn (*const SimpleTextOutputProtocol, bool) usize,
     mode: *SimpleTextOutputMode,
 
+    /// Resets the text output device hardware.
     pub fn reset(self: *const SimpleTextOutputProtocol, verify: bool) usize {
         return self._reset(self, verify);
     }
 
+    /// Writes a string to the output device.
     pub fn outputString(self: *const SimpleTextOutputProtocol, msg: [*]const u16) usize {
         return self._output_string(self, msg);
     }
 
+    /// Verifies that all characters in a string can be output to the target device.
     pub fn testString(self: *const SimpleTextOutputProtocol, msg: [*]const u16) usize {
         return self._test_string(self, msg);
     }
 
+    /// Returns information for an available text mode that the output device(s) supports.
     pub fn queryMode(self: *const SimpleTextOutputProtocol, mode_number: usize, columns: *usize, rows: *usize) usize {
         return self._query_mode(self, mode_number, columns, rows);
     }
 
+    /// Sets the output device(s) to a specified mode.
     pub fn setMode(self: *const SimpleTextOutputProtocol, mode_number: usize) usize {
         return self._set_mode(self, mode_number);
     }
 
+    /// Sets the background and foreground colors for the outputString() and clearScreen() functions.
     pub fn setAttribute(self: *const SimpleTextOutputProtocol, attribute: usize) usize {
         return self._set_attribute(self, attribute);
     }
 
+    /// Clears the output device(s) display to the currently selected background color.
     pub fn clearScreen(self: *const SimpleTextOutputProtocol) usize {
         return self._clear_screen(self);
     }
 
+    /// Sets the current coordinates of the cursor position.
     pub fn setCursorPosition(self: *const SimpleTextOutputProtocol, column: usize, row: usize) usize {
         return self._set_cursor_position(self, column, row);
     }
 
+    /// Makes the cursor visible or invisible.
     pub fn enableCursor(self: *const SimpleTextOutputProtocol, visible: bool) usize {
         return self._enable_cursor(self, visible);
     }
diff --git a/lib/std/os/uefi/status.zig b/lib/std/os/uefi/status.zig
index 6deb741d0d..7c7f98b450 100644
--- a/lib/std/os/uefi/status.zig
+++ b/lib/std/os/uefi/status.zig
@@ -1,46 +1,86 @@
 const high_bit = 1 << @typeInfo(usize).Int.bits - 1;
 
-/// UEFI Specification, Version 2.8, Appendix D
+/// The operation completed successfully.
 pub const success: usize = 0;
 
+/// The image failed to load.
 pub const load_error: usize = high_bit | 1;
+/// A parameter was incorrect.
 pub const invalid_parameter: usize = high_bit | 2;
+/// The operation is not supported.
 pub const unsupported: usize = high_bit | 3;
+/// The buffer was not the proper size for the request.
 pub const bad_buffer_size: usize = high_bit | 4;
+/// The buffer is not large enough to hold the requested data. The required buffer size is returned in the appropriate parameter when this error occurs.
 pub const buffer_too_small: usize = high_bit | 5;
+/// There is no data pending upon return.
 pub const not_ready: usize = high_bit | 6;
+/// The physical device reported an error while attempting the operation.
 pub const device_error: usize = high_bit | 7;
+/// The device cannot be written to.
 pub const write_protected: usize = high_bit | 8;
+/// A resource has run out.
 pub const out_of_resources: usize = high_bit | 9;
+/// An inconstancy was detected on the file system causing the operating to fail.
 pub const volume_corrupted: usize = high_bit | 10;
+/// There is no more space on the file system.
 pub const volume_full: usize = high_bit | 11;
+/// The device does not contain any medium to perform the operation.
 pub const no_media: usize = high_bit | 12;
+/// The medium in the device has changed since the last access.
 pub const media_changed: usize = high_bit | 13;
+/// The item was not found.
 pub const not_found: usize = high_bit | 14;
+/// Access was denied.
 pub const access_denied: usize = high_bit | 15;
+/// The server was not found or did not respond to the request.
 pub const no_response: usize = high_bit | 16;
+/// A mapping to a device does not exist.
 pub const no_mapping: usize = high_bit | 17;
+/// The timeout time expired.
 pub const timeout: usize = high_bit | 18;
+/// The protocol has not been started.
 pub const not_started: usize = high_bit | 19;
+/// The protocol has already been started.
 pub const already_started: usize = high_bit | 20;
+/// The operation was aborted.
 pub const aborted: usize = high_bit | 21;
+/// An ICMP error occurred during the network operation.
 pub const icmp_error: usize = high_bit | 22;
+/// A TFTP error occurred during the network operation.
 pub const tftp_error: usize = high_bit | 23;
+/// A protocol error occurred during the network operation.
 pub const protocol_error: usize = high_bit | 24;
+/// The function encountered an internal version that was incompatible with a version requested by the caller.
 pub const incompatible_version: usize = high_bit | 25;
+/// The function was not performed due to a security violation.
 pub const security_violation: usize = high_bit | 26;
+/// A CRC error was detected.
 pub const crc_error: usize = high_bit | 27;
+/// Beginning or end of media was reached
 pub const end_of_media: usize = high_bit | 28;
+/// The end of the file was reached.
 pub const end_of_file: usize = high_bit | 31;
+/// The language specified was invalid.
 pub const invalid_language: usize = high_bit | 32;
+/// The security status of the data is unknown or compromised and the data must be updated or replaced to restore a valid security status.
 pub const compromised_data: usize = high_bit | 33;
+/// There is an address conflict address allocation
 pub const ip_address_conflict: usize = high_bit | 34;
+/// A HTTP error occurred during the network operation.
 pub const http_error: usize = high_bit | 35;
 
+/// The string contained one or more characters that the device could not render and were skipped.
 pub const warn_unknown_glyph: usize = 1;
+/// The handle was closed, but the file was not deleted.
 pub const warn_delete_failure: usize = 2;
+/// The handle was closed, but the data to the file was not flushed properly.
 pub const warn_write_failure: usize = 3;
+/// The resulting buffer was too small, and the data was truncated to the buffer size.
 pub const warn_buffer_too_small: usize = 4;
+/// The data has not been updated within the timeframe set by localpolicy for this type of data.
 pub const warn_stale_data: usize = 5;
+/// The resulting buffer contains UEFI-compliant file system.
 pub const warn_file_system: usize = 6;
+/// The operation will be processed across a system reset.
 pub const warn_reset_required: usize = 7;
diff --git a/lib/std/os/uefi/tables/boot_services.zig b/lib/std/os/uefi/tables/boot_services.zig
index 8954481544..18fb082235 100644
--- a/lib/std/os/uefi/tables/boot_services.zig
+++ b/lib/std/os/uefi/tables/boot_services.zig
@@ -4,29 +4,37 @@ const Guid = uefi.Guid;
 const Handle = uefi.Handle;
 const TableHeader = uefi.tables.TableHeader;
 
-/// UEFI Specification, Version 2.8, 4.4
-///
-/// As the boot_services table may grow with new UEFI versions, it is important to check hdr.header_size.
+/// Boot services are services provided by the system's firmware until the operating system takes
+/// over control over the hardware by calling exitBootServices.
 ///
 /// Boot Services must not be used after exitBootServices has been called. The only exception is
 /// getMemoryMap, which may be used after the first unsuccessful call to exitBootServices.
 /// After successfully calling exitBootServices, system_table.console_in_handle, system_table.con_in,
 /// system_table.console_out_handle, system_table.con_out, system_table.standard_error_handle,
 /// system_table.std_err, and system_table.boot_services should be set to null. After setting these
-/// attributes to null, system_table.hdr.crc32 must be recomputed. See UEFI Specification, Version 2.8, 7.4.
+/// attributes to null, system_table.hdr.crc32 must be recomputed.
+///
+/// As the boot_services table may grow with new UEFI versions, it is important to check hdr.header_size.
 pub const BootServices = extern struct {
     hdr: TableHeader,
     raiseTpl: usize, // TODO
     restoreTpl: usize, // TODO
     allocatePages: usize, // TODO
     freePages: usize, // TODO
+    /// Returns the current memory map.
     getMemoryMap: extern fn (*usize, [*]MemoryDescriptor, *usize, *usize, *u32) usize,
+    /// Allocates pool memory.
     allocatePool: extern fn (MemoryType, usize, *align(8) [*]u8) usize,
     freePool: usize, // TODO
+    /// Creates an event.
     createEvent: extern fn (u32, usize, ?extern fn (Event, ?*const c_void) void, ?*const c_void, *Event) usize,
+    /// Sets the type of timer and the trigger time for a timer event.
     setTimer: extern fn (Event, TimerDelay, u64) usize,
+    /// Stops execution until an event is signaled.
     waitForEvent: extern fn (usize, [*]const Event, *usize) usize,
+    /// Signals an event.
     signalEvent: extern fn (Event) usize,
+    /// Closes an event.
     closeEvent: extern fn (Event) usize,
     checkEvent: usize, // TODO
     installProtocolInterface: usize, // TODO
@@ -40,11 +48,15 @@ pub const BootServices = extern struct {
     installConfigurationTable: usize, // TODO
     imageLoad: usize, // TODO
     imageStart: usize, // TODO
+    /// Terminates a loaded EFI image and returns control to boot services.
     exit: extern fn (Handle, usize, usize, ?*const c_void) usize,
     imageUnload: usize, // TODO
+    /// Terminates all boot services.
     exitBootServices: extern fn (Handle, usize) usize,
     getNextMonotonicCount: usize, // TODO
+    /// Induces a fine-grained stall.
     stall: extern fn (usize) usize,
+    /// Sets the system's watchdog timer.
     setWatchdogTimer: extern fn (usize, u64, usize, ?[*]const u16) usize,
     connectController: usize, // TODO
     disconnectController: usize, // TODO
@@ -53,6 +65,7 @@ pub const BootServices = extern struct {
     openProtocolInformation: usize, // TODO
     protocolsPerHandle: usize, // TODO
     locateHandleBuffer: usize, // TODO
+    /// Returns the first protocol instance that matches the given protocol.
     locateProtocol: extern fn (*align(8) const Guid, ?*const c_void, *?*c_void) usize,
     installMultipleProtocolInterfaces: usize, // TODO
     uninstallMultipleProtocolInterfaces: usize, // TODO
diff --git a/lib/std/os/uefi/tables/configuration_table.zig b/lib/std/os/uefi/tables/configuration_table.zig
index eb99e08477..0ac3bd73c8 100644
--- a/lib/std/os/uefi/tables/configuration_table.zig
+++ b/lib/std/os/uefi/tables/configuration_table.zig
@@ -1,8 +1,6 @@
 const uefi = @import("std").os.uefi;
 const Guid = uefi.Guid;
 
-/// UEFI Specification, Version 2.8, 4.6
-/// Because GUIDs must be align(8), structs of this type also must be align(8)
 pub const ConfigurationTable = extern struct {
     vendor_guid: Guid,
     vendor_table: *c_void,
diff --git a/lib/std/os/uefi/tables/runtime_services.zig b/lib/std/os/uefi/tables/runtime_services.zig
index 53cb17db50..89231b51a8 100644
--- a/lib/std/os/uefi/tables/runtime_services.zig
+++ b/lib/std/os/uefi/tables/runtime_services.zig
@@ -4,26 +4,31 @@ const TableHeader = uefi.tables.TableHeader;
 const Time = uefi.Time;
 const TimeCapabilities = uefi.TimeCapabilities;
 
-/// UEFI Specification, Version 2.8, 4.5
+/// Runtime services are provided by the firmware before and after exitBootServices has been called.
 ///
 /// As the runtime_services table may grow with new UEFI versions, it is important to check hdr.header_size.
 ///
 /// Some functions may not be supported. Check the RuntimeServicesSupported variable using getVariable.
-/// getVariable is one of the functions that may not be supported. See UEFI Specification, Version 2.8, 8.1.
+/// getVariable is one of the functions that may not be supported.
 ///
-/// Some functions may not be called while other functions are running. See UEFI Specification, Version 2.8, 8.1.
+/// Some functions may not be called while other functions are running.
 pub const RuntimeServices = extern struct {
     hdr: TableHeader,
+    /// Returns the current time and date information, and the time-keeping capabilities of the hardware platform.
     getTime: extern fn (*uefi.Time, ?*TimeCapabilities) usize,
     setTime: usize, // TODO
     getWakeupTime: usize, // TODO
     setWakeupTime: usize, // TODO
     setVirtualAddressMap: usize, // TODO
     convertPointer: usize, // TODO
+    /// Returns the value of a variable.
     getVariable: extern fn ([*]const u16, *align(8) const Guid, ?*u32, *usize, ?*c_void) usize,
+    /// Enumerates the current variable names.
     getNextVariableName: extern fn (*usize, [*]u16, *align(8) Guid) usize,
+    /// Sets the value of a variable.
     setVariable: extern fn ([*]const u16, *align(8) const Guid, u32, usize, *c_void) usize,
     getNextHighMonotonicCount: usize, // TODO
+    /// Resets the entire platform.
     resetSystem: extern fn (ResetType, usize, usize, ?*const c_void) noreturn,
     updateCapsule: usize, // TODO
     queryCapsuleCapabilities: usize, // TODO
@@ -32,7 +37,6 @@ pub const RuntimeServices = extern struct {
     pub const signature: u64 = 0x56524553544e5552;
 };
 
-/// UEFI Specification, Version 2.8, 8.5.1
 pub const ResetType = extern enum(u32) {
     ResetCold,
     ResetWarm,
@@ -40,7 +44,6 @@ pub const ResetType = extern enum(u32) {
     ResetPlatformSpecific,
 };
 
-/// UEFI Specification, Version 2.8, 3.3
 pub const global_variable align(8) = Guid{
     .time_low = 0x8be4df61,
     .time_mid = 0x93ca,
diff --git a/lib/std/os/uefi/tables/system_table.zig b/lib/std/os/uefi/tables/system_table.zig
index 23140f984e..6ace8e4001 100644
--- a/lib/std/os/uefi/tables/system_table.zig
+++ b/lib/std/os/uefi/tables/system_table.zig
@@ -7,17 +7,18 @@ const SimpleTextInputExProtocol = uefi.protocols.SimpleTextInputExProtocol;
 const SimpleTextOutputProtocol = uefi.protocols.SimpleTextOutputProtocol;
 const TableHeader = uefi.tables.TableHeader;
 
-/// UEFI Specification, Version 2.8, 4.3
+/// The EFI System Table contains pointers to the runtime and boot services tables.
 ///
 /// As the system_table may grow with new UEFI versions, it is important to check hdr.header_size.
 ///
 /// After successfully calling boot_services.exitBootServices, console_in_handle,
 /// con_in, console_out_handle, con_out, standard_error_handle, std_err, and
 /// boot_services should be set to null. After setting these attributes to null,
-/// hdr.crc32 must be recomputed. See UEFI Specification, Version 2.8, 7.4.
+/// hdr.crc32 must be recomputed.
 pub const SystemTable = extern struct {
     hdr: TableHeader,
-    firmware_vendor: *u16,
+    /// A null-terminated string that identifies the vendor that produces the system firmware of the platform.
+    firmware_vendor: [*]u16,
     firmware_revision: u32,
     console_in_handle: ?Handle,
     con_in: ?*SimpleTextInputExProtocol,
diff --git a/lib/std/os/uefi/tables/table_header.zig b/lib/std/os/uefi/tables/table_header.zig
index b955768e63..527c7a61b9 100644
--- a/lib/std/os/uefi/tables/table_header.zig
+++ b/lib/std/os/uefi/tables/table_header.zig
@@ -1,7 +1,7 @@
-/// UEFI Specification, Version 2.8, 4.2
 pub const TableHeader = extern struct {
     signature: u64,
     revision: u32,
+    /// The size, in bytes, of the entire table including the TableHeader
     header_size: u32,
     crc32: u32,
     reserved: u32,
-- 
cgit v1.2.3