ACPICA: Comment/format update, no functional change.
Add some additional commenting the the public acpixf.h file.
Signed-off-by: Bob Moore <robert.moore@intel.com>
Signed-off-by: Lv Zheng <lv.zheng@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
diff --git a/include/acpi/acpixf.h b/include/acpi/acpixf.h
index 2d074ba..b3b2108 100644
--- a/include/acpi/acpixf.h
+++ b/include/acpi/acpixf.h
@@ -55,11 +55,17 @@
extern u8 acpi_gbl_permanent_mmap;
-/*
- * Ensure that the globals are actually defined and initialized only once.
+/*****************************************************************************
*
- * The use of these macros allows a single list of globals (here) in order
- * to simplify maintenance of the code.
+ * Macros used for ACPICA globals and configuration
+ *
+ ****************************************************************************/
+
+/*
+ * Ensure that global variables are defined and initialized only once.
+ *
+ * The use of these macros allows for a single list of globals (here)
+ * in order to simplify maintenance of the code.
*/
#ifdef DEFINE_ACPI_GLOBALS
#define ACPI_GLOBAL(type,name) \
@@ -81,8 +87,11 @@
#endif
#endif
-/* ACPICA prototypes */
-
+/*
+ * These macros configure the various ACPICA interfaces. They are
+ * useful for generating stub inline functions for features that are
+ * configured out of the current kernel or ACPICA application.
+ */
#ifndef ACPI_EXTERNAL_RETURN_STATUS
#define ACPI_EXTERNAL_RETURN_STATUS(prototype) \
prototype;
@@ -108,16 +117,14 @@
prototype;
#endif
-/* Public globals, available from outside ACPICA subsystem */
-
/*****************************************************************************
*
- * Runtime configuration (static defaults that can be overriden at runtime)
+ * Public globals and runtime configuration options
*
****************************************************************************/
/*
- * Enable "slack" in the AML interpreter? Default is FALSE, and the
+ * Enable "slack mode" of the AML interpreter? Default is FALSE, and the
* interpreter strictly follows the ACPI specification. Setting to TRUE
* allows the interpreter to ignore certain errors and/or bad AML constructs.
*
@@ -234,16 +241,34 @@
ACPI_INIT_GLOBAL(u32, acpi_dbg_layer, 0);
/*
- * Globals that are publically available
+ * Other miscellaneous globals
*/
-ACPI_GLOBAL(u32, acpi_current_gpe_count);
ACPI_GLOBAL(struct acpi_table_fadt, acpi_gbl_FADT);
+ACPI_GLOBAL(u32, acpi_current_gpe_count);
ACPI_GLOBAL(u8, acpi_gbl_system_awake_and_running);
+/*****************************************************************************
+ *
+ * ACPICA public interface configuration.
+ *
+ * Interfaces that are configured out of the ACPICA build are replaced
+ * by inlined stubs by default.
+ *
+ ****************************************************************************/
+
/*
- * Hardware-reduced prototypes. All interfaces that use these macros will
- * be configured out of the ACPICA build if the ACPI_REDUCED_HARDWARE flag
+ * Hardware-reduced prototypes (default: Not hardware reduced).
+ *
+ * All ACPICA hardware-related interfaces that use these macros will be
+ * configured out of the ACPICA build if the ACPI_REDUCED_HARDWARE flag
* is set to TRUE.
+ *
+ * Note: This static build option for reduced hardware is intended to
+ * reduce ACPICA code size if desired or necessary. However, even if this
+ * option is not specified, the runtime behavior of ACPICA is dependent
+ * on the actual FADT reduced hardware flag (HW_REDUCED_ACPI). If set,
+ * the flag will enable similar behavior -- ACPICA will not attempt
+ * to access any ACPI-relate hardware (SCI, GPEs, Fixed Events, etc.)
*/
#if (!ACPI_REDUCED_HARDWARE)
#define ACPI_HW_DEPENDENT_RETURN_STATUS(prototype) \
@@ -268,9 +293,11 @@
#endif /* !ACPI_REDUCED_HARDWARE */
/*
- * Error-message prototypes. All interfaces that use these macros will
- * be configured out of the ACPICA build if the ACPI_NO_ERROR_MESSAGE flag
- * is defined.
+ * Error message prototypes (default: error messages enabled).
+ *
+ * All interfaces related to error and warning messages
+ * will be configured out of the ACPICA build if the
+ * ACPI_NO_ERROR_MESSAGE flag is defined.
*/
#ifndef ACPI_NO_ERROR_MESSAGES
#define ACPI_MSG_DEPENDENT_RETURN_VOID(prototype) \
@@ -283,9 +310,11 @@
#endif /* ACPI_NO_ERROR_MESSAGES */
/*
- * Debugging-output prototypes. All interfaces that use these macros will
- * be configured out of the ACPICA build if the ACPI_DEBUG_OUTPUT flag is
- * not defined.
+ * Debugging output prototypes (default: no debug output).
+ *
+ * All interfaces related to debug output messages
+ * will be configured out of the ACPICA build unless the
+ * ACPI_DEBUG_OUTPUT flag is defined.
*/
#ifdef ACPI_DEBUG_OUTPUT
#define ACPI_DBG_DEPENDENT_RETURN_VOID(prototype) \
@@ -297,6 +326,12 @@
#endif /* ACPI_DEBUG_OUTPUT */
+/*****************************************************************************
+ *
+ * ACPICA public interface prototypes
+ *
+ ****************************************************************************/
+
/*
* Initialization
*/