Cleanup

kernel/src/thor_acpi.cpp

@@ -27,12 +27,19 @@ extern "C" {
 
 // Initialization
 
+/*!
+ * \brief Initialize the OSL
+ */
 ACPI_STATUS AcpiOsInitialize(){
     //Nothing to initialize
 
     return AE_OK;
 }
 
+
+/*!
+ * \brief Terminate the OSL
+ */
 ACPI_STATUS AcpiOsTerminate(){
     //Nothing to terminate
 
@@ -41,16 +48,25 @@ ACPI_STATUS AcpiOsTerminate(){
 
 // Overriding of ACPI
 
+/*!
+ * \brief Override a predefined ACPI object
+ */
 ACPI_STATUS AcpiOsPredefinedOverride(const ACPI_PREDEFINED_NAMES* /*PredefinedObject*/, ACPI_STRING* new_value){
     *new_value = nullptr;
     return AE_OK;
 }
 
+/*!
+ * \brief Override an ACPI table
+ */
 ACPI_STATUS AcpiOsTableOverride(ACPI_TABLE_HEADER* /*ExistingTable*/, ACPI_TABLE_HEADER** new_table){
     *new_table = nullptr;
     return AE_OK;
 }
 
+/*!
+ * \brief Override a physical ACPI table
+ */
 ACPI_STATUS AcpiOsPhysicalTableOverride(ACPI_TABLE_HEADER* /*ExistingTable*/, ACPI_PHYSICAL_ADDRESS* new_address, UINT32* new_table_length){
     *new_address = 0;
     *new_table_length = 0;
@@ -59,16 +75,25 @@ ACPI_STATUS AcpiOsPhysicalTableOverride(ACPI_TABLE_HEADER* /*ExistingTable*/, AC
 
 // Dynamic allocation
 
+/*!
+ * \brief Allocate dynamic memory on the heap of the given size.
+ */
 void* AcpiOsAllocate(ACPI_SIZE size){
     return kalloc::k_malloc(size);
 }
 
+/*!
+ * \brief Release dynamic memory from the heap.
+ */
 void AcpiOsFree(void* p){
     kalloc::k_free(p);
 }
 
 // terminal
 
+/*!
+ * \brief Print something to terminal
+ */
 void AcpiOsPrintf(const char* format, ...){
     va_list va;
     va_start(va, format);
@@ -78,10 +103,16 @@ void AcpiOsPrintf(const char* format, ...){
     va_end(va);
 }
 
+/*!
+ * \brief Print something to terminal
+ */
 void AcpiOsVprintf(const char* format, va_list va){
     printf(format, va);
 }
 
+/*!
+ * \brief Called by the ACPI debugger
+ */
 ACPI_STATUS AcpiOsSignal(UINT32 function, void* info){
     // This should never happen
     if(!info){
@@ -112,12 +143,26 @@ ACPI_STATUS AcpiOsSignal(UINT32 function, void* info){
 
 // Scheduling
 
+/*!
+ * \brief Return the current thread id
+ */
 ACPI_THREAD_ID AcpiOsGetThreadId(){
     return scheduler::get_pid();
 }
 
-//TODO Need a real micro seconds clock
+/*
+ * \brief Sleep the given number of milliseconds
+ */
+void AcpiOsSleep(UINT64 ms){
+    scheduler::sleep_ms(ms);
+}
+
+/*!
+ * \brief Active sleep for the given number of microseconds
+ */
 void AcpiOsStall(UINT32 us){
+    //TODO Need a real micro seconds clock
+
     auto ticks = timer::ticks();
     auto wait = 1 + us / 1000;
 
@@ -130,10 +175,9 @@ void AcpiOsStall(UINT32 us){
     }
 }
 
-void AcpiOsSleep(UINT64 ms){
+/*!
-    scheduler::sleep_ms(ms);
+ * \brief Execute the given function in a new process
-}
+ */
-
 ACPI_STATUS AcpiOsExecute(ACPI_EXECUTE_TYPE /*type*/, ACPI_OSD_EXEC_CALLBACK function, void* context){
     auto* user_stack = new char[scheduler::user_stack_size];
     auto* kernel_stack = new char[scheduler::kernel_stack_size];
@@ -144,13 +188,13 @@ ACPI_STATUS AcpiOsExecute(ACPI_EXECUTE_TYPE /*type*/, ACPI_OSD_EXEC_CALLBACK fun
     scheduler::queue_system_process(process.pid);
 }
 
-//TODO This should be done much more precise
-// and should be real timestamp not an uptime timestamp
-
 /*!
  * \brief Returns the system time in 100 nanoseconds units
  */
 UINT64 AcpiOsGetTimer(){
+    //TODO This should be done much more precise
+    // and should be real timestamp not an uptime timestamp
+
     return timer::seconds() * 10000000;
 }
 
@@ -163,6 +207,9 @@ void AcpiOsWaitEventsComplete(){
 
 // ACPI
 
+/*!
+ * \brief Returns the physical address of the ACPI Root
+ */
 ACPI_PHYSICAL_ADDRESS AcpiOsGetRootPointer(){
     ACPI_PHYSICAL_ADDRESS  root_pointer;
     root_pointer = 0;
@@ -172,6 +219,9 @@ ACPI_PHYSICAL_ADDRESS AcpiOsGetRootPointer(){
 
 // Paging
 
+/*!
+ * \brief Map physical memory to a virtual address
+ */
 void* AcpiOsMapMemory(ACPI_PHYSICAL_ADDRESS phys, ACPI_SIZE length){
     size_t pages = (length + paging::PAGE_SIZE - 1) & ~(paging::PAGE_SIZE - 1);
 
@@ -190,6 +240,9 @@ void* AcpiOsMapMemory(ACPI_PHYSICAL_ADDRESS phys, ACPI_SIZE length){
     return reinterpret_cast<void*>(virt + (phys & ~(paging::PAGE_SIZE - 1)));
 }
 
+/*!
+ * \brief Unmap physical memory from a virtual address
+ */
 void AcpiOsUnmapMemory(void* virt_aligned_raw, ACPI_SIZE length){
     size_t pages = (length + paging::PAGE_SIZE - 1) & ~(paging::PAGE_SIZE - 1);
 
@@ -204,6 +257,9 @@ void AcpiOsUnmapMemory(void* virt_aligned_raw, ACPI_SIZE length){
 
 #if (ACPI_MUTEX_TYPE != ACPI_BINARY_SEMAPHORE)
 
+/*!
+ * \brief Create a mutex
+ */
 ACPI_STATUS AcpiOsCreateMutex(ACPI_MUTEX* handle){
     auto* lock = new mutex<false>();
 
@@ -214,12 +270,18 @@ ACPI_STATUS AcpiOsCreateMutex(ACPI_MUTEX* handle){
     return AE_OK;
 }
 
+/*!
+ * \brief Delete a mutex
+ */
 void AcpiOsDeleteMutex(ACPI_MUTEX handle){
     auto* lock = static_cast<mutex<false>*>(handle);
 
     delete lock;
 }
 
+/*!
+ * \brief Acquire a mutex
+ */
 ACPI_STATUS AcpiOsAcquireMutex(ACPI_MUTEX handle, UINT16 Timeout){
     auto* lock = static_cast<mutex<false>*>(handle);
 
@@ -228,6 +290,9 @@ ACPI_STATUS AcpiOsAcquireMutex(ACPI_MUTEX handle, UINT16 Timeout){
     return AE_OK;
 }
 
+/*!
+ * \brief Release a mutex
+ */
 void AcpiOsReleaseMutex(ACPI_MUTEX handle){
     auto* lock = static_cast<mutex<false>*>(handle);
 
@@ -236,6 +301,9 @@ void AcpiOsReleaseMutex(ACPI_MUTEX handle){
 
 #endif
 
+/*!
+ * \brief Create a semaphore
+ */
 ACPI_STATUS AcpiOsCreateSemaphore(UINT32 /*maxUnits*/, UINT32 initialUnits, ACPI_SEMAPHORE* handle){
     auto* lock = new semaphore();
 
@@ -246,6 +314,9 @@ ACPI_STATUS AcpiOsCreateSemaphore(UINT32 /*maxUnits*/, UINT32 initialUnits, ACPI
     return AE_OK;
 }
 
+/*!
+ * \brief Delete a semaphore
+ */
 ACPI_STATUS AcpiOsDeleteSemaphore(ACPI_SEMAPHORE handle){
     auto* lock = static_cast<semaphore*>(handle);
 
@@ -254,6 +325,9 @@ ACPI_STATUS AcpiOsDeleteSemaphore(ACPI_SEMAPHORE handle){
     return AE_OK;
 }
 
+/*!
+ * \brief Wait a semaphore
+ */
 ACPI_STATUS AcpiOsWaitSemaphore(ACPI_SEMAPHORE handle, UINT32 units, UINT16 /*timeout*/){
     auto* lock = static_cast<semaphore*>(handle);
 
@@ -264,6 +338,9 @@ ACPI_STATUS AcpiOsWaitSemaphore(ACPI_SEMAPHORE handle, UINT32 units, UINT16 /*ti
     return AE_OK;
 }
 
+/*!
+ * \brief Signal a semaphore
+ */
 ACPI_STATUS AcpiOsSignalSemaphore(ACPI_SEMAPHORE handle, UINT32 units){
     auto* lock = static_cast<semaphore*>(handle);
 
@@ -272,6 +349,9 @@ ACPI_STATUS AcpiOsSignalSemaphore(ACPI_SEMAPHORE handle, UINT32 units){
     return AE_OK;
 }
 
+/*!
+ * \brief Create an interrupt spinlock
+ */
 ACPI_STATUS AcpiOsCreateLock(ACPI_SPINLOCK *handle){
     auto* lock = new int_lock();
 
@@ -280,12 +360,18 @@ ACPI_STATUS AcpiOsCreateLock(ACPI_SPINLOCK *handle){
     return AE_OK;
 }
 
+/*!
+ * \brief Delete an interrupt spinlock
+ */
 void AcpiOsDeleteLock(ACPI_HANDLE handle){
     auto* lock = static_cast<semaphore*>(handle);
 
     delete lock;
 }
 
+/*!
+ * \brief Acquire an interrupt spinlock
+ */
 ACPI_CPU_FLAGS AcpiOsAcquireLock(ACPI_SPINLOCK handle){
     auto* lock = static_cast<semaphore*>(handle);
 
@@ -294,6 +380,9 @@ ACPI_CPU_FLAGS AcpiOsAcquireLock(ACPI_SPINLOCK handle){
     return 0;
 }
 
+/*!
+ * \brief Release an interrupt spinlock
+ */
 void AcpiOsReleaseLock(ACPI_SPINLOCK handle, ACPI_CPU_FLAGS /*flags*/){
     auto* lock = static_cast<semaphore*>(handle);
 
@@ -302,6 +391,9 @@ void AcpiOsReleaseLock(ACPI_SPINLOCK handle, ACPI_CPU_FLAGS /*flags*/){
 
 // Input / Output
 
+/*!
+ * \brief Read an hardware
+ */
 ACPI_STATUS AcpiOsReadPort(ACPI_IO_ADDRESS port, UINT32* value, UINT32 width){
     switch (width) {
         case 8:
@@ -323,6 +415,9 @@ ACPI_STATUS AcpiOsReadPort(ACPI_IO_ADDRESS port, UINT32* value, UINT32 width){
     return AE_OK;
 }
 
+/*!
+ * \brief Write an hardware
+ */
 ACPI_STATUS AcpiOsWritePort(ACPI_IO_ADDRESS port, UINT32 value, UINT32 width){
     switch (width) {
         case 8:
@@ -344,6 +439,9 @@ ACPI_STATUS AcpiOsWritePort(ACPI_IO_ADDRESS port, UINT32 value, UINT32 width){
     return AE_OK;
 }
 
+/*!
+ * \brief Read a physical memory location
+ */
 ACPI_STATUS AcpiOsReadMemory(ACPI_PHYSICAL_ADDRESS Address, UINT64 *value, UINT32 width){
     ACPI_STATUS rv = AE_OK;
 
@@ -378,6 +476,9 @@ ACPI_STATUS AcpiOsReadMemory(ACPI_PHYSICAL_ADDRESS Address, UINT64 *value, UINT3
     return rv;
 }
 
+/*!
+ * \brief Write a physical memory location
+ */
 ACPI_STATUS AcpiOsWriteMemory(ACPI_PHYSICAL_ADDRESS Address, UINT64 value, UINT32 width){
     ACPI_STATUS rv = AE_OK;