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

[Ian Campbell <Ian.Campbell@citrix.com>]

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.
> 
> 
>