Document methods and move them into kernel cpu folder

2 files changed, 86 insertions, 21 deletions

diff --git a/arch/x86_64/include/arch/context_switching/main.hpp b/arch/x86_64/include/arch/context_switching/main.hpp
index e296457..f8477ea 100644
--- a/arch/x86_64/include/arch/context_switching/main.hpp
+++ b/arch/x86_64/include/arch/context_switching/main.hpp
@@ -16,27 +16,32 @@ namespace teachos::arch::context_switching
   };
 
   /**
-   * @brief Setup GDT and IDT TODO
+   * @brief Creates the Interrupt Descriptor Table and Global Descriptor Table as a static variable the first time this
+   * method is called and update IDTR and GDTR registers values.
    *
-   * @return descriptor_tables
+   * @note Subsequent calls after the first one, will simply return the previously created tables, but not update the
+   * registers again.
+   *
+   * @return References to the statically created Interrupt Descriptor and Global Descriptor Table.
    */
   auto initialize_descriptor_tables() -> descriptor_tables;
 
   /**
-   * @brief TODO
-   *
-   * @param data_segment
-   * @param code_segment
-   * @param return_function
+   * @brief Switches from the current Kernel Mode (Level 0) to User Mode (Level 3). Will simply use predefined Segment
+   * Selectors for the User Data and User Code Segment, which are Index 3 and 4 in the GDT respectively.
    */
   auto switch_to_user_mode() -> void;
 
   /**
-   * @brief TODO
+   * @brief Switches from the current Code and Data Segment to the given Code and Data Segment.
+   *
+   * @note This method will additionally call initialize_descriptor_tables, to ensure the GDTR and IDTR have been setup
+   * correctly before attempting to switch the context. This switch is achieved using a far return, which will once
+   * executed call the given void function.
    *
-   * @param data_segment
-   * @param code_segment
-   * @param return_function
+   * @param data_segment Data Segment that the SS, DS; ES, FS and GS register will be set too.
+   * @param code_segment Code Segment that the CS register will be set too.
+   * @param return_function Function that will be called once the switch has been achieved.
    */
   auto switch_context(interrupt_descriptor_table::segment_selector data_segment,
                       interrupt_descriptor_table::segment_selector code_segment, void (*return_function)()) -> void;
diff --git a/arch/x86_64/include/arch/kernel/cpu/segment_register.hpp b/arch/x86_64/include/arch/kernel/cpu/segment_register.hpp
index d495ce6..5c77206 100644
--- a/arch/x86_64/include/arch/kernel/cpu/segment_register.hpp
+++ b/arch/x86_64/include/arch/kernel/cpu/segment_register.hpp
@@ -6,30 +6,90 @@
 namespace teachos::arch::kernel::cpu
 {
   /**
-   * @brief Clear all segment registers.
+   * @brief Clear all Data Segment registers (DS / ES / FS / GS).
    */
-  [[gnu::naked]]
-  auto reload_segment_registers() -> void;
+  auto reload_data_segment_registers() -> void;
 
   /**
-   * @brief Set the value of all segment registers. TODO
+   * @brief Updates the value of the Data Segment Register (DS), Extra Segment Register (ES), Thread-Local Storage
+   * Registers (FS / GS).
    *
-   * @param segment_selector
+   * @note The Stack Segment Register (SS) value should also be updated, but the value can not be directly set in
+   * comparsion to the other registers. This is the case because the register is used for stack management and can not
+   * be directly changed, instead this has to be done by a special instruction. Therefore
+   * validate_data_segment_registers should only be called after set_code_segment_register has been called as well.
+   *
+   * @param segment_selector Data Segment that should be loaded into the registers.
    */
-  auto set_segment_registers(context_switching::interrupt_descriptor_table::segment_selector segment_selector) -> void;
+  auto set_data_segment_registers(context_switching::interrupt_descriptor_table::segment_selector segment_selector)
+      -> void;
 
   /**
-   * @brief Returns the segment_selector in the code segment (cs) register. TODO
+   * @brief Returns the Segment Selector pointing to the Code Segment that has been loaded into the Code Segment
+   * Register (CS).
+   *
+   * @note The CS register can not be directly changed, instead a Far Return has to be executed to change it
    *
-   * @return segment_selector in the cs register
+   * @return Segment Selector pointing to the currently loaded Code Segment.
    */
   auto read_code_segment_register() -> context_switching::interrupt_descriptor_table::segment_selector;
 
   /**
-   * @brief TODO
+   * @brief Validates that all Data Segment Registers (DS / ES / FS / GS / SS) are the same as the given Data Segment
+   * and asserts and stops the application if they are not.
+   *
+   * @note This is only the case after set_code_segment_register has been executed as well, because it makes a far
+   * return that updates the SS register.
+   *
+   * @param data_segment Value that should be loaded into all Data Segment Registers.
+   */
+  auto validate_data_segment_registers(context_switching::interrupt_descriptor_table::segment_selector data_segment)
+      -> void;
+
+  /**
+   * @brief Validates that the Code Segment Register (CS) is the same as the given Code Segment
+   * and asserts and stops the application if they are not.
+   *
+   * @param code_segment Value that should be loaded into the Code Segment Register.
+   */
+  auto validate_code_segment_register(context_switching::interrupt_descriptor_table::segment_selector code_segment)
+      -> void;
+
+  /**
+   * @brief Simply forwards the call to validate_data_segment_registers and validate_code_segment_register and ensures
+   * that all Segment Registers, have been configured correctly.
+   *
+   * @note If all Segment Register have been set correctly the Context Switch using the set_code_segment_register method
+   * was successfull and the Privilege Level has been changed.
+   *
+   * @param data_segment Value that should be loaded into all Data Segment Registers.
+   * @param code_segment Value that should be loaded into the Code Segment Register.
+   */
+  auto validate_segment_registers(context_switching::interrupt_descriptor_table::segment_selector data_segment,
+                                  context_switching::interrupt_descriptor_table::segment_selector code_segment) -> void;
+
+  /**
+   * @brief Sets the value of the Code Segment Register (CS), this is achieved using a Far Return.
+   *
+   * @note The Far Return used by this method, will cause the context to switch, because we are changing from the
+   * current Code Segment and it's associated  Privilege Level to another Code Segment. The given method will then be
+   * called in the new context and it should be possible to call validate_segment_registers, with the same values
+   * without assertions if the switch was successful.
+   *
+   * To achieve this Far Return we call IRETQ, which expects the stack to be defined a certain way to achieve that we:
+   * 1. Push the Data Segment Selector
+   * 2. Push the current Stack Pointer
+   * 3. Push Eflags
+   * 4. Push Code Segment Selector
+   * 5. Push Return Address
    *
+   * @param data_segment Data Segment that should be loaded into the SS register.
+   * @param code_segment Code Segment that should be loaded into the CS register.
+   * @param address Function that we want to call in the new context created by the given Code Segment.
    */
-  auto validate_data_segment_registers() -> context_switching::interrupt_descriptor_table::segment_selector;
+  auto set_code_segment_register(context_switching::interrupt_descriptor_table::segment_selector data_segment,
+                                 context_switching::interrupt_descriptor_table::segment_selector code_segment,
+                                 uint64_t address) -> void;
 
 }  // namespace teachos::arch::kernel::cpu