release v0.15

.github/workflows/build.yml

@@ -21,7 +21,6 @@ jobs:
         rust:
           - nightly
           - 1.59
-          - 1.57
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -31,7 +30,6 @@ jobs:
           toolchain: ${{ matrix.rust }}
           override: true
       - name: Run cargo build for stable
-        if: matrix.rust != 1.57
         uses: actions-rs/cargo@v1
         with:
           command: build
@@ -42,7 +40,6 @@ jobs:
           command: build
           args: --no-default-features
       - name: Run cargo doc for stable
-        if: matrix.rust != 1.57
         uses: actions-rs/cargo@v1
         with:
           command: doc
@@ -53,7 +50,6 @@ jobs:
           command: doc
           args: --no-default-features
       - name: Run cargo test for stable
-        if: matrix.rust != 1.57
         uses: actions-rs/cargo@v1
         with:
           command: test

Cargo.toml

@@ -15,9 +15,9 @@ license = "MIT/Apache-2.0"
 name = "x86_64"
 readme = "README.md"
 repository = "https://github.com/rust-osdev/x86_64"
-version = "0.14.11"
+version = "0.15.0"
 edition = "2018"
-rust-version = "1.57" # Needed to support panic! in const fns
+rust-version = "1.59" # Needed to support inline asm and default const generics
 
 [dependencies]
 bit_field = "0.10.1"
@@ -28,17 +28,13 @@ rustversion = "1.0.5"
 [features]
 default = ["nightly", "instructions"]
 instructions = []
-nightly = ["const_fn", "step_trait", "abi_x86_interrupt"]
+nightly = [ "const_fn", "step_trait", "abi_x86_interrupt", "asm_const" ]
 abi_x86_interrupt = []
 const_fn = []
+asm_const = []
 step_trait = []
 doc_auto_cfg = []
 
-# These features are no longer used and only there for backwards compatibility.
-external_asm = []
-inline_asm = []
-doc_cfg = []
-
 [package.metadata.docs.rs]
 all-features = true
 

Changelog.md

@@ -1,10 +1,44 @@
 # Unreleased
 
+# 0.15.0 – 2024-01-14
+
+## Breaking changes
+
+- [replace software_interrupt! macro with generic function](https://github.com/rust-osdev/x86_64/pull/259)
+- [Use SegmentSelector in InterruptStackFrame](https://github.com/rust-osdev/x86_64/pull/263)
+- [add `InvalidStarSegmentSelectors` error](https://github.com/rust-osdev/x86_64/pull/317)
+- [add `PcidTooBig` error](https://github.com/rust-osdev/x86_64/pull/316)
+- [implement `Index<u8>` for IDT instead of `Index<usize>`](https://github.com/rust-osdev/x86_64/pull/319)
+- [change `cpu_flags`'s type to `RFlags`](https://github.com/rust-osdev/x86_64/pull/324)
+- [fix `load_tss` and `GlobalDescriptorTable`](https://github.com/rust-osdev/x86_64/pull/323)
+- [add an immutable getter for the level 4 page table](https://github.com/rust-osdev/x86_64/pull/327)
+- [make `Cr2::read` return a result](https://github.com/rust-osdev/x86_64/pull/335)
+- [remove `external_asm` and `inline_asm` features](https://github.com/rust-osdev/x86_64/pull/345)
+- [Allow the GDT to be of any length](https://github.com/rust-osdev/x86_64/pull/360)
+- [Remove software_interrupt! macro](https://github.com/rust-osdev/x86_64/pull/363)
+- [Remove usize trait impls](https://github.com/rust-osdev/x86_64/pull/364)
+- [Remove deprecated functions/flags](https://github.com/rust-osdev/x86_64/pull/368)
+- [VirtAddr improvements](https://github.com/rust-osdev/x86_64/pull/370)
+- [Add structures::gdt::Entry type](https://github.com/rust-osdev/x86_64/pull/380)
+- [Allow GDT to be loaded with shared reference](https://github.com/rust-osdev/x86_64/pull/381)
+- [seal off the `PageSize` trait](https://github.com/rust-osdev/x86_64/pull/404)
+
 ## New Features
 
 - [Add `HandlerFuncType` trait](https://github.com/rust-osdev/x86_64/pull/439)
 
-# 0.14.11 – 2022-09-15
+## Fixes
+
+- [fix typo in docs](https://github.com/rust-osdev/x86_64/pull/265)
+- [activate `feature(asm_const)`](https://github.com/rust-osdev/x86_64/pull/320)
+- [gdt: Check that MAX is in range](https://github.com/rust-osdev/x86_64/pull/365)
+- [fix `Page::from_page_table_indices`](https://github.com/rust-osdev/x86_64/pull/398)
+
+## Other improvements
+
+- [idt: Fixup Options structure and cleanup set_handler_fn](https://github.com/rust-osdev/x86_64/pull/226)
+
+# 0.14.11 – 2023-09-15
 
 ## New Features
 

README.md

@@ -12,11 +12,13 @@ Support for x86_64 specific instructions (e.g. TLB flush), registers (e.g. contr
 
 ## Minimum Supported Rust Version (MSRV)
 
-If no features are enabled (`--no-default-features`), Rust 1.57.0 is required.
+If no nightly features are enabled, Rust 1.59.0 is required.
+This can be done by either:
+  - `--no-default-features --features instructions`
+  - `--no-default-features`
 
-If only the `instructions` feature is enabled (`--no-default-features --features instructions`), Rust 1.59.0 is required.
-
-If the `nightly` feature or any of its sub-features is enabled, a recent nightly is required.
+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
 
@@ -37,4 +39,4 @@ useful crates in this space include:
   [`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.
+    - Works on any Rust target.

src/addr.rs

@@ -20,7 +20,7 @@ const ADDRESS_SPACE_SIZE: u64 = 0x1_0000_0000_0000;
 /// between `u64` and `usize`.
 ///
 /// On `x86_64`, only the 48 lower bits of a virtual address can be used. The top 16 bits need
-/// to be copies of bit 47, i.e. the most significant bit. Addresses that fulfil this criterium
+/// to be copies of bit 47, i.e. the most significant bit. Addresses that fulfil this criterion
 /// are called “canonical”. This type guarantees that it always represents a canonical address.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(transparent)]
@@ -60,39 +60,43 @@ impl core::fmt::Debug for VirtAddrNotValid {
 impl VirtAddr {
     /// Creates a new canonical virtual address.
     ///
-    /// This function performs sign extension of bit 47 to make the address canonical.
+    /// The provided address should already be canonical. If you want to check
+    /// whether an address is canonical, use [`try_new`](Self::try_new).
     ///
     /// ## Panics
     ///
-    /// This function panics if the bits in the range 48 to 64 contain data (i.e. are not null and no sign extension).
+    /// This function panics if the bits in the range 48 to 64 are invalid
+    /// (i.e. are not a proper sign extension of bit 47).
     #[inline]
-    pub fn new(addr: u64) -> VirtAddr {
-        Self::try_new(addr).expect(
-            "address passed to VirtAddr::new must not contain any data \
-             in bits 48 to 64",
-        )
+    pub const fn new(addr: u64) -> VirtAddr {
+        // TODO: Replace with .ok().expect(msg) when that works on stable.
+        match Self::try_new(addr) {
+            Ok(v) => v,
+            Err(_) => panic!("virtual address must be sign extended in bits 48 to 64"),
+        }
     }
 
     /// Tries to create a new canonical virtual address.
     ///
-    /// This function tries to performs sign
-    /// extension of bit 47 to make the address canonical. It succeeds if bits 48 to 64 are
-    /// either a correct sign extension (i.e. copies of bit 47) or all null. Else, an error
-    /// is returned.
-    #[inline]
-    pub fn try_new(addr: u64) -> Result<VirtAddr, VirtAddrNotValid> {
-        match addr.get_bits(47..64) {
-            0 | 0x1ffff => Ok(VirtAddr(addr)),     // address is canonical
-            1 => Ok(VirtAddr::new_truncate(addr)), // address needs sign extension
-            _ => Err(VirtAddrNotValid(addr)),
+    /// This function checks wether the given address is canonical
+    /// and returns an error otherwise. An address is canonical
+    /// if bits 48 to 64 are a correct sign
+    /// extension (i.e. copies of bit 47).
+    #[inline]
+    pub const fn try_new(addr: u64) -> Result<VirtAddr, VirtAddrNotValid> {
+        let v = Self::new_truncate(addr);
+        if v.0 == addr {
+            Ok(v)
+        } else {
+            Err(VirtAddrNotValid(addr))
         }
     }
 
     /// Creates a new canonical virtual address, throwing out bits 48..64.
     ///
-    /// This function performs sign extension of bit 47 to make the address canonical, so
-    /// bits 48 to 64 are overwritten. If you want to check that these bits contain no data,
-    /// use `new` or `try_new`.
+    /// This function performs sign extension of bit 47 to make the address
+    /// canonical, overwriting bits 48 to 64. If you want to check whether an
+    /// address is canonical, use [`new`](Self::new) or [`try_new`](Self::try_new).
     #[inline]
     pub const fn new_truncate(addr: u64) -> VirtAddr {
         // By doing the right shift as a signed operation (on a i64), it will
@@ -123,11 +127,7 @@ impl VirtAddr {
     }
 
     /// Creates a virtual address from the given pointer
-    // cfg(target_pointer_width = "32") is only here for backwards
-    // compatibility: Earlier versions of this crate did not have any `cfg()`
-    // on this function. At least for 32- and 64-bit we know the `as u64` cast
-    // doesn't truncate.
-    #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
+    #[cfg(target_pointer_width = "64")]
     #[inline]
     pub fn from_ptr<T: ?Sized>(ptr: *const T) -> Self {
         Self::new(ptr as *const () as u64)
@@ -320,23 +320,6 @@ impl AddAssign<u64> for VirtAddr {
     }
 }
 
-#[cfg(target_pointer_width = "64")]
-impl Add<usize> for VirtAddr {
-    type Output = Self;
-    #[inline]
-    fn add(self, rhs: usize) -> Self::Output {
-        self + rhs as u64
-    }
-}
-
-#[cfg(target_pointer_width = "64")]
-impl AddAssign<usize> for VirtAddr {
-    #[inline]
-    fn add_assign(&mut self, rhs: usize) {
-        self.add_assign(rhs as u64)
-    }
-}
-
 impl Sub<u64> for VirtAddr {
     type Output = Self;
     #[inline]
@@ -352,23 +335,6 @@ impl SubAssign<u64> for VirtAddr {
     }
 }
 
-#[cfg(target_pointer_width = "64")]
-impl Sub<usize> for VirtAddr {
-    type Output = Self;
-    #[inline]
-    fn sub(self, rhs: usize) -> Self::Output {
-        self - rhs as u64
-    }
-}
-
-#[cfg(target_pointer_width = "64")]
-impl SubAssign<usize> for VirtAddr {
-    #[inline]
-    fn sub_assign(&mut self, rhs: usize) {
-        self.sub_assign(rhs as u64)
-    }
-}
-
 impl Sub<VirtAddr> for VirtAddr {
     type Output = u64;
     #[inline]
@@ -583,23 +549,6 @@ impl AddAssign<u64> for PhysAddr {
     }
 }
 
-#[cfg(target_pointer_width = "64")]
-impl Add<usize> for PhysAddr {
-    type Output = Self;
-    #[inline]
-    fn add(self, rhs: usize) -> Self::Output {
-        self + rhs as u64
-    }
-}
-
-#[cfg(target_pointer_width = "64")]
-impl AddAssign<usize> for PhysAddr {
-    #[inline]
-    fn add_assign(&mut self, rhs: usize) {
-        self.add_assign(rhs as u64)
-    }
-}
-
 impl Sub<u64> for PhysAddr {
     type Output = Self;
     #[inline]
@@ -615,23 +564,6 @@ impl SubAssign<u64> for PhysAddr {
     }
 }
 
-#[cfg(target_pointer_width = "64")]
-impl Sub<usize> for PhysAddr {
-    type Output = Self;
-    #[inline]
-    fn sub(self, rhs: usize) -> Self::Output {
-        self - rhs as u64
-    }
-}
-
-#[cfg(target_pointer_width = "64")]
-impl SubAssign<usize> for PhysAddr {
-    #[inline]
-    fn sub_assign(&mut self, rhs: usize) {
-        self.sub_assign(rhs as u64)
-    }
-}
-
 impl Sub<PhysAddr> for PhysAddr {
     type Output = u64;
     #[inline]

src/instructions/interrupts.rs

@@ -139,12 +139,19 @@ pub fn int3() {
 
 /// Generate a software interrupt by invoking the `int` instruction.
 ///
-/// This currently needs to be a macro because the `int` argument needs to be an
-/// immediate. This macro will be replaced by a generic function when support for
-/// const generics is implemented in Rust.
-#[macro_export]
-macro_rules! software_interrupt {
-    ($x:expr) => {{
-        asm!("int {id}", id = const $x, options(nomem, nostack));
-    }};
+/// ## Safety
+///
+/// Invoking an arbitrary interrupt is unsafe. It can cause your system to
+/// crash if you invoke a double-fault (#8) or machine-check (#18) exception.
+/// It can also cause memory/register corruption depending on the interrupt
+/// implementation (if it expects values/pointers to be passed in registers).
+#[cfg(feature = "asm_const")]
+#[cfg_attr(
+    feature = "doc_cfg",
+    doc(cfg(any(feature = "nightly", feature = "asm_const")))
+)]
+pub unsafe fn software_interrupt<const NUM: u8>() {
+    unsafe {
+        asm!("int {num}", num = const NUM, options(nomem, nostack));
+    }
 }