5 files changed, 31 insertions, 35 deletions

diff --git a/include/acpi/acconfig.h b/include/acpi/acconfig.h
index 0943457e0fa5..358258ad09f8 100644
--- a/include/acpi/acconfig.h
+++ b/include/acpi/acconfig.h
@@ -138,7 +138,7 @@
 
 /* Maximum sleep allowed via Sleep() operator */
 
-#define ACPI_MAX_SLEEP                  2000    /* Two seconds */
+#define ACPI_MAX_SLEEP                  2000    /* 2000 millisec == two seconds */
 
 /* Address Range lists are per-space_id (Memory and I/O only) */
 
diff --git a/include/acpi/acpixf.h b/include/acpi/acpixf.h
index 3d88395d4d6f..defbcaa90f40 100644
--- a/include/acpi/acpixf.h
+++ b/include/acpi/acpixf.h
@@ -56,11 +56,12 @@
 extern u8 acpi_gbl_permanent_mmap;
 
 /*
- * Globals that are publicly available, allowing for
- * run time configuration
+ * Globals that are publically available
  */
+/* Runtime configuration of debug print levels */
 extern u32 acpi_dbg_level;
 extern u32 acpi_dbg_layer;
+/* ACPICA runtime options */
 extern u8 acpi_gbl_enable_interpreter_slack;
 extern u8 acpi_gbl_all_methods_serialized;
 extern u8 acpi_gbl_create_osi_method;
@@ -106,7 +107,7 @@ extern u8 acpi_gbl_reduced_hardware;	/* ACPI 5.0 */
 
 extern u32 acpi_rsdt_forced;
 /*
- * Global interfaces
+ * Initialization
  */
 acpi_status
 acpi_initialize_tables(struct acpi_table_desc *initial_storage,
@@ -124,6 +125,9 @@ acpi_status acpi_terminate(void);
 acpi_status acpi_subsystem_status(void);
 #endif
 
+/*
+ * Miscellaneous global interfaces
+ */
 ACPI_HW_DEPENDENT_RETURN_STATUS(acpi_status acpi_enable(void))
 ACPI_HW_DEPENDENT_RETURN_STATUS(acpi_status acpi_disable(void))
 
diff --git a/include/acpi/actbl1.h b/include/acpi/actbl1.h
index 280fc45b59dd..61f04c0dd5cb 100644
--- a/include/acpi/actbl1.h
+++ b/include/acpi/actbl1.h
@@ -768,7 +768,7 @@ struct acpi_madt_interrupt_source {
 
 struct acpi_madt_local_x2apic {
         struct acpi_subtable_header header;
-        u16 reserved;           /* Reserved - must be zero */
+        u16 reserved;           /* reserved - must be zero */
         u32 local_apic_id;      /* Processor x2APIC ID  */
         u32 lapic_flags;
         u32 uid;                /* ACPI processor UID */
@@ -781,14 +781,14 @@ struct acpi_madt_local_x2apic_nmi {
         u16 inti_flags;
         u32 uid;                /* ACPI processor UID */
         u8 lint;                /* LINTn to which NMI is connected */
-        u8 reserved[3];
+        u8 reserved[3];         /* reserved - must be zero */
 };
 
 /* 11: Generic Interrupt (ACPI 5.0) */
 
 struct acpi_madt_generic_interrupt {
         struct acpi_subtable_header header;
-        u16 reserved;           /* Reserved - must be zero */
+        u16 reserved;           /* reserved - must be zero */
         u32 gic_id;
         u32 uid;
         u32 flags;
diff --git a/include/acpi/actypes.h b/include/acpi/actypes.h
index 4f43f1fba132..35d4dea0bd37 100644
--- a/include/acpi/actypes.h
+++ b/include/acpi/actypes.h
@@ -595,7 +595,7 @@ typedef u32 acpi_object_type;
 
 /*
  * These are special object types that never appear in
- * a Namespace node, only in a union acpi_operand_object
+ * a Namespace node, only in an object of union acpi_operand_object
  */
 #define ACPI_TYPE_LOCAL_EXTRA           0x1C
 #define ACPI_TYPE_LOCAL_DATA            0x1D
@@ -662,7 +662,7 @@ typedef u32 acpi_event_status;
 #define ACPI_GPE_MAX                    0xFF
 #define ACPI_NUM_GPE                    256
 
-/* Actions for acpi_set_gpe_wake_mask, acpi_hw_low_set_gpe */
+/* Actions for acpi_set_gpe, acpi_gpe_wakeup, acpi_hw_low_set_gpe */
 
 #define ACPI_GPE_ENABLE                 0
 #define ACPI_GPE_DISABLE                1
diff --git a/include/acpi/platform/acenv.h b/include/acpi/platform/acenv.h
index 89cee88dd2a5..e3409b6cefbd 100644
--- a/include/acpi/platform/acenv.h
+++ b/include/acpi/platform/acenv.h
@@ -1,6 +1,6 @@
 /******************************************************************************
  *
- * Name: acenv.h - Generation environment specific items
+ * Name: acenv.h - Host and compiler configuration
  *
  *****************************************************************************/
 
@@ -60,14 +60,12 @@
  *
  *****************************************************************************/
 
+/* Linkable ACPICA library */
 #ifdef ACPI_LIBRARY
-/*
- * Note: The non-debug version of the acpi_library does not contain any
- * debug support, for minimal size. The debug version uses ACPI_FULL_DEBUG
- */
 #define ACPI_USE_LOCAL_CACHE
 #endif
 
+/* iASL configuration */
 #ifdef ACPI_ASL_COMPILER
 #define ACPI_DEBUG_OUTPUT
 #define ACPI_APPLICATION
@@ -77,6 +75,7 @@
 #define ACPI_DATA_TABLE_DISASSEMBLY
 #endif
 
+/* acpi_exec configuration. Multithreaded with full AML debugger */
 #ifdef ACPI_EXEC_APP
 #undef DEBUGGER_THREADING
 #define DEBUGGER_THREADING      DEBUGGER_SINGLE_THREADED
@@ -87,11 +86,13 @@
 #define ACPI_DBG_TRACK_ALLOCATIONS
 #endif
 
+/* Common for all ACPICA applications */
 #ifdef ACPI_APPLICATION
 #define ACPI_USE_SYSTEM_CLIBRARY
 #define ACPI_USE_LOCAL_CACHE
 #endif
 
+/* Common debug support */
 #ifdef ACPI_FULL_DEBUG
 #define ACPI_DEBUGGER
 #define ACPI_DEBUG_OUTPUT
@@ -186,9 +187,7 @@
  *
  *****************************************************************************/
 
-/*
- * Are mutexes supported by the host? default is no, use binary semaphores.
- */
+/* Type of mutex supported by host. Default is binary semaphores. */
 #ifndef ACPI_MUTEX_TYPE
 #define ACPI_MUTEX_TYPE             ACPI_BINARY_SEMAPHORE
 #endif
@@ -230,9 +229,7 @@
  * We want to keep these to a minimum.
  */
 #ifdef ACPI_USE_STANDARD_HEADERS
-/*
- * Use the standard headers from the standard locations
- */
+/* Use the standard headers from the standard locations */
 #include <stdarg.h>
 #include <stdlib.h>
 #include <string.h>
@@ -240,9 +237,7 @@
 
 #endif                          /* ACPI_USE_STANDARD_HEADERS */
 
-/*
- * We will be linking to the standard Clib functions
- */
+/* We will be linking to the standard Clib functions */
 #define ACPI_STRSTR(s1,s2)      strstr((s1), (s2))
 #define ACPI_STRCHR(s1,c)       strchr((s1), (c))
 #define ACPI_STRLEN(s)          (acpi_size) strlen((s))
@@ -274,12 +269,12 @@
  *
  *****************************************************************************/
 
- /*
-  * Use local definitions of C library macros and functions
-  * NOTE: The function implementations may not be as efficient
-  * as an inline or assembly code implementation provided by a
-  * native C library.
-  */
+/*
+ * Use local definitions of C library macros and functions. These function
+ * implementations may not be as efficient as an inline or assembly code
+ * implementation provided by a native C library, but they are functionally
+ * equivalent.
+ */
 
 #ifndef va_arg
 
@@ -288,15 +283,11 @@
 typedef char *va_list;
 #endif                          /* _VALIST */
 
-/*
- * Storage alignment properties
- */
+/* Storage alignment properties */
 #define  _AUPBND                (sizeof (acpi_native_int) - 1)
 #define  _ADNBND                (sizeof (acpi_native_int) - 1)
 
-/*
- * Variable argument list macro definitions
- */
+/* Variable argument list macro definitions */
 #define _bnd(X, bnd)            (((sizeof (X)) + (bnd)) & (~(bnd)))
 #define va_arg(ap, T)           (*(T *)(((ap) += (_bnd (T, _AUPBND))) - (_bnd (T,_ADNBND))))
 #define va_end(ap)              (void) 0
@@ -304,6 +295,7 @@ typedef char *va_list;
 
 #endif                          /* va_arg */
 
+/* Use the local (ACPICA) definitions of the clib functions */
 #define ACPI_STRSTR(s1,s2)      acpi_ut_strstr ((s1), (s2))
 #define ACPI_STRCHR(s1,c)       acpi_ut_strchr ((s1), (c))
 #define ACPI_STRLEN(s)          (acpi_size) acpi_ut_strlen ((s))