Xen devel - Jun 2012 - [PATCH] 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.





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

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

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

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.

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.

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.