Merge pull request #382 from rust-osdev/docs

Update comment and docs

README.md

@@ -17,3 +17,24 @@ If no features are enabled (`--no-default-features`), Rust 1.57.0 is required.
 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.
+
+## 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/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>>;