[MULTIBOOT2 DOC PATCH 01/10] multiboot2: Remove redundant if

[MULTIBOOT2 DOC PATCH 01/10] multiboot2: Remove redundant if

[Daniel Kiper]

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index 4b92918..27e5a2f 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -425,7 +425,7 @@ u32     | size              |
 
 @samp{type} is divided into 2 parts. Lower contains an identifier of contents of the rest of the tag.
 @samp{size} contains the size of tag including header fields.
-If bit @samp{0} of @samp{flags} (also known as @samp{optional}) is set if bootloader may ignore this tag if it 
+If bit @samp{0} of @samp{flags} (also known as @samp{optional}) is set bootloader may ignore this tag if it 
 lacks relevant support.
 Tags are terminated by a tag of type @samp{0} and size @samp{8}.
 
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 02/10] multiboot2: Clarify meaning of information request header tag

[Daniel Kiper]

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |   20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index 27e5a2f..a7e3584 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -443,15 +443,19 @@ u32[n]  | mbi_tag_types     |
 @end group
 @end example
 
-@samp{mbi_tag_types} is an array of u32 each one representing an information
-request
-If this tag is present and @samp{optional} is set to @samp{0} information
-conveyed by requested tag types must be present. If bootloader is unable
-to supply this information it must fail with an error
+@samp{mbi_tag_types} is an array of u32 each one representing an information request.
 
-Note: it doesn't garantee that any tags of type @samp{mbi_tag_types} will
-actually be present. E.g. on a videoless system even if you requested tag
-@samp{8} no tags of type @samp{8} will be present in mbi.
+If this tag is present and @samp{optional} is set to @samp{0} bootloader must
+support (understand meaning of) requested tag(s) and be able to provide relevant
+information to image if it is available. If bootloader do not understand meaning
+of requested tag(s) it must fail with an error. However, if it support a given
+tag(s) but information conveyed by it/them is not available bootloader can do not
+provide requested tag(s) in Multiboot information structure and proceed further.
+
+Note: Above means that there is not guarantee that any tags of type @samp{mbi_tag_types}
+will actually be present. E.g. on a videoless system even if you requested tag @samp{8}
+and bootloader support it no tags of type @samp{8} will be present in Multiboot
+information structure.
 
 
 @node Address header tag
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 03/10] multiboot2: Fix description of EFI boot services tag

[Daniel Kiper]

Without this fix multiboot2 doc build fails. Additionally,
add missing full stop at the end of sentence.

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |    7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index a7e3584..e43df93 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -358,6 +358,7 @@ executable header.
 * Address header tag::       
 * Console header tags::
 * Module alignment tag::
+* EFI boot services tag::
 
 @end menu
 
@@ -608,8 +609,8 @@ u32     | size = 8          |
 
 If this tag is present modules must be page aligned.
 
-@node EFI boot services
-@subsection EFI boot services
+@node EFI boot services tag
+@subsection EFI boot services tag
 
 @example
 @group
@@ -622,7 +623,7 @@ u32     | size = 8          |
 @end example
 
 This tag indicates that payload supports starting without
-terminating boot services
+terminating boot services.
 
 @node Machine state
 @section MIPS machine state
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 04/10] multiboot2: Add description of support for EFI boot services

[Daniel Kiper]

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |  108 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/multiboot2.h   |    2 +
 2 files changed, 108 insertions(+), 2 deletions(-)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index e43df93..1583b76 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -534,6 +534,62 @@ The physical address to which the boot loader should jump in order to
 start running the operating system.
 @end table
 
+@subsection EFI i386 entry address tag of Multiboot header
+
+@example
+@group
+        +-------------------+
+u16     | type = 8          |
+u16     | flags             |
+u32     | size              |
+u_virt  | entry_addr        |
+        +-------------------+
+@end group
+@end example
+
+All of the address fields in this tag are physical addresses.
+The meaning of each is as follows:
+
+@table @code
+
+@item entry_addr
+The physical address to which the boot loader should jump in order to
+start running EFI i386 compatible operating system code.
+@end table
+
+This tag is taken into account only on EFI i386 platforms
+when Multiboot image header contains EFI boot services tag.
+Then entry point specified in ELF header and the entry address
+tag of Multiboot header are ignored.
+
+@subsection EFI amd64 entry address tag of Multiboot header
+
+@example
+@group
+        +-------------------+
+u16     | type = 9          |
+u16     | flags             |
+u32     | size              |
+u_virt  | entry_addr        |
+        +-------------------+
+@end group
+@end example
+
+All of the address fields in this tag are physical addresses.
+The meaning of each is as follows:
+
+@table @code
+
+@item entry_addr
+The physical address to which the boot loader should jump in order to
+start running EFI amd64 compatible operating system code.
+@end table
+
+This tag is taken into account only on EFI amd64 platforms
+when Multiboot image header contains EFI boot services tag.
+Then entry point specified in ELF header and the entry address
+tag of Multiboot header are ignored.
+
 @node Console header tags
 @subsection Flags tag
 
@@ -714,12 +770,60 @@ The OS image must leave interrupts disabled until it sets up its own
 
 On EFI system boot services must be terminated.
 
+@section EFI i386 machine state with boot services enabled
+
+When the boot loader invokes the 32-bit operating system on EFI i386
+platform and EFI boot services tag together with EFI i386 entry address
+tag are present in the image Multiboot header, the machine must have the
+following state:
+
+@table @samp
+@item EAX
+Must contain the magic value @samp{0x36d76289}; the presence of this
+value indicates to the operating system that it was loaded by a
+Multiboot-compliant boot loader (e.g. as opposed to another type of
+boot loader that the operating system can also be loaded from).
+
+@item EBX
+Must contain the 32-bit physical address of the Multiboot
+information structure provided by the boot loader (@pxref{Boot
+information format}).
+@end table
+
+All other processor registers, flag bits and state are set accordingly
+to Unified Extensible Firmware Interface Specification, Version 2.6,
+section 2.3.2, IA-32 Platforms, boot services.
+
+@section EFI amd64 machine state with boot services enabled
+
+When the boot loader invokes the 64-bit operating system on EFI amd64
+platform and EFI boot services tag together with EFI amd64 entry address
+tag are present in the image Multiboot header, the machine must have the
+following state:
+
+@table @samp
+@item RAX
+Must contain the magic value @samp{0x36d76289}; the presence of this
+value indicates to the operating system that it was loaded by a
+Multiboot-compliant boot loader (e.g. as opposed to another type of
+boot loader that the operating system can also be loaded from).
+
+@item RBX
+Must contain the 64-bit physical address of the Multiboot
+information structure provided by the boot loader (@pxref{Boot
+information format}).
+@end table
+
+All other processor registers, flag bits and state are set accordingly
+to Unified Extensible Firmware Interface Specification, Version 2.6,
+section 2.3.4, x64 Platforms, boot services.
+
 @node Boot information format
 @section Boot information
 @subsection Boot information format
 
-Upon entry to the operating system, the @code{EBX} register contains the
-physical address of a @dfn{Multiboot information} data structure,
+Upon entry to the operating system, the @code{R5/EBX/RBX} register contains
+the physical address of a @dfn{Multiboot information} data structure,
 through which the boot loader communicates vital information to the
 operating system. The operating system can use or ignore any parts of
 the structure as it chooses; all information passed by the boot loader
diff --git a/doc/multiboot2.h b/doc/multiboot2.h
index 78337f5..240400d 100644
--- a/doc/multiboot2.h
+++ b/doc/multiboot2.h
@@ -69,6 +69,8 @@
 #define MULTIBOOT_HEADER_TAG_FRAMEBUFFER  5
 #define MULTIBOOT_HEADER_TAG_MODULE_ALIGN  6
 #define MULTIBOOT_HEADER_TAG_EFI_BS        7
+#define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI32  8
+#define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI64  9
 
 #define MULTIBOOT_ARCHITECTURE_I386  0
 #define MULTIBOOT_ARCHITECTURE_MIPS32  4
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 05/10] multiboot2: Add description of EFI image handle tags

[Daniel Kiper]

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |   28 ++++++++++++++++++++++++++++
 doc/multiboot2.h   |   16 ++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index 1583b76..130176a 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -1281,6 +1281,34 @@ u32     | size = 8          |
 
 This tag indicates ExitBootServices wasn't called
 
+@subsection EFI 32-bit image handle pointer
+@example
+@group
+        +-------------------+
+u32     | type = 19         |
+u32     | size = 12         |
+u32     | pointer           |
+        +-------------------+
+@end group
+@end example
+
+This tag contains pointer to EFI i386 image handle.
+Usually it is boot loader image handle.
+
+@subsection EFI 64-bit image handle pointer
+@example
+@group
+        +-------------------+
+u32     | type = 20         |
+u32     | size = 16         |
+u64     | pointer           |
+        +-------------------+
+@end group
+@end example
+
+This tag contains pointer to EFI amd64 image handle.
+Usually it is boot loader image handle.
+
 @node Examples
 @chapter Examples
 
diff --git a/doc/multiboot2.h b/doc/multiboot2.h
index 240400d..b85cb13 100644
--- a/doc/multiboot2.h
+++ b/doc/multiboot2.h
@@ -60,6 +60,8 @@
 #define MULTIBOOT_TAG_TYPE_NETWORK           16
 #define MULTIBOOT_TAG_TYPE_EFI_MMAP          17
 #define MULTIBOOT_TAG_TYPE_EFI_BS            18
+#define MULTIBOOT_TAG_TYPE_EFI32_IH          19
+#define MULTIBOOT_TAG_TYPE_EFI64_IH          20
 
 #define MULTIBOOT_HEADER_TAG_END  0
 #define MULTIBOOT_HEADER_TAG_INFORMATION_REQUEST  1
@@ -372,6 +374,20 @@ struct multiboot_tag_efi_mmap
   multiboot_uint8_t efi_mmap[0];
 }; 
 
+struct multiboot_tag_efi32_ih
+{
+  multiboot_uint32_t type;
+  multiboot_uint32_t size;
+  multiboot_uint32_t pointer;
+};
+
+struct multiboot_tag_efi64_ih
+{
+  multiboot_uint32_t type;
+  multiboot_uint32_t size;
+  multiboot_uint64_t pointer;
+};
+
 #endif /* ! ASM_FILE */
 
 #endif /* ! MULTIBOOT_HEADER */
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 06/10] multiboot2: Add description of support for relocatable images

[Daniel Kiper]

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |   56 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/multiboot2.h   |   24 ++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index 130176a..f1e0e09 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -359,6 +359,7 @@ executable header.
 * Console header tags::
 * Module alignment tag::
 * EFI boot services tag::
+* Relocatable header tag::
 
 @end menu
 
@@ -681,6 +682,47 @@ u32     | size = 8          |
 This tag indicates that payload supports starting without
 terminating boot services.
 
+@node Relocatable header tag
+@subsection Relocatable header tag
+
+@example
+@group
+        +-------------------+
+u16     | type = 10         |
+u16     | flags             |
+u32     | size = 24         |
+u32     | min_addr          |
+u32     | max_addr          |
+u32     | align             |
+u32     | preference        |
+        +-------------------+
+@end group
+@end example
+
+This tag indicates that image is relocatable.
+
+The meaning of each field is as follows:
+
+@table @code
+@item min_addr
+Lowest possible physical address at which image should be loaded.
+Boot loader cannot load any part of image below this address.
+
+@item max_addr
+Highest possible physical address at which loaded image should end.
+Boot loader cannot load any part of image above this address.
+
+@item align
+Image alignment in memory, e.g. 4096 (know on many machines as page).
+
+@item preference
+It contains load address placement suggestion for boot loader.
+Boot loader should follow it. @samp{0} means none, @samp{1} means
+load image at lowest possible address but not lower than min_addr
+and @samp{2} means load image at highest possible address but not
+higher than max_addr.
+@end table
+
 @node Machine state
 @section MIPS machine state
 
@@ -1309,6 +1351,20 @@ u64     | pointer           |
 This tag contains pointer to EFI amd64 image handle.
 Usually it is boot loader image handle.
 
+@subsection Image load base physical address
+@example
+@group
+        +-------------------+
+u32     | type = 21         |
+u32     | size = 12         |
+u32     | load_base_addr    |
+        +-------------------+
+@end group
+@end example
+
+This tag contains image load base physical address. It is
+provided only if image has relocatable header tag.
+
 @node Examples
 @chapter Examples
 
diff --git a/doc/multiboot2.h b/doc/multiboot2.h
index b85cb13..b181607 100644
--- a/doc/multiboot2.h
+++ b/doc/multiboot2.h
@@ -62,6 +62,7 @@
 #define MULTIBOOT_TAG_TYPE_EFI_BS            18
 #define MULTIBOOT_TAG_TYPE_EFI32_IH          19
 #define MULTIBOOT_TAG_TYPE_EFI64_IH          20
+#define MULTIBOOT_TAG_TYPE_LOAD_BASE_ADDR    21
 
 #define MULTIBOOT_HEADER_TAG_END  0
 #define MULTIBOOT_HEADER_TAG_INFORMATION_REQUEST  1
@@ -73,11 +74,16 @@
 #define MULTIBOOT_HEADER_TAG_EFI_BS        7
 #define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI32  8
 #define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI64  9
+#define MULTIBOOT_HEADER_TAG_RELOCATABLE  10
 
 #define MULTIBOOT_ARCHITECTURE_I386  0
 #define MULTIBOOT_ARCHITECTURE_MIPS32  4
 #define MULTIBOOT_HEADER_TAG_OPTIONAL 1
 
+#define MULTIBOOT_LOAD_PREFERENCE_NONE 0
+#define MULTIBOOT_LOAD_PREFERENCE_LOW 1
+#define MULTIBOOT_LOAD_PREFERENCE_HIGH 2
+
 #define MULTIBOOT_CONSOLE_FLAGS_CONSOLE_REQUIRED 1
 #define MULTIBOOT_CONSOLE_FLAGS_EGA_TEXT_SUPPORTED 2
 
@@ -162,6 +168,17 @@ struct multiboot_header_tag_module_align
   multiboot_uint32_t size;
 };
 
+struct multiboot_header_tag_relocatable
+{
+  multiboot_uint16_t type;
+  multiboot_uint16_t flags;
+  multiboot_uint32_t size;
+  multiboot_uint32_t min_addr;
+  multiboot_uint32_t max_addr;
+  multiboot_uint32_t align;
+  multiboot_uint32_t preference;
+};
+
 struct multiboot_color
 {
   multiboot_uint8_t red;
@@ -388,6 +405,13 @@ struct multiboot_tag_efi64_ih
   multiboot_uint64_t pointer;
 };
 
+struct multiboot_tag_load_base_addr
+{
+  multiboot_uint32_t type;
+  multiboot_uint32_t size;
+  multiboot_uint32_t load_base_addr;
+};
+
 #endif /* ! ASM_FILE */
 
 #endif /* ! MULTIBOOT_HEADER */
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 07/10] multiboot2: Say that memory maps may not be available on EFI platforms

[Daniel Kiper]

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |   11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index f1e0e09..c81b2ea 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -927,6 +927,10 @@ possible value for lower memory is 640 kilobytes. The value returned for
 upper memory is maximally the address of the first upper memory hole
 minus 1 megabyte. It is not guaranteed to be this value.
 
+This tag may not be provided by some boot loaders on EFI platforms if EFI
+boot services are enabled and available for loaded image (EFI boot services
+not terminated tag exists in Multiboot information structure).
+
 @subsection BIOS Boot device
 @example
 @group
@@ -1078,6 +1082,10 @@ indicated a reserved area.
 The map provided is guaranteed to list all standard @sc{ram} that should
 be available for normal use. This type however includes the regions occupied by kernel, mbi, segments and modules. Kernel must take care not to overwrite these regions.
 
+This tag may not be provided by some boot loaders on EFI platforms if EFI
+boot services are enabled and available for loaded image (EFI boot services
+not terminated tag exists in Multiboot information structure).
+
 @subsection Boot loader name
 @example
 @group
@@ -1310,6 +1318,9 @@ u32     | descriptor version|
 
 This tag contains EFI memory map as per EFI specification.
 
+This tag may not be provided by some boot loaders on EFI platforms if EFI
+boot services are enabled and available for loaded image (EFI boot services
+not terminated tag exists in Multiboot information structure).
 
 @subsection EFI boot services not terminated
 @example
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 08/10] multiboot2: Add C structure alignment and padding consideration section

[Daniel Kiper]

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |   17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index c81b2ea..bf02a1b 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -1384,6 +1384,7 @@ document, but are included for prospective operating system and boot
 loader writers.
 
 @menu
+* C structure alignment and padding consideration::
 * Notes on PC::                 
 * BIOS device mapping techniques::  
 * Example OS code::             
@@ -1391,6 +1392,22 @@ loader writers.
 @end menu
 
 
+@node C structure alignment and padding consideration
+@section C structure alignment and padding consideration
+
+Many C compilers try to optimize memory accesses aligning structure
+members properly. Usually they reach the goal by adding some padding.
+This is very useful thing in general. However, if you try to mix assembler
+with C or use C to implement structure low level access this behavior
+may lead, at least, to quite surprising results. Hence, compiler should
+be instructed to not optimize such accesses. Usually it is done by special
+attribute added to structure definition, e.g. GCC compatible sources use
+@samp{__attribute__ ((__packed__))} for this purpose. However, this is not
+required if it is known that its members are properly aligned and compiler
+does not do any optimization. Very good example of this is shown below in
+@file{multiboot2.h} file.
+
+
 @node Notes on PC
 @section Notes on PC
 
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 09/10] multiboot2: Add me to authors

[Daniel Kiper]

.. and properly format author list.

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 doc/multiboot.texi |    4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index bf02a1b..a25c223 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -53,7 +53,9 @@ versions.
 @titlepage
 @sp 10
 @title The Multiboot Specification version @value{VERSION}
-@author Yoshinori K. Okuji, Bryan Ford, Erich Stefan Boleyn, Kunihiro Ishiguro, Vladimir 'phcoder' Serbinenko
+@author Yoshinori K. Okuji, Bryan Ford, Erich Stefan Boleyn,
+@author Kunihiro Ishiguro, Vladimir 'phcoder' Serbinenko,
+@author Daniel Kiper
 @page
 @vskip 0pt plus 1filll
 @insertcopying
-- 
1.7.10.4


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

[MULTIBOOT2 DOC PATCH 10/10] multiboot2: Bump version to 2.0

[Daniel Kiper]

.. and add 2016 to copyright.

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
 configure.ac       |    2 +-
 doc/multiboot.texi |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/configure.ac b/configure.ac
index b11961d..585b37a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -13,7 +13,7 @@ dnl LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE
 dnl USE OF THIS SOFTWARE.
 
 AC_PREREQ(2.59)
-AC_INIT([Multiboot], [1.6], [bug-grub@gnu.org])
+AC_INIT([Multiboot], [2.0], [bug-grub@gnu.org])
 AC_CONFIG_SRCDIR([doc/multiboot.texi])
 AC_CONFIG_HEADER([config.h])
 AM_INIT_AUTOMAKE
diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index a25c223..350937f 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -20,7 +20,7 @@ Copyright @copyright{} 1995,96 Bryan Ford <baford@@cs.utah.edu>
 
 Copyright @copyright{} 1995,96 Erich Stefan Boleyn <erich@@uruk.org>
 
-Copyright @copyright{} 1999,2000,2001,2002,2005,2006,2009,2010 Free Software Foundation, Inc.
+Copyright @copyright{} 1999,2000,2001,2002,2005,2006,2009,2010,2016 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to make and distribute verbatim copies of
-- 
1.7.10.4


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

Re: [MULTIBOOT2 DOC PATCH 01/10] multiboot2: Remove redundant if

[Andrew Cooper]

On 09/06/2016 21:30, Daniel Kiper wrote:
> Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  doc/multiboot.texi |    2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index 4b92918..27e5a2f 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -425,7 +425,7 @@ u32     | size              |
>  
>  @samp{type} is divided into 2 parts. Lower contains an identifier of contents of the rest of the tag.
>  @samp{size} contains the size of tag including header fields.
> -If bit @samp{0} of @samp{flags} (also known as @samp{optional}) is set if bootloader may ignore this tag if it 
> +If bit @samp{0} of @samp{flags} (also known as @samp{optional}) is set bootloader may ignore this tag if it 

As a native English speaker, I think you want to s/if/, the/ in this
case.  Neither option currently parses.

~Andrew

>  lacks relevant support.
>  Tags are terminated by a tag of type @samp{0} and size @samp{8}.
>  


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

Re: [MULTIBOOT2 DOC PATCH 02/10] multiboot2: Clarify meaning of information request header tag

[Andrew Cooper]

On 09/06/2016 21:30, Daniel Kiper wrote:
> Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  doc/multiboot.texi |   20 ++++++++++++--------
>  1 file changed, 12 insertions(+), 8 deletions(-)
>
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index 27e5a2f..a7e3584 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -443,15 +443,19 @@ u32[n]  | mbi_tag_types     |
>  @end group
>  @end example
>  
> -@samp{mbi_tag_types} is an array of u32 each one representing an information
> -request
> -If this tag is present and @samp{optional} is set to @samp{0} information
> -conveyed by requested tag types must be present. If bootloader is unable
> -to supply this information it must fail with an error
> +@samp{mbi_tag_types} is an array of u32 each one representing an information request.

"u32's, each"

>  
> -Note: it doesn't garantee that any tags of type @samp{mbi_tag_types} will
> -actually be present. E.g. on a videoless system even if you requested tag
> -@samp{8} no tags of type @samp{8} will be present in mbi.
> +If this tag is present and @samp{optional} is set to @samp{0} bootloader must

", the bootloader"

> +support (understand meaning of) requested tag(s) and be able to provide relevant

"the requested".  I don't think you need to explain what supported
means, so I would just drop the brackets entirely.

> +information to image if it is available. If bootloader do not understand meaning

"the image".  "the bootloader does not". "the meaning".

> +of requested tag(s) it must fail with an error. However, if it support a given

"the requested".  "supports".

> +tag(s) but information conveyed by it/them is not available bootloader can do not

"a given tag(s)" is an odd way of phrasing this.  I would recommend just
"supports a given tag, but the information requested by it is".

"available, the bootloader can't provide the requested".

> +provide requested tag(s) in Multiboot information structure and proceed further.

"in the Multiboot".  What do you mean by "and proceed further" in this
case?  It also doesn't parse.  I presume you mean that it is legal for
the bootloader to not provide the requested information, but may
continue booting.

> +
> +Note: Above means that there is not guarantee that any tags of type @samp{mbi_tag_types}

"The above", "there is no guarentee"

> +will actually be present. E.g. on a videoless system even if you requested tag @samp{8}
> +and bootloader support it no tags of type @samp{8} will be present in Multiboot

"the bootloader supports it, no".  "The Multiboot".

~Andrew

> +information structure.
>  
>  
>  @node Address header tag


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

Re: [MULTIBOOT2 DOC PATCH 04/10] multiboot2: Add description of support for EFI boot services

[Andrew Cooper]

On 09/06/2016 21:30, Daniel Kiper wrote:
> Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  doc/multiboot.texi |  108 +++++++++++++++++++++++++++++++++++++++++++++++++++-
>  doc/multiboot2.h   |    2 +
>  2 files changed, 108 insertions(+), 2 deletions(-)
>
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index e43df93..1583b76 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -534,6 +534,62 @@ The physical address to which the boot loader should jump in order to
>  start running the operating system.
>  @end table
>  
> +@subsection EFI i386 entry address tag of Multiboot header
> +
> +@example
> +@group
> +        +-------------------+
> +u16     | type = 8          |
> +u16     | flags             |
> +u32     | size              |
> +u_virt  | entry_addr        |
> +        +-------------------+
> +@end group
> +@end example
> +
> +All of the address fields in this tag are physical addresses.
> +The meaning of each is as follows:
> +
> +@table @code
> +
> +@item entry_addr
> +The physical address to which the boot loader should jump in order to
> +start running EFI i386 compatible operating system code.
> +@end table
> +
> +This tag is taken into account only on EFI i386 platforms
> +when Multiboot image header contains EFI boot services tag.
> +Then entry point specified in ELF header and the entry address
> +tag of Multiboot header are ignored.
> +
> +@subsection EFI amd64 entry address tag of Multiboot header
> +
> +@example
> +@group
> +        +-------------------+
> +u16     | type = 9          |
> +u16     | flags             |
> +u32     | size              |
> +u_virt  | entry_addr        |
> +        +-------------------+
> +@end group
> +@end example
> +
> +All of the address fields in this tag are physical addresses.
> +The meaning of each is as follows:

A 64bit entry cannot possibly be a physical, as paging is mandatory.

This is clearly supposed to be the entry virtual address, but it should
not be conflated with the position of the image in RAM.  The chances of
the two being the same is very small.

> +
> +@table @code
> +
> +@item entry_addr
> +The physical address to which the boot loader should jump in order to
> +start running EFI amd64 compatible operating system code.
> +@end table
> +
> +This tag is taken into account only on EFI amd64 platforms
> +when Multiboot image header contains EFI boot services tag.
> +Then entry point specified in ELF header and the entry address
> +tag of Multiboot header are ignored.
> +
>  @node Console header tags
>  @subsection Flags tag
>  
> @@ -714,12 +770,60 @@ The OS image must leave interrupts disabled until it sets up its own
>  
>  On EFI system boot services must be terminated.
>  
> +@section EFI i386 machine state with boot services enabled
> +
> +When the boot loader invokes the 32-bit operating system on EFI i386
> +platform and EFI boot services tag together with EFI i386 entry address
> +tag are present in the image Multiboot header, the machine must have the
> +following state:
> +
> +@table @samp
> +@item EAX
> +Must contain the magic value @samp{0x36d76289}; the presence of this
> +value indicates to the operating system that it was loaded by a
> +Multiboot-compliant boot loader (e.g. as opposed to another type of

Multiboot 2, not multiboot.

> +boot loader that the operating system can also be loaded from).
> +
> +@item EBX
> +Must contain the 32-bit physical address of the Multiboot
> +information structure provided by the boot loader (@pxref{Boot
> +information format}).
> +@end table
> +
> +All other processor registers, flag bits and state are set accordingly
> +to Unified Extensible Firmware Interface Specification, Version 2.6,
> +section 2.3.2, IA-32 Platforms, boot services.
> +
> +@section EFI amd64 machine state with boot services enabled
> +
> +When the boot loader invokes the 64-bit operating system on EFI amd64
> +platform and EFI boot services tag together with EFI amd64 entry address
> +tag are present in the image Multiboot header, the machine must have the
> +following state:
> +
> +@table @samp
> +@item RAX
> +Must contain the magic value @samp{0x36d76289}; the presence of this
> +value indicates to the operating system that it was loaded by a
> +Multiboot-compliant boot loader (e.g. as opposed to another type of

Again, Multiboot 2.

> +boot loader that the operating system can also be loaded from).
> +
> +@item RBX
> +Must contain the 64-bit physical address of the Multiboot

This is surely a virtual address, unless you expect a multiboot payload
to edit its own pagetables before it can read the info structure.

> +information structure provided by the boot loader (@pxref{Boot
> +information format}).
> +@end table
> +
> +All other processor registers, flag bits and state are set accordingly
> +to Unified Extensible Firmware Interface Specification, Version 2.6,
> +section 2.3.4, x64 Platforms, boot services.
> +
>  @node Boot information format
>  @section Boot information
>  @subsection Boot information format
>  
> -Upon entry to the operating system, the @code{EBX} register contains the
> -physical address of a @dfn{Multiboot information} data structure,
> +Upon entry to the operating system, the @code{R5/EBX/RBX} register contains
> +the physical address of a @dfn{Multiboot information} data structure,

Same here.

~Andrew

>  through which the boot loader communicates vital information to the
>  operating system. The operating system can use or ignore any parts of
>  the structure as it chooses; all information passed by the boot loader
> diff --git a/doc/multiboot2.h b/doc/multiboot2.h
> index 78337f5..240400d 100644
> --- a/doc/multiboot2.h
> +++ b/doc/multiboot2.h
> @@ -69,6 +69,8 @@
>  #define MULTIBOOT_HEADER_TAG_FRAMEBUFFER  5
>  #define MULTIBOOT_HEADER_TAG_MODULE_ALIGN  6
>  #define MULTIBOOT_HEADER_TAG_EFI_BS        7
> +#define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI32  8
> +#define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI64  9
>  
>  #define MULTIBOOT_ARCHITECTURE_I386  0
>  #define MULTIBOOT_ARCHITECTURE_MIPS32  4


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

Re: [MULTIBOOT2 DOC PATCH 06/10] multiboot2: Add description of support for relocatable images

[Andrew Cooper]

On 09/06/2016 21:30, Daniel Kiper wrote:
> Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  doc/multiboot.texi |   56 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  doc/multiboot2.h   |   24 ++++++++++++++++++++++
>  2 files changed, 80 insertions(+)
>
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index 130176a..f1e0e09 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -359,6 +359,7 @@ executable header.
>  * Console header tags::
>  * Module alignment tag::
>  * EFI boot services tag::
> +* Relocatable header tag::
>  
>  @end menu
>  
> @@ -681,6 +682,47 @@ u32     | size = 8          |
>  This tag indicates that payload supports starting without
>  terminating boot services.
>  
> +@node Relocatable header tag
> +@subsection Relocatable header tag
> +
> +@example
> +@group
> +        +-------------------+
> +u16     | type = 10         |
> +u16     | flags             |
> +u32     | size = 24         |
> +u32     | min_addr          |
> +u32     | max_addr          |
> +u32     | align             |
> +u32     | preference        |
> +        +-------------------+
> +@end group
> +@end example
> +
> +This tag indicates that image is relocatable.
> +
> +The meaning of each field is as follows:
> +
> +@table @code
> +@item min_addr
> +Lowest possible physical address at which image should be loaded.
> +Boot loader cannot load any part of image below this address.

"The bootloader".

> +
> +@item max_addr
> +Highest possible physical address at which loaded image should end.
> +Boot loader cannot load any part of image above this address.

"The bootloader".

> +
> +@item align
> +Image alignment in memory, e.g. 4096 (know on many machines as page).

I would drop the qualification in brackets.  It isn't helpful to the
intended audience.

> +
> +@item preference
> +It contains load address placement suggestion for boot loader.
> +Boot loader should follow it. @samp{0} means none, @samp{1} means
> +load image at lowest possible address but not lower than min_addr
> +and @samp{2} means load image at highest possible address but not
> +higher than max_addr.
> +@end table
> +
>  @node Machine state
>  @section MIPS machine state
>  
> @@ -1309,6 +1351,20 @@ u64     | pointer           |
>  This tag contains pointer to EFI amd64 image handle.
>  Usually it is boot loader image handle.
>  
> +@subsection Image load base physical address
> +@example
> +@group
> +        +-------------------+
> +u32     | type = 21         |
> +u32     | size = 12         |
> +u32     | load_base_addr    |
> +        +-------------------+
> +@end group
> +@end example
> +
> +This tag contains image load base physical address. It is
> +provided only if image has relocatable header tag.
> +
>  @node Examples
>  @chapter Examples
>  
> diff --git a/doc/multiboot2.h b/doc/multiboot2.h
> index b85cb13..b181607 100644
> --- a/doc/multiboot2.h
> +++ b/doc/multiboot2.h
> @@ -62,6 +62,7 @@
>  #define MULTIBOOT_TAG_TYPE_EFI_BS            18
>  #define MULTIBOOT_TAG_TYPE_EFI32_IH          19
>  #define MULTIBOOT_TAG_TYPE_EFI64_IH          20
> +#define MULTIBOOT_TAG_TYPE_LOAD_BASE_ADDR    21
>  
>  #define MULTIBOOT_HEADER_TAG_END  0
>  #define MULTIBOOT_HEADER_TAG_INFORMATION_REQUEST  1
> @@ -73,11 +74,16 @@
>  #define MULTIBOOT_HEADER_TAG_EFI_BS        7
>  #define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI32  8
>  #define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI64  9
> +#define MULTIBOOT_HEADER_TAG_RELOCATABLE  10
>  
>  #define MULTIBOOT_ARCHITECTURE_I386  0
>  #define MULTIBOOT_ARCHITECTURE_MIPS32  4
>  #define MULTIBOOT_HEADER_TAG_OPTIONAL 1
>  
> +#define MULTIBOOT_LOAD_PREFERENCE_NONE 0
> +#define MULTIBOOT_LOAD_PREFERENCE_LOW 1
> +#define MULTIBOOT_LOAD_PREFERENCE_HIGH 2
> +
>  #define MULTIBOOT_CONSOLE_FLAGS_CONSOLE_REQUIRED 1
>  #define MULTIBOOT_CONSOLE_FLAGS_EGA_TEXT_SUPPORTED 2
>  
> @@ -162,6 +168,17 @@ struct multiboot_header_tag_module_align
>    multiboot_uint32_t size;
>  };
>  
> +struct multiboot_header_tag_relocatable
> +{
> +  multiboot_uint16_t type;
> +  multiboot_uint16_t flags;
> +  multiboot_uint32_t size;
> +  multiboot_uint32_t min_addr;
> +  multiboot_uint32_t max_addr;

64bit multiboot2 payloads could reasonably expect to be able to have
themselves relocated about the 4G boundary.

~Andrew

> +  multiboot_uint32_t align;
> +  multiboot_uint32_t preference;
> +};
> +
>  struct multiboot_color
>  {
>    multiboot_uint8_t red;
> @@ -388,6 +405,13 @@ struct multiboot_tag_efi64_ih
>    multiboot_uint64_t pointer;
>  };
>  
> +struct multiboot_tag_load_base_addr
> +{
> +  multiboot_uint32_t type;
> +  multiboot_uint32_t size;
> +  multiboot_uint32_t load_base_addr;
> +};
> +
>  #endif /* ! ASM_FILE */
>  
>  #endif /* ! MULTIBOOT_HEADER */


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

Re: [MULTIBOOT2 DOC PATCH 07/10] multiboot2: Say that memory maps may not be available on EFI platforms

[Andrew Cooper]

On 09/06/2016 21:30, Daniel Kiper wrote:
> Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  doc/multiboot.texi |   11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index f1e0e09..c81b2ea 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -927,6 +927,10 @@ possible value for lower memory is 640 kilobytes. The value returned for
>  upper memory is maximally the address of the first upper memory hole
>  minus 1 megabyte. It is not guaranteed to be this value.
>  
> +This tag may not be provided by some boot loaders on EFI platforms if EFI
> +boot services are enabled and available for loaded image (EFI boot services

"for the loaded".  And below.

~Andrew

> +not terminated tag exists in Multiboot information structure).
> +
>  @subsection BIOS Boot device
>  @example
>  @group
> @@ -1078,6 +1082,10 @@ indicated a reserved area.
>  The map provided is guaranteed to list all standard @sc{ram} that should
>  be available for normal use. This type however includes the regions occupied by kernel, mbi, segments and modules. Kernel must take care not to overwrite these regions.
>  
> +This tag may not be provided by some boot loaders on EFI platforms if EFI
> +boot services are enabled and available for loaded image (EFI boot services
> +not terminated tag exists in Multiboot information structure).
> +
>  @subsection Boot loader name
>  @example
>  @group
> @@ -1310,6 +1318,9 @@ u32     | descriptor version|
>  
>  This tag contains EFI memory map as per EFI specification.
>  
> +This tag may not be provided by some boot loaders on EFI platforms if EFI
> +boot services are enabled and available for loaded image (EFI boot services
> +not terminated tag exists in Multiboot information structure).
>  
>  @subsection EFI boot services not terminated
>  @example


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

Re: [MULTIBOOT2 DOC PATCH 08/10] multiboot2: Add C structure alignment and padding consideration section

[Andrew Cooper]

On 09/06/2016 21:30, Daniel Kiper wrote:
> Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  doc/multiboot.texi |   17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
>
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index c81b2ea..bf02a1b 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -1384,6 +1384,7 @@ document, but are included for prospective operating system and boot
>  loader writers.
>  
>  @menu
> +* C structure alignment and padding consideration::
>  * Notes on PC::                 
>  * BIOS device mapping techniques::  
>  * Example OS code::             
> @@ -1391,6 +1392,22 @@ loader writers.
>  @end menu
>  
>  
> +@node C structure alignment and padding consideration
> +@section C structure alignment and padding consideration
> +
> +Many C compilers try to optimize memory accesses aligning structure

"by aligning"

> +members properly. Usually they reach the goal by adding some padding.

What does "properly" mean here?  The default padding will be specified
by the default ABI the compiler conforms to.

> +This is very useful thing in general. However, if you try to mix assembler
> +with C or use C to implement structure low level access this behavior
> +may lead, at least, to quite surprising results. Hence, compiler should
> +be instructed to not optimize such accesses. Usually it is done by special
> +attribute added to structure definition, e.g. GCC compatible sources use
> +@samp{__attribute__ ((__packed__))} for this purpose. However, this is not
> +required if it is known that its members are properly aligned and compiler
> +does not do any optimization. Very good example of this is shown below in
> +@file{multiboot2.h} file.

I am not sure what you are trying to say.

~Andrew

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

Re: [MULTIBOOT2 DOC PATCH 06/10] multiboot2: Add description of support for relocatable images

[Daniel Kiper]

On Thu, Jun 09, 2016 at 10:36:29PM +0100, Andrew Cooper wrote:
> On 09/06/2016 21:30, Daniel Kiper wrote:
> > Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> > ---
> >  doc/multiboot.texi |   56 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  doc/multiboot2.h   |   24 ++++++++++++++++++++++
> >  2 files changed, 80 insertions(+)
> >
> > diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> > index 130176a..f1e0e09 100644
> > --- a/doc/multiboot.texi
> > +++ b/doc/multiboot.texi
> > @@ -359,6 +359,7 @@ executable header.
> >  * Console header tags::
> >  * Module alignment tag::
> >  * EFI boot services tag::
> > +* Relocatable header tag::
> >
> >  @end menu
> >
> > @@ -681,6 +682,47 @@ u32     | size = 8          |
> >  This tag indicates that payload supports starting without
> >  terminating boot services.
> >
> > +@node Relocatable header tag
> > +@subsection Relocatable header tag
> > +
> > +@example
> > +@group
> > +        +-------------------+
> > +u16     | type = 10         |
> > +u16     | flags             |
> > +u32     | size = 24         |
> > +u32     | min_addr          |
> > +u32     | max_addr          |
> > +u32     | align             |
> > +u32     | preference        |
> > +        +-------------------+
> > +@end group
> > +@end example
> > +
> > +This tag indicates that image is relocatable.
> > +
> > +The meaning of each field is as follows:
> > +
> > +@table @code
> > +@item min_addr
> > +Lowest possible physical address at which image should be loaded.
> > +Boot loader cannot load any part of image below this address.
>
> "The bootloader".

This and earlier comments show, what I know very well, that a/the
English stuff is huge pain for me. Ehh... It looks that I should
not update any docs... ;-))) Anyway, thank you for your comments!

[...]

> > +struct multiboot_header_tag_relocatable
> > +{
> > +  multiboot_uint16_t type;
> > +  multiboot_uint16_t flags;
> > +  multiboot_uint32_t size;
> > +  multiboot_uint32_t min_addr;
> > +  multiboot_uint32_t max_addr;
>
> 64bit multiboot2 payloads could reasonably expect to be able to have
> themselves relocated about the 4G boundary.

That is true but in general the multiboot2 protocol is 32-bit stuff.
So, I prefer to stay in 32-bit domain. Just in case. If we need to use
full blown 64-bit thing then, IMO, we should introduce new protocol
(e.g. multiboot3) with full 64-bit support, probably compatible with
32-bit stuff to some extent.

Daniel

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

Re: [MULTIBOOT2 DOC PATCH 08/10] multiboot2: Add C structure alignment and padding consideration section

[Daniel Kiper]

On Thu, Jun 09, 2016 at 11:07:12PM +0100, Andrew Cooper wrote:
> On 09/06/2016 21:30, Daniel Kiper wrote:
> > Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> > ---
> >  doc/multiboot.texi |   17 +++++++++++++++++
> >  1 file changed, 17 insertions(+)
> >
> > diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> > index c81b2ea..bf02a1b 100644
> > --- a/doc/multiboot.texi
> > +++ b/doc/multiboot.texi
> > @@ -1384,6 +1384,7 @@ document, but are included for prospective operating system and boot
> >  loader writers.
> >
> >  @menu
> > +* C structure alignment and padding consideration::
> >  * Notes on PC::
> >  * BIOS device mapping techniques::
> >  * Example OS code::
> > @@ -1391,6 +1392,22 @@ loader writers.
> >  @end menu
> >
> >
> > +@node C structure alignment and padding consideration
> > +@section C structure alignment and padding consideration
> > +
> > +Many C compilers try to optimize memory accesses aligning structure
>
> "by aligning"
>
> > +members properly. Usually they reach the goal by adding some padding.
>
> What does "properly" mean here?  The default padding will be specified
> by the default ABI the compiler conforms to.

Right. I do not want to go into the details in this section and duplicate
anything which is much better described somewhere else. So, that is why
I use "properly" here. However, if you think that it can be phrased
better then drop me a line.

> > +This is very useful thing in general. However, if you try to mix assembler
> > +with C or use C to implement structure low level access this behavior
> > +may lead, at least, to quite surprising results. Hence, compiler should
> > +be instructed to not optimize such accesses. Usually it is done by special
> > +attribute added to structure definition, e.g. GCC compatible sources use
> > +@samp{__attribute__ ((__packed__))} for this purpose. However, this is not
> > +required if it is known that its members are properly aligned and compiler
> > +does not do any optimization. Very good example of this is shown below in
> > +@file{multiboot2.h} file.
>
> I am not sure what you are trying to say.

Do you refer to whole paragraph or last sentence?

In general I would like to say that guys should pay attention to proper
usage of struct construct in C and be aware that bad things may happen when
they introduce new tags structs without __packed__ attribute. However, they
also should be aware that __packed__ is not always required. And tag structs
in multiboot2.h file does not contain __packed__ attribute because they are
build in proper way. I hope that helps.

Daniel

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