tss: Update documentation

src/instructions/tables.rs

@@ -70,11 +70,20 @@ pub fn sidt() -> DescriptorTablePointer {
 
 /// Load the task state register using the `ltr` instruction.
 ///
+/// Note that loading a TSS segment selector marks the corresponding TSS
+/// Descriptor in the GDT as "busy", preventing it from being loaded again
+/// (either on this CPU or another CPU). TSS structures (including Descriptors
+/// and Selectors) should generally be per-CPU. See
+/// [`tss_segment`](crate::structures::gdt::Descriptor::tss_segment)
+/// for more information.
+///
+/// Calling `load_tss` with a busy TSS selector results in a `#GP` exception.
+///
 /// ## Safety
 ///
 /// This function is unsafe because the caller must ensure that the given
-/// `SegmentSelector` points to a valid TSS entry in the GDT and that loading
-/// this TSS is safe.
+/// `SegmentSelector` points to a valid TSS entry in the GDT and that the
+/// corresponding data in the TSS is valid.
 #[inline]
 pub unsafe fn load_tss(sel: SegmentSelector) {
     unsafe {

src/structures/gdt.rs

@@ -312,6 +312,13 @@ impl Descriptor {
     }
 
     /// Creates a TSS system descriptor for the given TSS.
+    ///
+    /// While it is possible to create multiple Descriptors that point to the
+    /// same TSS, this generally isn't recommended, as the TSS usually contains
+    /// per-CPU information such as the RSP and IST pointers. Instead, there
+    /// should be exactly one TSS and one corresponding TSS Descriptor per CPU.
+    /// Then, each of these descriptors should be placed in a GDT (which can
+    /// either be global or per-CPU).
     #[inline]
     pub fn tss_segment(tss: &'static TaskStateSegment) -> Descriptor {
         use self::DescriptorFlags as Flags;