[PATCH, v2] x86-64/EFI: document building and usage

[PATCH, v2] x86-64/EFI: document building and usage

[Jan Beulich]

Signed-off-by: Jan Beulich <jbeulich@suse.com>

---
v2: Switch to using markdown as suggested by Ian Campbell.
    Also document obvious config file options, as also suggested by Ian.

--- /dev/null
+++ b/docs/misc/efi.markdown
@@ -0,0 +1,79 @@
+Building xen.efi requires gcc 4.5.x or above (4.6.x or newer recommended, as
+4.5.x was probably never really tested for this purpose) and binutils 2.22 or
+newer. Additionally, the binutils build must be configured to include support
+for the x86_64-pep emulation (i.e. `--enable-targets=x86_64-pep` or an option
+of equivalent effect should be passed to the configure script).
+
+Once built, `make install-xen` can place the resulting binary directly into
+the EFI boot partition, provided `EFI_VENDOR` is set in the environment (and
+`EFI_MOUNTPOINT` is overridden as needed, should the default of `/boot/efi` not
+match your system).
+
+The binary itself will require a configuration file (names with the `.efi`
+extension of the binary's name replaced by `.cfg`, and - until an existing
+file is found - trailing name components dropped at `.`, `-`, and `_`
+separators will be tried) to be present in the same directory as the binary.
+(To illustrate the name handling, a binary named `xen-4.2-unstable.efi` would
+try `xen-4.2-unstable.cfg`, `xen-4.2.cfg`, `xen-4.cfg`, and `xen.cfg` in
+order.) One can override this with a command line option (`-cfg=<filename>`).
+
+The configuration file consists of one or more sections headed by a section
+name enclosed in square brackets, with individual values specified in each
+section. A section named `[global]` is treated specially to allow certain
+settings to apply to all other sections (or to provide defaults for certain
+settings in case individual sections don't specify them). A typical file would
+thus look like this (`#` serving as comment character):
+
+    **************************example begin******************************
+
+    [global]
+    default=sle11sp2
+    
+    [sle11sp2]
+    options=console=vga,com1 com1=57600 loglvl=all noreboot
+    kernel=vmlinuz-3.0.31-0.4-xen ignore_loglevel #earlyprintk=xen
+    ramdisk=initrd-3.0.31-0.4-xen
+
+    **************************example end********************************
+
+The individual values used here are:
+
+###`default=<name>`
+
+Specifies the section to use for booting, if none was specified on the command
+line; only meaningful in the `[global]` section. This isn't required; if
+absent, section headers will be ignored and for each value looked for the
+first instance within the file will be used.
+
+###`options=<text>`
+
+Specifies the options passed to the hypervisor, see [Xen Hypervisor Command
+Line Options](xen-command-line.html).
+
+###`kernel=<filename>[ <options>]`
+
+Specifies the Dom0 kernel binary and the options to pass to it.
+
+###`ramdisk=<filename>`
+
+Specifies a Linux-style initial RAM disk image to load.
+
+Other values to specify are:
+
+###`video=gfx-<xres>[x<yres>[x<depth>]]`
+
+Specifies a video mode to select if available. In case of problems, the
+`-basevideo` command line option can be used to skip altering video modes.
+
+###`xsm=<filename>`
+
+Specifies an XSM module to load.
+
+###`ucode=<filename>`
+
+Specifies a CPU microcode blob to load.
+
+Filenames must be specified relative to the location of the EFI binary.
+
+Extra options to be passed to Xen can also be specified on the command line,
+following a `--` separator option.

[PATCH] x86-64/EFI: document building and usage

[Jan Beulich]

[-- Attachment #1: Type: text/plain, Size: 2612 bytes --]

Signed-off-by: Jan Beulich <jbeulich@suse.com>

--- /dev/null
+++ b/docs/misc/efi.txt
@@ -0,0 +1,52 @@
+Building xen.efi requires gcc 4.5.x or above (4.6.x or newer recommended, as
+4.5.x was probably never really tested for this purpose) and binutils 2.22 or
+newer. Additionally, the binutils build must be configured to include support
+for the x86_64-pep emulation (i.e. --enable-targets=x86_64-pep or an option of
+equivalent effect should be passed to the configure script).
+
+Once built, "make install-xen" can place the resulting binary directly int
+the EFI boot partition, provided EFI_VENDOR is set (and EFI_MOUNTPOINT is
+overridden as needed, should the default of /boot/efi not match the target
+system).
+
+The binary itself will require a configuration file (names with the .efi
+extension of the binary's name replaced by .cfg, and - until an existing file
+is found - trailing name components dropped at '.', '-', and '_' separators
+will be tried) to be present in the same directory as the binary. (To
+illustrate the name handling, a binary named xen-4.2-unstable.efi would try
+xen-4.2-unstable.cfg, xen-4.2.cfg, xen-4.cfg, and xen.cfg in order.) One can
+override this with a command line option ("-cfg=<filename>").
+
+The configuration file consists of one or more sections headed by a section
+name enclosed in square brackets, with individual values specified in each
+section. A section named [global] is treated specially to allow certain
+settings to apply to all other sections (or to provide defaults for certain
+settings in case individual sections don't specify them). A typical file would
+thus look like this ('#' serving as comment character):
+
+**************************example begin******************************
+[global]
+default=sle11sp2
+
+[sle11sp2]
+options=console=vga,com1 com1=57600 loglvl=all noreboot
+kernel=vmlinuz-3.0.31-0.4-xen ignore_loglevel #earlyprintk=xen
+ramdisk=initrd-3.0.31-0.4-xen
+**************************example end********************************
+
+Other values to specify are
+
+video=gfx-<xres>[x<yres>[x<depth>]]
+(specifying a video mode to select if available; in case of problems the
+"-basevideo" command line option can be used to skip altering video modes)
+
+xsm=<filename>
+(specifying an XSM module to load)
+
+ucode=<filename>
+(specifying a CPU microcode blob to load)
+
+Filenames must be specified relative to the location of the EFI binary.
+
+Extra options to be passed to Xen can also be specified on the command line,
+following a "--" separator option.




[-- Attachment #2: EFI-build-doc.patch --]
[-- Type: text/plain, Size: 2649 bytes --]

x86-64/EFI: document building and usage

Signed-off-by: Jan Beulich <jbeulich@suse.com>

--- /dev/null
+++ b/docs/misc/efi.txt
@@ -0,0 +1,52 @@
+Building xen.efi requires gcc 4.5.x or above (4.6.x or newer recommended, as
+4.5.x was probably never really tested for this purpose) and binutils 2.22 or
+newer. Additionally, the binutils build must be configured to include support
+for the x86_64-pep emulation (i.e. --enable-targets=x86_64-pep or an option of
+equivalent effect should be passed to the configure script).
+
+Once built, "make install-xen" can place the resulting binary directly int
+the EFI boot partition, provided EFI_VENDOR is set (and EFI_MOUNTPOINT is
+overridden as needed, should the default of /boot/efi not match the target
+system).
+
+The binary itself will require a configuration file (names with the .efi
+extension of the binary's name replaced by .cfg, and - until an existing file
+is found - trailing name components dropped at '.', '-', and '_' separators
+will be tried) to be present in the same directory as the binary. (To
+illustrate the name handling, a binary named xen-4.2-unstable.efi would try
+xen-4.2-unstable.cfg, xen-4.2.cfg, xen-4.cfg, and xen.cfg in order.) One can
+override this with a command line option ("-cfg=<filename>").
+
+The configuration file consists of one or more sections headed by a section
+name enclosed in square brackets, with individual values specified in each
+section. A section named [global] is treated specially to allow certain
+settings to apply to all other sections (or to provide defaults for certain
+settings in case individual sections don't specify them). A typical file would
+thus look like this ('#' serving as comment character):
+
+**************************example begin******************************
+[global]
+default=sle11sp2
+
+[sle11sp2]
+options=console=vga,com1 com1=57600 loglvl=all noreboot
+kernel=vmlinuz-3.0.31-0.4-xen ignore_loglevel #earlyprintk=xen
+ramdisk=initrd-3.0.31-0.4-xen
+**************************example end********************************
+
+Other values to specify are
+
+video=gfx-<xres>[x<yres>[x<depth>]]
+(specifying a video mode to select if available; in case of problems the
+"-basevideo" command line option can be used to skip altering video modes)
+
+xsm=<filename>
+(specifying an XSM module to load)
+
+ucode=<filename>
+(specifying a CPU microcode blob to load)
+
+Filenames must be specified relative to the location of the EFI binary.
+
+Extra options to be passed to Xen can also be specified on the command line,
+following a "--" separator option.

[-- Attachment #3: Type: text/plain, Size: 126 bytes --]

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

Re: [PATCH] x86-64/EFI: document building and usage

[Ian Campbell]

On Wed, 2012-06-20 at 08:36 +0100, Jan Beulich wrote:
> Signed-off-by: Jan Beulich <jbeulich@suse.com>

The text looks fine to me, thanks. One comment inline below.

Did you consider using markdown syntax to get a somewhat formatted HTML
output? You'd basically just need to s/.txt/.markdown/ and tweak things
a bit to use the markdown syntax (which is designed to mostly follow the
sorts of ASCII typographical conventions which people use anyway).

http://daringfireball.net/projects/markdown/

> --- /dev/null
> +++ b/docs/misc/efi.txt
> @@ -0,0 +1,52 @@
> +Building xen.efi requires gcc 4.5.x or above (4.6.x or newer recommended, as
> +4.5.x was probably never really tested for this purpose) and binutils 2.22 or
> +newer. Additionally, the binutils build must be configured to include support
> +for the x86_64-pep emulation (i.e. --enable-targets=x86_64-pep or an option of
> +equivalent effect should be passed to the configure script).
> +
> +Once built, "make install-xen" can place the resulting binary directly int
> +the EFI boot partition, provided EFI_VENDOR is set (and EFI_MOUNTPOINT is
> +overridden as needed, should the default of /boot/efi not match the target
> +system).
> +
> +The binary itself will require a configuration file (names with the .efi
> +extension of the binary's name replaced by .cfg, and - until an existing file
> +is found - trailing name components dropped at '.', '-', and '_' separators
> +will be tried) to be present in the same directory as the binary. (To
> +illustrate the name handling, a binary named xen-4.2-unstable.efi would try
> +xen-4.2-unstable.cfg, xen-4.2.cfg, xen-4.cfg, and xen.cfg in order.) One can
> +override this with a command line option ("-cfg=<filename>").
> +
> +The configuration file consists of one or more sections headed by a section
> +name enclosed in square brackets, with individual values specified in each
> +section. A section named [global] is treated specially to allow certain
> +settings to apply to all other sections (or to provide defaults for certain
> +settings in case individual sections don't specify them). A typical file would
> +thus look like this ('#' serving as comment character):
> +
> +**************************example begin******************************
> +[global]
> +default=sle11sp2
> +
> +[sle11sp2]
> +options=console=vga,com1 com1=57600 loglvl=all noreboot
> +kernel=vmlinuz-3.0.31-0.4-xen ignore_loglevel #earlyprintk=xen
> +ramdisk=initrd-3.0.31-0.4-xen
> +**************************example end********************************
> +
> +Other values to specify are

As well as "Other values" I think you need to document the ones above as
well.

> +
> +video=gfx-<xres>[x<yres>[x<depth>]]
> +(specifying a video mode to select if available; in case of problems the
> +"-basevideo" command line option can be used to skip altering video modes)
> +
> +xsm=<filename>
> +(specifying an XSM module to load)
> +
> +ucode=<filename>
> +(specifying a CPU microcode blob to load)
> +
> +Filenames must be specified relative to the location of the EFI binary.
> +
> +Extra options to be passed to Xen can also be specified on the command line,
> +following a "--" separator option.
> 
> 
> 

Re: [PATCH] x86-64/EFI: document building and usage

[Jan Beulich]

>>> On 20.06.12 at 13:35, Ian Campbell <Ian.Campbell@citrix.com> wrote:
> On Wed, 2012-06-20 at 08:36 +0100, Jan Beulich wrote:
>> Signed-off-by: Jan Beulich <jbeulich@suse.com>
> 
> The text looks fine to me, thanks. One comment inline below.
> 
> Did you consider using markdown syntax to get a somewhat formatted HTML
> output? You'd basically just need to s/.txt/.markdown/ and tweak things
> a bit to use the markdown syntax (which is designed to mostly follow the
> sorts of ASCII typographical conventions which people use anyway).
> 
> http://daringfireball.net/projects/markdown/ 

I didn't consider this, but I can certainly convert it if that's what
is preferred these days.

>> +**************************example begin******************************
>> +[global]
>> +default=sle11sp2
>> +
>> +[sle11sp2]
>> +options=console=vga,com1 com1=57600 loglvl=all noreboot
>> +kernel=vmlinuz-3.0.31-0.4-xen ignore_loglevel #earlyprintk=xen
>> +ramdisk=initrd-3.0.31-0.4-xen
>> +**************************example end********************************
>> +
>> +Other values to specify are
> 
> As well as "Other values" I think you need to document the ones above as
> well.

Hmm, I would think anyone half way familiar with Xen can interpret
the meaning of the four ones used above without extra explanation.
I don't intend this small piece of text to be a reference document,
but just an aid to people (having got tired of individuals contacting
me namely about how to build xen.efi, despite all the information
being available already - just scattered around).

Jan

Re: [PATCH] x86-64/EFI: document building and usage

[Ian Campbell]

On Wed, 2012-06-20 at 12:56 +0100, Jan Beulich wrote:
> >>> On 20.06.12 at 13:35, Ian Campbell <Ian.Campbell@citrix.com> wrote:
> > On Wed, 2012-06-20 at 08:36 +0100, Jan Beulich wrote:
> >> Signed-off-by: Jan Beulich <jbeulich@suse.com>
> > 
> > The text looks fine to me, thanks. One comment inline below.
> > 
> > Did you consider using markdown syntax to get a somewhat formatted HTML
> > output? You'd basically just need to s/.txt/.markdown/ and tweak things
> > a bit to use the markdown syntax (which is designed to mostly follow the
> > sorts of ASCII typographical conventions which people use anyway).
> > 
> > http://daringfireball.net/projects/markdown/ 
> 
> I didn't consider this, but I can certainly convert it if that's what
> is preferred these days.

I think it's generally preferred for new stuff if the author is willing
(i.e. we'd still rather have .txt than nothing)

> >> +**************************example begin******************************
> >> +[global]
> >> +default=sle11sp2
> >> +
> >> +[sle11sp2]
> >> +options=console=vga,com1 com1=57600 loglvl=all noreboot
> >> +kernel=vmlinuz-3.0.31-0.4-xen ignore_loglevel #earlyprintk=xen
> >> +ramdisk=initrd-3.0.31-0.4-xen
> >> +**************************example end********************************
> >> +
> >> +Other values to specify are
> > 
> > As well as "Other values" I think you need to document the ones above as
> > well.
> 
> Hmm, I would think anyone half way familiar with Xen can interpret
> the meaning of the four ones used above without extra explanation.

The problem is more those which aren't familiar with Xen who think they
want to deploy it using EFI, for whatever reason.

> I don't intend this small piece of text to be a reference document,
> but just an aid to people (having got tired of individuals contacting
> me namely about how to build xen.efi, despite all the information
> being available already - just scattered around).

Sure. Documenting those three options will help with that too, won't it?
I'd expect that getting pestered by those who can't figure that sort of
thing out would be doubly annoying!

I don't think it'll take more than a line to document each one, a link
to http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html might
be useful too.

Re: [PATCH] x86-64/EFI: document building and usage

[Ian Jackson]

Ian Campbell writes ("Re: [Xen-devel] [PATCH] x86-64/EFI: document building and usage"):
> On Wed, 2012-06-20 at 12:56 +0100, Jan Beulich wrote:
> > I didn't consider this, but I can certainly convert it if that's what
> > is preferred these days.
> 
> I think it's generally preferred for new stuff if the author is willing
> (i.e. we'd still rather have .txt than nothing)

I'm not sure we want to let the best be the enemy of the good.

Shouldn't we commit this as-is and perhaps update it to markdown
later ?

Ian.

Re: [PATCH] x86-64/EFI: document building and usage [and 2 more messages]

[Ian Jackson]

Ian Jackson writes ("Re: [Xen-devel] [PATCH] x86-64/EFI: document building and usage"):
> I'm not sure we want to let the best be the enemy of the good.
> 
> Shouldn't we commit this as-is and perhaps update it to markdown
> later ?

Ah never mind, just seen v2.

Ian.

Re: [PATCH, v2] x86-64/EFI: document building and usage

[Keir Fraser]

On 20/06/2012 14:03, "Jan Beulich" <JBeulich@suse.com> wrote:

> Signed-off-by: Jan Beulich <jbeulich@suse.com>

Acked-by: Keir Fraser <keir@xen.org>

> ---
> v2: Switch to using markdown as suggested by Ian Campbell.
>     Also document obvious config file options, as also suggested by Ian.
> 
> --- /dev/null
> +++ b/docs/misc/efi.markdown
> @@ -0,0 +1,79 @@
> +Building xen.efi requires gcc 4.5.x or above (4.6.x or newer recommended, as
> +4.5.x was probably never really tested for this purpose) and binutils 2.22 or
> +newer. Additionally, the binutils build must be configured to include support
> +for the x86_64-pep emulation (i.e. `--enable-targets=x86_64-pep` or an option
> +of equivalent effect should be passed to the configure script).
> +
> +Once built, `make install-xen` can place the resulting binary directly into
> +the EFI boot partition, provided `EFI_VENDOR` is set in the environment (and
> +`EFI_MOUNTPOINT` is overridden as needed, should the default of `/boot/efi`
> not
> +match your system).
> +
> +The binary itself will require a configuration file (names with the `.efi`
> +extension of the binary's name replaced by `.cfg`, and - until an existing
> +file is found - trailing name components dropped at `.`, `-`, and `_`
> +separators will be tried) to be present in the same directory as the binary.
> +(To illustrate the name handling, a binary named `xen-4.2-unstable.efi` would
> +try `xen-4.2-unstable.cfg`, `xen-4.2.cfg`, `xen-4.cfg`, and `xen.cfg` in
> +order.) One can override this with a command line option (`-cfg=<filename>`).
> +
> +The configuration file consists of one or more sections headed by a section
> +name enclosed in square brackets, with individual values specified in each
> +section. A section named `[global]` is treated specially to allow certain
> +settings to apply to all other sections (or to provide defaults for certain
> +settings in case individual sections don't specify them). A typical file
> would
> +thus look like this (`#` serving as comment character):
> +
> +    **************************example begin******************************
> +
> +    [global]
> +    default=sle11sp2
> +    
> +    [sle11sp2]
> +    options=console=vga,com1 com1=57600 loglvl=all noreboot
> +    kernel=vmlinuz-3.0.31-0.4-xen ignore_loglevel #earlyprintk=xen
> +    ramdisk=initrd-3.0.31-0.4-xen
> +
> +    **************************example end********************************
> +
> +The individual values used here are:
> +
> +###`default=<name>`
> +
> +Specifies the section to use for booting, if none was specified on the
> command
> +line; only meaningful in the `[global]` section. This isn't required; if
> +absent, section headers will be ignored and for each value looked for the
> +first instance within the file will be used.
> +
> +###`options=<text>`
> +
> +Specifies the options passed to the hypervisor, see [Xen Hypervisor Command
> +Line Options](xen-command-line.html).
> +
> +###`kernel=<filename>[ <options>]`
> +
> +Specifies the Dom0 kernel binary and the options to pass to it.
> +
> +###`ramdisk=<filename>`
> +
> +Specifies a Linux-style initial RAM disk image to load.
> +
> +Other values to specify are:
> +
> +###`video=gfx-<xres>[x<yres>[x<depth>]]`
> +
> +Specifies a video mode to select if available. In case of problems, the
> +`-basevideo` command line option can be used to skip altering video modes.
> +
> +###`xsm=<filename>`
> +
> +Specifies an XSM module to load.
> +
> +###`ucode=<filename>`
> +
> +Specifies a CPU microcode blob to load.
> +
> +Filenames must be specified relative to the location of the EFI binary.
> +
> +Extra options to be passed to Xen can also be specified on the command line,
> +following a `--` separator option.
> 
> 
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org
> http://lists.xen.org/xen-devel