Merge branch 'master' into next

README.md

@@ -19,3 +19,24 @@ This can be done by either:
 
 If the `nightly` feature or any of its sub-features is enabled (which is the
 default), a recent nightly is required.
+
+## Other OS development crates
+
+This crate does not attempt to handle every facet of OS development. Other
+useful crates in this space include:
+  - [`raw-cpuid`](https://crates.io/crates/raw-cpuid): safe wrappers around the
+  [`cpuid` instruction](https://en.wikipedia.org/wiki/CPUID)
+    - Provides parsed versions of the CPUID data, rather than just raw binary values.
+    - Support for AMD and Intel specific values.
+    - Works on x86 and x86_64 systems, in both user and kernel mode.
+  - [`uefi`](https://crates.io/crates/uefi): abstractions for
+  [UEFI](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface)
+  (the successor to BIOS)
+    - Provides UEFI tables, functions, and types.
+    - Useful for writing UEFI applications, or calling UEFI functions from your OS.
+    - Works on a variety of modern platforms, not just x86_64.
+  - [`volatile`](https://crates.io/crates/volatile): interface to
+  [`read_volatile`](https://doc.rust-lang.org/std/ptr/fn.read_volatile.html) and
+  [`write_volatile`](https://doc.rust-lang.org/std/ptr/fn.write_volatile.html)
+    - Makes it easier to program [MMIO](https://en.wikipedia.org/wiki/Memory-mapped_I/O) interfaces and devices.
+    - Works on any Rust target.

src/addr.rs

@@ -159,12 +159,17 @@ impl VirtAddr {
     /// Aligns the virtual address upwards to the given alignment.
     ///
     /// See the `align_up` function for more information.
+    ///
+    /// # Panics
+    ///
+    /// This function panics if the resulting address is higher than
+    /// `0xffff_ffff_ffff_ffff`.
     #[inline]
     pub fn align_up<U>(self, align: U) -> Self
     where
         U: Into<u64>,
     {
-        VirtAddr(align_up(self.0, align.into()))
+        VirtAddr::new_truncate(align_up(self.0, align.into()))
     }
 
     /// Aligns the virtual address downwards to the given alignment.
@@ -175,7 +180,7 @@ impl VirtAddr {
     where
         U: Into<u64>,
     {
-        VirtAddr(align_down(self.0, align.into()))
+        VirtAddr::new_truncate(align_down(self.0, align.into()))
     }
 
     /// Checks whether the virtual address has the demanded alignment.
@@ -445,12 +450,17 @@ impl PhysAddr {
     /// Aligns the physical address upwards to the given alignment.
     ///
     /// See the `align_up` function for more information.
+    ///
+    /// # Panics
+    ///
+    /// This function panics if the resulting address has a bit in the range 52
+    /// to 64 set.
     #[inline]
     pub fn align_up<U>(self, align: U) -> Self
     where
         U: Into<u64>,
     {
-        PhysAddr(align_up(self.0, align.into()))
+        PhysAddr::new(align_up(self.0, align.into()))
     }
 
     /// Aligns the physical address downwards to the given alignment.
@@ -570,15 +580,20 @@ pub const fn align_down(addr: u64, align: u64) -> u64 {
 ///
 /// Returns the smallest `x` with alignment `align` so that `x >= addr`.
 ///
-/// Panics if the alignment is not a power of two.
+/// Panics if the alignment is not a power of two or if an overflow occurs.
 #[inline]
 pub const fn align_up(addr: u64, align: u64) -> u64 {
     assert!(align.is_power_of_two(), "`align` must be a power of two");
     let align_mask = align - 1;
     if addr & align_mask == 0 {
         addr // already aligned
     } else {
-        (addr | align_mask) + 1
+        // FIXME: Replace with .expect, once `Option::expect` is const.
+        if let Some(aligned) = (addr | align_mask).checked_add(1) {
+            aligned
+        } else {
+            panic!("attempt to add with overflow")
+        }
     }
 }
 
@@ -724,4 +739,34 @@ mod tests {
         assert_eq!(align_up(0, 2), 0);
         assert_eq!(align_up(0, 0x8000_0000_0000_0000), 0);
     }
+
+    #[test]
+    fn test_virt_addr_align_up() {
+        // Make sure the 47th bit is extended.
+        assert_eq!(
+            VirtAddr::new(0x7fff_ffff_ffff).align_up(2u64),
+            VirtAddr::new(0xffff_8000_0000_0000)
+        );
+    }
+
+    #[test]
+    fn test_virt_addr_align_down() {
+        // Make sure the 47th bit is extended.
+        assert_eq!(
+            VirtAddr::new(0xffff_8000_0000_0000).align_down(1u64 << 48),
+            VirtAddr::new(0)
+        );
+    }
+
+    #[test]
+    #[should_panic]
+    fn test_virt_addr_align_up_overflow() {
+        VirtAddr::new(0xffff_ffff_ffff_ffff).align_up(2u64);
+    }
+
+    #[test]
+    #[should_panic]
+    fn test_phys_addr_align_up_overflow() {
+        PhysAddr::new(0x000f_ffff_ffff_ffff).align_up(2u64);
+    }
 }

src/instructions/segmentation.rs

@@ -9,7 +9,7 @@ use crate::{
 use core::arch::asm;
 
 macro_rules! get_reg_impl {
-    ($name:literal, $asm_get:ident) => {
+    ($name:literal) => {
         fn get_reg() -> SegmentSelector {
             let segment: u16;
             unsafe {
@@ -21,9 +21,9 @@ macro_rules! get_reg_impl {
 }
 
 macro_rules! segment_impl {
-    ($type:ty, $name:literal, $asm_get:ident, $asm_load:ident) => {
+    ($type:ty, $name:literal) => {
         impl Segment for $type {
-            get_reg_impl!($name, $asm_get);
+            get_reg_impl!($name);
 
             unsafe fn set_reg(sel: SegmentSelector) {
                 unsafe {
@@ -35,7 +35,7 @@ macro_rules! segment_impl {
 }
 
 macro_rules! segment64_impl {
-    ($type:ty, $name:literal, $base:ty, $asm_rd:ident, $asm_wr:ident) => {
+    ($type:ty, $name:literal, $base:ty) => {
         impl Segment64 for $type {
             const BASE: Msr = <$base>::MSR;
             fn read_base() -> VirtAddr {
@@ -56,7 +56,7 @@ macro_rules! segment64_impl {
 }
 
 impl Segment for CS {
-    get_reg_impl!("cs", x86_64_asm_get_cs);
+    get_reg_impl!("cs");
 
     /// Note this is special since we cannot directly move to [`CS`]; x86 requires the instruction
     /// pointer and [`CS`] to be set at the same time. To do this, we push the new segment selector
@@ -82,13 +82,13 @@ impl Segment for CS {
     }
 }
 
-segment_impl!(SS, "ss", x86_64_asm_get_ss, x86_64_asm_load_ss);
-segment_impl!(DS, "ds", x86_64_asm_get_ds, x86_64_asm_load_ds);
-segment_impl!(ES, "es", x86_64_asm_get_es, x86_64_asm_load_es);
-segment_impl!(FS, "fs", x86_64_asm_get_fs, x86_64_asm_load_fs);
-segment64_impl!(FS, "fs", FsBase, x86_64_asm_rdfsbase, x86_64_asm_wrfsbase);
-segment_impl!(GS, "gs", x86_64_asm_get_gs, x86_64_asm_load_gs);
-segment64_impl!(GS, "gs", GsBase, x86_64_asm_rdgsbase, x86_64_asm_wrgsbase);
+segment_impl!(SS, "ss");
+segment_impl!(DS, "ds");
+segment_impl!(ES, "es");
+segment_impl!(FS, "fs");
+segment64_impl!(FS, "fs", FsBase);
+segment_impl!(GS, "gs");
+segment64_impl!(GS, "gs", GsBase);
 
 impl GS {
     /// Swap `KernelGsBase` MSR and `GsBase` MSR.

src/registers/segmentation.rs

@@ -6,13 +6,15 @@ use bit_field::BitField;
 use core::fmt;
 // imports for intra doc links
 #[cfg(doc)]
-use crate::registers::control::Cr4Flags;
+use crate::{
+    registers::control::Cr4Flags,
+    structures::gdt::{Descriptor, DescriptorFlags, GlobalDescriptorTable},
+};
 
 /// An x86 segment
 ///
 /// Segment registers on x86 are 16-bit [`SegmentSelector`]s, which index into
-/// the [`GlobalDescriptorTable`](crate::structures::gdt::GlobalDescriptorTable). The
-/// corresponding GDT entry is used to
+/// the [`GlobalDescriptorTable`]. The corresponding GDT entry is used to
 /// configure the segment itself. Note that most segmentation functionality is
 /// disabled in 64-bit mode. See the individual segments for more information.
 pub trait Segment {
@@ -77,6 +79,10 @@ impl SegmentSelector {
         SegmentSelector(index << 3 | (rpl as u16))
     }
 
+    /// Can be used as a selector into a non-existent segment and assigned to segment registers,
+    /// e.g. data segment register in ring 0
+    pub const NULL: Self = Self::new(0, PrivilegeLevel::Ring0);
+
     /// Returns the GDT index.
     #[inline]
     pub fn index(self) -> u16 {
@@ -107,18 +113,27 @@ impl fmt::Debug for SegmentSelector {
 
 /// Code Segment
 ///
-/// The segment base and limit are unused in 64-bit mode. Only the L (long), D
-/// (default operation size), and DPL (descriptor privilege-level) fields of the
-/// descriptor are recognized. So changing the segment register can be used to
-/// change privilege level or enable/disable long mode.
+/// While most fields in the Code-Segment [`Descriptor`] are unused in 64-bit
+/// long mode, some of them must be set to a specific value. The
+/// [`EXECUTABLE`](DescriptorFlags::EXECUTABLE),
+/// [`USER_SEGMENT`](DescriptorFlags::USER_SEGMENT), and
+/// [`LONG_MODE`](DescriptorFlags::LONG_MODE) bits must be set, while the
+/// [`DEFAULT_SIZE`](DescriptorFlags::DEFAULT_SIZE) bit must be unset.
+///
+/// The [`DPL_RING_3`](DescriptorFlags::DPL_RING_3) field can be used to change
+/// privilege level. The [`PRESENT`](DescriptorFlags::PRESENT) bit can be used
+/// to make a segment present or not present.
+///
+/// All other fields (like the segment base and limit) are ignored by the
+/// processor and setting them has no effect.
 #[derive(Debug)]
 pub struct CS;
 
 /// Stack Segment
 ///
 /// Entirely unused in 64-bit mode; setting the segment register does nothing.
 /// However, in ring 3, the SS register still has to point to a valid
-/// [`Descriptor`](crate::structures::gdt::Descriptor) (it cannot be zero). This
+/// [`Descriptor`] (it cannot be zero). This
 /// means a user-mode read/write segment descriptor must be present in the GDT.
 ///
 /// This register is also set by the `syscall`/`sysret` and

src/structures/paging/frame_alloc.rs

@@ -4,8 +4,11 @@ use crate::structures::paging::{PageSize, PhysFrame};
 
 /// A trait for types that can allocate a frame of memory.
 ///
-/// This trait is unsafe to implement because the implementer must guarantee that
-/// the `allocate_frame` method returns only unique unused frames.
+/// # Safety
+///
+/// The implementer of this trait must guarantee that the `allocate_frame`
+/// method returns only unique unused frames. Otherwise, undefined behavior
+/// may result from two callers modifying or deallocating the same frame.
 pub unsafe trait FrameAllocator<S: PageSize> {
     /// Allocate a frame of the appropriate size and return it if possible.
     fn allocate_frame(&mut self) -> Option<PhysFrame<S>>;