x86/boot/e820: Clean up and improve comments in asm/e820/types.h

Do some common-sense cleanups:

 - standardize on the kernel coding style consistently

 - tabulate definitions consistently

 - extend and clarify various descriptions

 - fix speling

 - update the header guard name according to the new position

 - etc.

No change in functionality.

Cc: Alex Thorlton <athorlton@sgi.com>
Cc: Andy Lutomirski <luto@kernel.org>
Cc: Borislav Petkov <bp@alien8.de>
Cc: Brian Gerst <brgerst@gmail.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Denys Vlasenko <dvlasenk@redhat.com>
Cc: H. Peter Anvin <hpa@zytor.com>
Cc: Huang, Ying <ying.huang@intel.com>
Cc: Josh Poimboeuf <jpoimboe@redhat.com>
Cc: Juergen Gross <jgross@suse.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Paul Jackson <pj@sgi.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Rafael J. Wysocki <rjw@sisk.pl>
Cc: Tejun Heo <tj@kernel.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Wei Yang <richard.weiyang@gmail.com>
Cc: Yinghai Lu <yinghai@kernel.org>
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Ingo Molnar <mingo@kernel.org>

1 files changed, 53 insertions, 31 deletions

diff --git a/arch/x86/include/asm/e820/types.h b/arch/x86/include/asm/e820/types.h
index 9dafe59cf6e2..cfa8f4a19b5d 100644
--- a/arch/x86/include/asm/e820/types.h
+++ b/arch/x86/include/asm/e820/types.h
@@ -1,18 +1,30 @@
-#ifndef _UAPI_ASM_X86_E820_H
-#define _UAPI_ASM_X86_E820_H
-#define E820MAP	0x2d0		/* our map */
-#define E820MAX	128		/* number of entries in E820MAP */
+#ifndef _ASM_E820_TYPES_H
+#define _ASM_E820_TYPES_H
+
+/* Our map: */
+#define E820MAP			0x2d0
+
+/* The maximum number of entries in E820MAP: */
+#define E820MAX			128
 
 /*
- * Legacy E820 BIOS limits us to 128 (E820MAX) nodes due to the
- * constrained space in the zeropage.  If we have more nodes than
- * that, and if we've booted off EFI firmware, then the EFI tables
- * passed us from the EFI firmware can list more nodes.  Size our
- * internal memory map tables to have room for these additional
- * nodes, based on up to three entries per node for which the
- * kernel was built: MAX_NUMNODES == (1 << CONFIG_NODES_SHIFT),
- * plus E820MAX, allowing space for the possible duplicate E820
- * entries that might need room in the same arrays, prior to the
+ * The legacy E820 BIOS limits us to 128 (E820MAX) nodes due to the
+ * constrained space in the zeropage.
+ *
+ * On large systems we can easily have thousands of nodes with RAM,
+ * which cannot be fit into so few entries - so we have a mechanism
+ * to extend the e820 table size at build-time, via the E820_X_MAX
+ * define below.
+ *
+ * ( Those extra entries are enumerated via the EFI memory map, not
+ *   via the legacy zeropage mechanism. )
+ *
+ * Size our internal memory map tables to have room for these additional
+ * entries, based on a heuristic calculation: up to three entries per
+ * NUMA node, plus E820MAX for some extra space.
+ *
+ * This allows for bootstrap/firmware quirks such as possible duplicate
+ * E820 entries that might need room in the same arrays, prior to the
  * call to sanitize_e820_map() to remove duplicates.  The allowance
  * of three memory map entries per node is "enough" entries for
  * the initial hardware platform motivating this mechanism to make
@@ -20,19 +32,19 @@
  * to allow more than three entries per node or otherwise refine
  * this size.
  */
-
 #ifndef __KERNEL__
-#define E820_X_MAX E820MAX
+# define E820_X_MAX		E820MAX
 #endif
 
-#define E820NR	0x1e8		/* # entries in E820MAP */
+/* Number of entries in E820MAP: */
+#define E820NR			0x1e8
 
-#define E820_RAM	1
-#define E820_RESERVED	2
-#define E820_ACPI	3
-#define E820_NVS	4
-#define E820_UNUSABLE	5
-#define E820_PMEM	7
+#define E820_RAM		1
+#define E820_RESERVED		2
+#define E820_ACPI		3
+#define E820_NVS		4
+#define E820_UNUSABLE		5
+#define E820_PMEM		7
 
 /*
  * This is a non-standardized way to represent ADR or NVDIMM regions that
@@ -43,7 +55,7 @@
  *   but newer versions switched to 12 as 6 was assigned differently.  Some
  *   time they will learn... )
  */
-#define E820_PRAM	12
+#define E820_PRAM		12
 
 /*
  * reserved RAM used by kernel itself
@@ -51,23 +63,34 @@
  * included in the S3 integrity calculation and so should not include
  * any memory that BIOS might alter over the S3 transition
  */
-#define E820_RESERVED_KERN        128
+#define E820_RESERVED_KERN	128
 
 #ifndef __ASSEMBLY__
 #include <linux/types.h>
+
+/*
+ * A single E820 map entry, describing a memory range of [addr...addr+size-1],
+ * of 'type' memory type:
+ */
 struct e820entry {
-	__u64 addr;	/* start of memory segment */
-	__u64 size;	/* size of memory segment */
-	__u32 type;	/* type of memory segment */
+	__u64 addr;
+	__u64 size;
+	__u32 type;
 } __attribute__((packed));
 
+/*
+ * The whole array of E820 entries:
+ */
 struct e820map {
 	__u32 nr_map;
 	struct e820entry map[E820_X_MAX];
 };
 
-#define ISA_START_ADDRESS	0xa0000
-#define ISA_END_ADDRESS		0x100000
+/*
+ * Various legacy ranges in physical memory:
+ */
+#define ISA_START_ADDRESS	0x000a0000
+#define ISA_END_ADDRESS		0x00100000
 
 #define BIOS_BEGIN		0x000a0000
 #define BIOS_END		0x00100000
@@ -77,5 +100,4 @@ struct e820map {
 
 #endif /* __ASSEMBLY__ */
 
-
-#endif /* _UAPI_ASM_X86_E820_H */
+#endif /* _ASM_E820_TYPES_H */