[Xen-devel] [PATCH to X86 PV MMU Wiki v2] Expand the bootup section to include ELF and memory layout

[Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>]

v2: Integrate Ian's comments.

Signed-of-by: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>
diff --git a/intro.txt b/intro.txt
index 8a16f92..fc80ef6 100644
--- a/intro.txt
+++ b/intro.txt
@@ -339,6 +339,173 @@ into the page table base register but will not be 
explicitly pinned.
 The initial virtual and pseudo-physical layout of a new guest is
 described 
[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday
 here].
 
+
+When guest has started, the kernel image is read and the ELF (PT_NOTE) program 
is
+parsed.The hypervisor looks in the .note sections
+for the 'Xen' NULL terminated notes. The description fields contain the
+required information to find out: where the kernel expects its virtual base 
address,
+what type of hypervisor it can work with, certain features the kernel image
+can support, and the location of the hypercall page. There are two variants of 
this:
+
+; a). A â.note.Xenâ section in ELF header conforming to the ELF PT_NOTE format.
+The PT_NOTE header is described in 
[http://www.netbsd.org/docs/kernel/elf-notes.html]
+and in [http://www.sco.com/developers/gabi/latest/contents.html]
+
+The type field (Name, Desc, Type) are of the ELF specification. The specific
+type values and the description is defined by Xen.
+
+This structure is a 4-byte aligned structure. First section is an numerical
+key (aligned to 4 bytes); followed by either a string or a numerical value
+(again, aligned to 4 bytes). The values can up to any length, if the key is
+assumed to a string. If it is a numerical value, it is a long
+(64-bit value - which means 8 bytes).
+
+For example this XEN_ELFNOTE_XEN_VERSION (5) with the value of "xen-3.0":
+
+  04000000 08000000 05000000 58656e00 78656e2d 332e3000 ........Xen.xen-3.0
+
+Using read-elf would print out as a eight-byte length value with type 5:
+
+  Xen                  0x00000008      Unknown note type: (0x00000005)
+
+; b). The legacy ASCIIZ string with all of the keys concatenated. Each key
+being a string and the equal sign with the value also being an string
+(numeric values are typed as hexadecimal strings). The delimiter is a comma.
+The key can be up to 32 characters and the value up to 128 characters.
+For example:
+
+       
GUEST_OS=Mini-OS,XEN_VER=xen-3.0,VIRT_BASE=0x0,ELF_PADDR_OFFSET=0x0,HYPERCALL_PAGE=0x2,LOADER=generic
+
+
+The legacy should not be used as it has limited values that can
+be used and the specification is frozen.
+
+The parameters and its purpose are explained in
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,elfnote.h.html#incontents_elfnote
 here].
+
+And the XEN_ELF_FEATURES values are explained in
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,features.h.html#incontents_elfnote_features
 here].
+
+For example, if the ELF values were as so:
+
+{| border="1" cellpadding="2" cellspacing="0"
+ | Name of Xen ELF entry
+ | Contents
+ |-
+ | XEN_ELFNOTE_GUEST_OS (6)
+ | linux
+ |-
+ | XEN_ELFNOTE_GUEST_VERSION (7)
+ | 2.6
+ |-
+ | XEN_ELFNOTE_XEN_VERSION (5)
+ | xen-3.0
+ |-
+ | XEN_ELFNOTE_VIRT_BASE (3)
+ | 0xffffffff80000000
+ |-
+ | XEN_ELFNOTE_ENTRY (1)
+ | 0xffffffff81899200
+ |-
+ | XEN_ELFNOTE_HYPERCALL_PAGE (2)
+ | 0xffffffff81001000
+ |-
+ | XEN_ELFNOTE_FEATURES (10)
+ | !writable_page_tables|pae_pgdir_above_4gb
+ |-
+ | XEN_ELFNOTE_PAE_MODE (9)
+ | yes
+ |-
+ | XEN_ELFNOTE_LOADER (8)
+ | generic
+ |-
+ | XEN_ELFNOTE_SUSPEND_CANCEL (14)
+ | 1
+ |-
+ | XEN_ELFNOTE_HV_START_LOW
+ | 0xffff800000000000
+ |-
+ | XEN_ELFNOTE_PADDR_OFFSET
+ | 0
+ |}
+
+With that setup, the hypervisor constructs an initial page table that spans the
+region from virtual start address up (0xffffffff80000000) to the end of the
+p2m map.
+
+Using that ELF program header information, the hypervisor (or toolstack)
+constructs the domain with the appropiately located data. This ELF data
+is used to construct a guest which is laid out as enumerated in this
+header:
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday]
+
+NOTE: This is an example of a 64-bit guest and not part of the ABI.
+
+{| border="1" cellpadding="2" cellspacing="0"
+ | Page Frame (PFN)
+ | Virtual Address
+ | contents
+ |-
+ | 0x0
+ | 0xffffffff80000000
+ | location of 
[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday_shared
 struct shared_info]. The 3.d entry (start_info_t) contains the machine address 
of this structure.
+ |-
+ | 0x1000
+ | 0xffffffff81000000
+ | location of the kernel
+ |-
+ | 0x1001
+ | 0xffffffff81001000
+ | location of the hypercall within the kernel
+ |-
+ | 0x1E3E
+ | 0xffffffff81e3e000
+ | ramdisk (NOTE: This is an example and the kernel size or ramdisk will 
differ)
+ |-
+ | 0xFC69
+ | 0xffffffff8fc69000
+ | (NOTE): This is an example and based on the size of the kernel and ramdisk 
and will differ). phys2mach (P2M) - an array of machine frame numbers. The 
total size of this array is dependent on the nr_pages in
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday
 struct start_info]
+and the architecture of the guest (each entry is four bytes
+under 32-bit kernels and eight bytes under 64-bit kernels).
+ |-
+ | 0xFCE9
+ | 0xffffffff8fce9000
+ | location of
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday
 start_info structure]
+ |-
+ | 0xFCEA
+ | 0xffffffff8fcea000
+ | location of
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,xs_wire.h.html#incontents_xenstore_struct
 XenStore structure].
+Also refer to http://xenbits.xen.org/docs/unstable/misc/xenstore.txt
+ |-
+ | 0xFCEB
+ | 0xffffffff8fceb000
+ | Depending on the type of the guest (initial domain or subsequent domains), 
it can either be the
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday_dom0_console
 dom0_vga_console_info structure]
+or 
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,console.h.html
 XenConsole structure].
+The parameters defining this location are in the
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday
 start_info structure]
+ |-
+ | 0xFCEC
+ | 0xffffffff8fcfc000
+ | bootstrap page tables. These pagetables are loaded in the guest at startup
+and cover from 0x0 up to 0xFD6f (the bootstack).
+ |-
+ | 0xFD6F
+ | 0xffffffff8fd6f000
+ | bootstrap stack.
+ |}
+
+When the guest is launched, per
+[http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#incontents_startofday]
+explanation, the register %esi contains the virtual address to the
+start_info_t (0xffffffff8fce9000), the %cr3 points to the beginning of the
+bootstrap page-tables (0xffffffff8fcfc000), and the %esp points to the
+bootstrap stack (0xffffffff8fd6f000).
+
 = Virtual Address Space =
 
 Xen enforces certain restrictions on the virtual addresses which are

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel