[tip:x86/boot] x86/boot: Enumerate documentation for the x86 hardware_subarch

[tip-bot for Luis R. Rodriguez]

Commit-ID:  18c78a96239749fc4aaee84ca1eb5a8e81f2601d
Gitweb:     http://git.kernel.org/tip/18c78a96239749fc4aaee84ca1eb5a8e81f2601d
Author:     Luis R. Rodriguez <mcgrof@xxxxxxxxxx>
AuthorDate: Wed, 13 Apr 2016 17:04:31 -0700
Committer:  Ingo Molnar <mingo@xxxxxxxxxx>
CommitDate: Fri, 22 Apr 2016 10:28:59 +0200

x86/boot: Enumerate documentation for the x86 hardware_subarch

Although hardware_subarch has been in place since the x86 boot
protocol 2.07 it hasn't been used much. Enumerate current possible
values to avoid misuses and help with semantics later at boot
time should this be used further.

These enums should only ever be used by architecture x86 code,
and all that code should be well contained and compartamentalized,
clarify that as well.

Signed-off-by: Luis R. Rodriguez <mcgrof@xxxxxxxxxx>
Cc: Andy Lutomirski <luto@xxxxxxxxxxxxxx>
Cc: Borislav Petkov <bp@xxxxxxxxx>
Cc: Brian Gerst <brgerst@xxxxxxxxx>
Cc: Denys Vlasenko <dvlasenk@xxxxxxxxxx>
Cc: H. Peter Anvin <hpa@xxxxxxxxx>
Cc: Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxxx>
Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
Cc: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
Cc: andrew.cooper3@xxxxxxxxxx
Cc: andriy.shevchenko@xxxxxxxxxxxxxxx
Cc: bigeasy@xxxxxxxxxxxxx
Cc: boris.ostrovsky@xxxxxxxxxx
Cc: david.vrabel@xxxxxxxxxx
Cc: ffainelli@xxxxxxxxxx
Cc: george.dunlap@xxxxxxxxxx
Cc: glin@xxxxxxxx
Cc: jgross@xxxxxxxx
Cc: jlee@xxxxxxxx
Cc: josh@xxxxxxxxxxxxxxxx
Cc: julien.grall@xxxxxxxxxx
Cc: konrad.wilk@xxxxxxxxxx
Cc: kozerkov@xxxxxxxxxxxxx
Cc: lenb@xxxxxxxxxx
Cc: lguest@xxxxxxxxxxxxxxxx
Cc: linux-acpi@xxxxxxxxxxxxxxx
Cc: lv.zheng@xxxxxxxxx
Cc: matt@xxxxxxxxxxxxxxxxxxx
Cc: mbizon@xxxxxxxxxx
Cc: rjw@xxxxxxxxxxxxx
Cc: robert.moore@xxxxxxxxx
Cc: rusty@xxxxxxxxxxxxxxx
Cc: tiwai@xxxxxxx
Cc: toshi.kani@xxxxxx
Cc: xen-devel@xxxxxxxxxxxxxxxxxxx
Link: http://lkml.kernel.org/r/1460592286-300-2-git-send-email-mcgrof@xxxxxxxxxx
Signed-off-by: Ingo Molnar <mingo@xxxxxxxxxx>
---
 arch/x86/include/uapi/asm/bootparam.h | 41 ++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/arch/x86/include/uapi/asm/bootparam.h b/arch/x86/include/uapi/asm/bootparam.h
index 3292543..c18ce67 100644
--- a/arch/x86/include/uapi/asm/bootparam.h
+++ b/arch/x86/include/uapi/asm/bootparam.h
@@ -157,7 +157,46 @@ struct boot_params {
 	__u8  _pad9[276];				/* 0xeec */
 } __attribute__((packed));
 
-enum {
+/**
+ * enum x86_hardware_subarch - x86 hardware subarchitecture
+ *
+ * The x86 hardware_subarch and hardware_subarch_data were added as of the x86
+ * boot protocol 2.07 to help distinguish and support custom x86 boot
+ * sequences. This enum represents accepted values for the x86
+ * hardware_subarch.  Custom x86 boot sequences (not X86_SUBARCH_PC) do not
+ * have or simply *cannot* make use of natural stubs like BIOS or EFI, the
+ * hardware_subarch can be used on the Linux entry path to revector to a
+ * subarchitecture stub when needed. This subarchitecture stub can be used to
+ * set up Linux boot parameters or for special care to account for nonstandard
+ * handling of page tables.
+ *
+ * These enums should only ever be used by x86 code, and the code that uses
+ * it should be well contained and compartamentalized.
+ *
+ * KVM and Xen HVM do not have a subarch as these are expected to follow
+ * standard x86 boot entries. If there is a genuine need for "hypervisor" type
+ * that should be considered separately in the future. Future guest types
+ * should seriously consider working with standard x86 boot stubs such as
+ * the BIOS or EFI boot stubs.
+ *
+ * WARNING: this enum is only used for legacy hacks, for platform features that
+ *	    are not easily enumerated or discoverable. You should not ever use
+ *	    this for new features.
+ *
+ * @X86_SUBARCH_PC: Should be used if the hardware is enumerable using standard
+ *	PC mechanisms (PCI, ACPI) and doesn't need a special boot flow.
+ * @X86_SUBARCH_LGUEST: Used for x86 hypervisor demo, lguest
+ * @X86_SUBARCH_XEN: Used for Xen guest types which follow the PV boot path,
+ * 	which start at asm startup_xen() entry point and later jump to the C
+ * 	xen_start_kernel() entry point. Both domU and dom0 type of guests are
+ * 	currently supportd through this PV boot path.
+ * @X86_SUBARCH_INTEL_MID: Used for Intel MID (Mobile Internet Device) platform
+ *	systems which do not have the PCI legacy interfaces.
+ * @X86_SUBARCH_CE4100: Used for Intel CE media processor (CE4100) SoC for
+ * 	for settop boxes and media devices, the use of a subarch for CE4100
+ * 	is more of a hack...
+ */
+enum x86_hardware_subarch {
 	X86_SUBARCH_PC = 0,
 	X86_SUBARCH_LGUEST,
 	X86_SUBARCH_XEN,