From 563082e5e117c305ca955558dd0e86928d1fd74b Mon Sep 17 00:00:00 2001
From: AlmuHS <almuhs@github.com>
Date: Thu, 3 Oct 2019 14:56:28 +0200
Subject: docs: described acpi rdsp structures

---
 i386/i386at/acpi_rsdp.h | 46 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 5 deletions(-)

diff --git a/i386/i386at/acpi_rsdp.h b/i386/i386at/acpi_rsdp.h
index c68cd6af..661d101c 100644
--- a/i386/i386at/acpi_rsdp.h
+++ b/i386/i386at/acpi_rsdp.h
@@ -31,6 +31,14 @@ struct acpi_rsdp
     uint32_t rsdt_addr;
 } __attribute__((__packed__));
 
+
+/* RSDT Entry Header 
+ * 
+ * Header which stores the descriptors of tables pointed from RDSP's Entry Field
+ * Includes the signature of the table, to identify each table
+ * 
+ * In MADT, the signature is 'APIC'
+ */ 
 struct acpi_dhdr
 {
     uint8_t signature[4];
@@ -53,36 +61,58 @@ struct acpi_rsdt
     uint32_t entry[0];
 } __attribute__((__packed__));
 
-
+//APIC table signature
 #define ACPI_APIC_SIG "APIC"
 
+//Types value for Local APIC and I/O APIC ACPI's structures
 #define ACPI_APIC_ENTRY_LAPIC  0
 #define ACPI_APIC_ENTRY_IOAPIC 1
 
+/* APIC descriptor header 
+ * Define the type of the structure (Local APIC, I/O APIC or others)
+ * Type: Local APIC (0), I/O APIC (1)
+ */
 struct acpi_apic_dhdr
 {
     uint8_t type;
     uint8_t length;
 } __attribute__((__packed__));
 
+
+/* Multiple APIC Description Table (MADT)
+ *
+ * Describes the APIC structures which exist in the machine
+ * Includes the common address where Local APIC is mapped in main memory
+ * 
+ * Entry field stores the descriptors of APIC structures
+ */
 struct acpi_apic
 {
-    struct acpi_dhdr header;
-    uint32_t lapic_addr;
+    struct acpi_dhdr header; //Header, which stores the descriptor for RDST's Entry field
+    uint32_t lapic_addr; //Local Interrupt Controller Address
     uint32_t flags;
-    struct acpi_apic_dhdr entry[0];
+    struct acpi_apic_dhdr entry[0]; //Interrupt Controller Structure 
 } __attribute__((__packed__));
 
+/* Processor Local APIC Structure
+ *
+ * Stores information about APIC ID, flags and ACPI Processor UID
+ */
 
 struct acpi_apic_lapic
 {
     struct acpi_apic_dhdr header;
-    uint8_t processor_id;
+    uint8_t processor_id; //ACPI Processor UID
     uint8_t apic_id;
     uint32_t flags;
 } __attribute__((__packed__));
 
 
+/* I/O APIC Structure 
+ *
+ * Stores information about APIC ID, and I/O APIC tables
+ */
+
 struct acpi_apic_ioapic
 {
     struct acpi_apic_dhdr header;
@@ -97,6 +127,12 @@ struct acpi_apic_ioapic
 
 int acpi_setup();
 void acpi_print_info();
+
+/* extra_setup() function:  
+ *
+ * Must be executed after configure paging
+ * Reserve Local APIC common pointer in a physical page
+ */
 int extra_setup();
 
 
-- 
cgit v1.2.3