Document methods and move them into kernel cpu folder

5 files changed, 144 insertions, 80 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
 
diff --git a/arch/x86_64/src/context_switching/main.cpp b/arch/x86_64/src/context_switching/main.cpp
index 0f2ec93..5cac878 100644
--- a/arch/x86_64/src/context_switching/main.cpp
+++ b/arch/x86_64/src/context_switching/main.cpp
@@ -12,46 +12,6 @@ namespace teachos::arch::context_switching
 {
   namespace
   {
-
-    /**
-     * @brief Switch context into the mode defined in the segment selectors.
-     *
-     * Setup the stack IRETQ expects to switch the mode:
-     * 1. push data selector
-     * 2. push current stack pointer
-     * 3. push eflags
-     * 4. push code segment selector
-     * 5. push return address
-     *
-     * @param data_segment
-     * @param code_segment
-     * @param address
-     */
-    [[gnu::naked]]
-    auto far_return(context_switching::interrupt_descriptor_table::segment_selector data_segment,
-                    context_switching::interrupt_descriptor_table::segment_selector code_segment, uint64_t address)
-        -> void
-    {
-      asm volatile("mov %[data_segment], %%rax\n"
-                   "mov %%rax, %%ds\n"
-                   "mov %%rax, %%es\n"
-                   "mov %%rax, %%fs\n"
-                   "mov %%rax, %%gs\n"
-                   "mov %%rsp, %%rax\n"
-
-                   "push %[data_segment]\n"
-                   "push %%rax\n"
-                   "pushfq\n"
-                   "push %[code_segment]\n"
-                   "mov %[return_function], %%rax\n"
-                   "push %%rax\n"
-
-                   "iretq\n"
-                   :
-                   : [data_segment] "m"(data_segment), [code_segment] "m"(code_segment), [return_function] "r"(address)
-                   : "rax");
-    }
-
     constexpr context_switching::interrupt_descriptor_table::segment_selector USER_CODE_SEGMENT_SELECTOR{
         3U, context_switching::interrupt_descriptor_table::segment_selector::REQUEST_LEVEL_USER};
     constexpr context_switching::interrupt_descriptor_table::segment_selector USER_DATA_SEGMENT_SELECTOR{
@@ -61,6 +21,14 @@ namespace teachos::arch::context_switching
 
   auto initialize_descriptor_tables() -> descriptor_tables
   {
+    static bool initalized = false;
+    if (initalized)
+    {
+      descriptor_tables tables = {segment_descriptor_table::get_or_create_global_descriptor_table(),
+                                  interrupt_descriptor_table::get_or_create_interrupt_descriptor_table()};
+      return tables;
+    }
+
     kernel::cpu::clear_interrupt_flag();
 
     segment_descriptor_table::update_global_descriptor_table_register();
@@ -68,7 +36,7 @@ namespace teachos::arch::context_switching
 
     interrupt_descriptor_table::segment_selector segment_selector{
         1U, interrupt_descriptor_table::segment_selector::REQUEST_LEVEL_KERNEL};
-    kernel::cpu::far_pointer pointer{&kernel::cpu::reload_segment_registers, segment_selector};
+    kernel::cpu::far_pointer pointer{&kernel::cpu::reload_data_segment_registers, segment_selector};
     kernel::cpu::call(pointer);
 
     segment_descriptor_table::update_task_state_segment_register();
@@ -77,17 +45,13 @@ namespace teachos::arch::context_switching
 
     descriptor_tables tables = {segment_descriptor_table::get_or_create_global_descriptor_table(),
                                 interrupt_descriptor_table::get_or_create_interrupt_descriptor_table()};
+    initalized = true;
     return tables;
   }
 
   auto user_mode_main() -> void
   {
-    auto current_segment = kernel::cpu::read_code_segment_register();
-    exception_handling::assert(USER_CODE_SEGMENT_SELECTOR == current_segment,
-                               "[Context Switching] Context switch into user mode not successful");
-    exception_handling::assert(USER_DATA_SEGMENT_SELECTOR == kernel::cpu::validate_data_segment_registers(),
-                               "[Context Switching] Context switch into user mode not successful");
-
+    kernel::cpu::validate_segment_registers(USER_DATA_SEGMENT_SELECTOR, USER_CODE_SEGMENT_SELECTOR);
     video::vga::text::write("Successfully entered user mode!", video::vga::text::common_attributes::green_on_black);
   }
 
@@ -99,8 +63,9 @@ namespace teachos::arch::context_switching
   auto switch_context(interrupt_descriptor_table::segment_selector data_segment,
                       interrupt_descriptor_table::segment_selector code_segment, void (*return_function)()) -> void
   {
-    kernel::cpu::set_segment_registers(data_segment);
-    far_return(data_segment, code_segment, reinterpret_cast<uint64_t>(return_function));
+    (void)initialize_descriptor_tables();
+    kernel::cpu::set_data_segment_registers(data_segment);
+    kernel::cpu::set_code_segment_register(data_segment, code_segment, reinterpret_cast<uint64_t>(return_function));
   }
 
 }  // namespace teachos::arch::context_switching
diff --git a/arch/x86_64/src/kernel/cpu/segment_register.cpp b/arch/x86_64/src/kernel/cpu/segment_register.cpp
index cb367b6..44b4eff 100644
--- a/arch/x86_64/src/kernel/cpu/segment_register.cpp
+++ b/arch/x86_64/src/kernel/cpu/segment_register.cpp
@@ -6,7 +6,7 @@
 namespace teachos::arch::kernel::cpu
 {
   [[gnu::naked]]
-  auto reload_segment_registers() -> void
+  auto reload_data_segment_registers() -> void
   {
     asm volatile("xor %rax, %rax\n"
                  "mov %rax, %ss\n"
@@ -18,7 +18,8 @@ namespace teachos::arch::kernel::cpu
   }
 
   [[gnu::naked]]
-  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
   {
     asm volatile("xor %%rax, %%rax\n"
                  "mov %[input], %%ax\n"
@@ -38,7 +39,8 @@ namespace teachos::arch::kernel::cpu
     return current_value;
   }
 
-  auto validate_data_segment_registers() -> context_switching::interrupt_descriptor_table::segment_selector
+  auto validate_data_segment_registers(context_switching::interrupt_descriptor_table::segment_selector data_segment)
+      -> void
   {
     context_switching::interrupt_descriptor_table::segment_selector ss;
     context_switching::interrupt_descriptor_table::segment_selector ds;
@@ -54,10 +56,46 @@ namespace teachos::arch::kernel::cpu
         "mov %%gs, %[gs_output]\n"
         : [ss_output] "=r"(ss), [ds_output] "=r"(ds), [es_output] "=r"(es), [fs_output] "=r"(fs), [gs_output] "=r"(gs));
 
-    auto result = ss == ds && ss == es && ss == fs && ss == gs;
+    auto result = (ss == ds && ss == es && ss == fs && ss == gs);
     exception_handling::assert(result, "[Segment Register] Values in data register are not the same.");
+    result = (ss == data_segment);
+    exception_handling::assert(
+        result, "[Segment Register] Expected Data Segment is not the same as the value in the Stack Segment register.");
+  }
+
+  auto validate_code_segment_register(context_switching::interrupt_descriptor_table::segment_selector code_segment)
+      -> void
+  {
+    auto const cs = read_code_segment_register();
+    exception_handling::assert(
+        cs == code_segment,
+        "[Segment Register] Expected Code Segment is not the same as the value in 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
+  {
+    validate_data_segment_registers(data_segment);
+    validate_code_segment_register(code_segment);
+  }
+
+  [[gnu::naked]]
+  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
+  {
+    asm volatile("mov %%rsp, %%rax\n"
+                 "push %[data_segment]\n"
+                 "push %%rax\n"
+                 "pushfq\n"
+                 "push %[code_segment]\n"
+                 "mov %[return_function], %%rax\n"
+                 "push %%rax\n"
 
-    return ss;
+                 "iretq\n"
+                 :
+                 : [data_segment] "m"(data_segment), [code_segment] "m"(code_segment), [return_function] "r"(address)
+                 : "rax");
   }
 
 }  // namespace teachos::arch::kernel::cpu
diff --git a/arch/x86_64/src/kernel/main.cpp b/arch/x86_64/src/kernel/main.cpp
index b69064d..05c879e 100644
--- a/arch/x86_64/src/kernel/main.cpp
+++ b/arch/x86_64/src/kernel/main.cpp
@@ -61,11 +61,7 @@ namespace teachos::arch::kernel
     // stack_overflow_test(0);
 
     memory::heap::global_heap_allocator::register_heap_allocator(memory::heap::heap_allocator_type::LINKED_LIST);
-
-    heap_test();
-
-    decltype(auto) descriptor_tables = context_switching::initialize_descriptor_tables();
-    (void)descriptor_tables;
+    // heap_test();
 
     context_switching::switch_to_user_mode();
   }