[MULTIBOOT2 SPEC PATCH v3 3/4] multiboot2: Make example kernel build at least for i386

[Hans Ulrich Niedermann]

The example kernel has assembly language boot code for both
i386 and mips, but the mips assembly code used to be built
unconditionally, even if the build is using non-mips build
tools such as for x86_64 or i386.

This makes the example kernel build at least for i386, both
on i386 and on x86_64 hosts.

  * renames the i386 boot code from boot.S to boot_i386.S
    to go along with the mips boot code in boot_mips.S

  * adds AC_CANONICAL_HOST to select the proper boot code:

      * i386 if building on x86_64 (adds -m32) or on i[3456]86
      * mips if building for mips*
      * do not build the kernel if building for another system

  * adds m4 quoting and uses AS_HELP_STRING use in configure.ac

  * fixes the name of the constants used in boot_i386.S
    to use the actual constant names from multiboot2.h

  * documents both boot_i386.S and boot_mips.S in the
    multiboot.texi page

Building the example kernel for mips still needs some work, as
I have not managed to build for mips yet with either my
mips64-linux-gnu cross-compilation toolchain on Fedora 32 or
on my Debian 10.3 MIPS install running in qemu-system-mips.

Signed-off-by: Hans Ulrich Niedermann <address@hidden>

 rename doc/{boot.S => boot_i386.S} (94%)

diff --git a/.gitignore b/.gitignore
index 01823be9c..4de19ceee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,7 +11,9 @@ Makefile.in
 /aclocal.m4
 /autom4te.cache/
 /compile
+/config.guess
 /config.h.in
+/config.sub
 /configure
 /depcomp
 /doc/mdate-sh
diff --git a/configure.ac b/configure.ac
index 8f21b1852..5ddb16b72 100644
--- a/configure.ac
+++ b/configure.ac
@@ -32,11 +32,36 @@ dnl Because recent automake complains about AS, set it here.
 CCAS="$CC"
 AC_SUBST(CCAS)
 
-dnl Build the example Multiboot kernel.
-AC_ARG_ENABLE(example-kernel,
-  [  --enable-example-kernel
-                          build the example Multiboot kernel])
-AM_CONDITIONAL(BUILD_EXAMPLE_KERNEL, test "x$enable_example_kernel" = xyes)
+dnl Build the example Multiboot kernel (if possible on this host)
+AC_CANONICAL_HOST
+kernel_ccasflags=
+kernel_cflags=
+case "$host_cpu" in #(
+  i[[3456]]86)
+    kernel_boot_arch=i386
+    ;; #(
+  x86_64)
+    kernel_boot_arch=i386
+    kernel_ccasflags="-m32"
+    kernel_cflags="-m32"
+    ;; #(
+  mips*)
+    kernel_boot_arch=mips
+    ;; #(
+  *)
+    kernel_boot_arch=unsupported
+    ;;
+esac
+AC_SUBST([kernel_boot_arch])
+AC_SUBST([kernel_ccasflags])
+AC_SUBST([kernel_cflags])
+
+AC_ARG_ENABLE([example-kernel], [dnl
+AS_HELP_STRING([--enable-example-kernel],
+               [build the example Multiboot2 kernel])])
+
+AM_CONDITIONAL([BUILD_EXAMPLE_KERNEL],
+               [test "x$enable_example_kernel" = xyes && test 
"x$kernel_boot_arch" != "xunsupported"])
 
 dnl Because recent automake complains about CCASFLAGS, set it here.
 CCASFLAGS='$(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)'
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2a5afd95d..0d896fe10 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,6 +1,6 @@
 info_TEXINFOS = multiboot.texi
-EXAMPLES = boot_mips.S kernel.c multiboot2.h
-multiboot_TEXINFOS = boot.S.texi kernel.c.texi multiboot2.h.texi
+EXAMPLES = boot_i386.S boot_mips.S kernel.c multiboot2.h
+multiboot_TEXINFOS = boot_i386.S.texi boot_mips.S.texi kernel.c.texi 
multiboot2.h.texi
 SRC2TEXI = src2texi
 noinst_SCRIPTS = $(SRC2TEXI)
 EXTRA_PROGRAMS = kernel
@@ -9,8 +9,9 @@ pkginclude_HEADERS = multiboot2.h
 # The example kernel is built if you specify --enable-example-kernel.
 if BUILD_EXAMPLE_KERNEL
 noinst_PROGRAMS = kernel
-kernel_SOURCES = $(EXAMPLES)
-kernel_CFLAGS = -fno-builtin -nostdinc -O -g -Wall \
+kernel_SOURCES = boot_$(kernel_boot_arch).S kernel.c multiboot2.h
+kernel_CCASFLAGS = $(kernel_ccasflags)
+kernel_CFLAGS = $(kernel_cflags) -fno-builtin -nostdinc -O -g -Wall \
        -imacros $(top_builddir)/config.h
 kernel_LDFLAGS = -nostdlib -Wl,-N -Wl,-Ttext -Wl,80100000 -Wl,--build-id=none
 
diff --git a/doc/boot.S b/doc/boot_i386.S
similarity index 94%
rename from doc/boot.S
rename to doc/boot_i386.S
index 8f6f66fcc..9ab016612 100644
--- a/doc/boot.S
+++ b/doc/boot_i386.S
@@ -50,11 +50,11 @@ multiboot_header:
        /* magic */
        .long   MULTIBOOT2_HEADER_MAGIC
        /* ISA: i386 */
-       .long   GRUB_MULTIBOOT_ARCHITECTURE_I386
+       .long   MULTIBOOT_ARCHITECTURE_I386
        /* Header length.  */
        .long   multiboot_header_end - multiboot_header
        /* checksum */
-       .long   -(MULTIBOOT2_HEADER_MAGIC + GRUB_MULTIBOOT_ARCHITECTURE_I386 + 
(multiboot_header_end - multiboot_header))
+       .long   -(MULTIBOOT2_HEADER_MAGIC + MULTIBOOT_ARCHITECTURE_I386 + 
(multiboot_header_end - multiboot_header))
 #ifndef __ELF__
 address_tag_start:     
        .short MULTIBOOT_HEADER_TAG_ADDRESS
diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index df8a0d056..827a5c08d 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -1553,26 +1553,31 @@ Multiboot2-compliant boot loader and for reference to 
how to implement a
 Multiboot2 kernel. The source files can be found under the directory
 @file{doc} in the Multiboot2 source distribution.
 
-The kernel @file{kernel} consists of only three files: @file{boot.S},
-@file{kernel.c} and @file{multiboot2.h}. The assembly source
-@file{boot.S} is written in GAS (@pxref{Top, , GNU assembler, as.info,
-The GNU assembler}), and contains the Multiboot2 information structure to
-comply with the specification. When a Multiboot2-compliant boot loader
-loads and execute it, it initialize the stack pointer and @code{EFLAGS},
-and then call the function @code{cmain} defined in @file{kernel.c}. If
-@code{cmain} returns to the callee, then it shows a message to inform
-the user of the halt state and stops forever until you push the reset
-key. The file @file{kernel.c} contains the function @code{cmain},
-which checks if the magic number passed by the boot loader is valid and
-so on, and some functions to print messages on the screen. The file
-@file{multiboot2.h} defines some macros, such as the magic number for the
-Multiboot2 header, the Multiboot2 header structure and the Multiboot2
-information structure.
+The kernel @file{kernel} consists of only three files:
+@file{boot_i386.S} or @file{boot_mips.S} (depending on the kernel
+architecture), @file{kernel.c}, and @file{multiboot2.h}. The assembly
+sources @file{boot_i386.S} and @file{boot_mips.S} are written in GAS
+(@pxref{Top, , GNU assembler, as.info, The GNU assembler}) and
+contain the Multiboot2 information structure to comply with the
+specification. When a Multiboot2-compliant boot loader loads and
+executes @file{boot_*.S}, it initializes the stack pointer and
+@code{EFLAGS}, and then calls the function @code{cmain} defined in
+@file{kernel.c}.
+
+If @code{cmain} returns to the callee, then it shows a message to
+inform the user of the halt state and stops forever until you push the
+system reset button. The file @file{kernel.c} contains the function
+@code{cmain}, which checks if the magic number passed by the boot
+loader is valid and so on, and some functions to print messages on the
+screen. The file @file{multiboot2.h} defines some C preprocessor
+macros, such as the magic number for the Multiboot2 header, the
+Multiboot2 header structure and the Multiboot2 information structure.
 
 @menu
-* multiboot2.h::                 
-* boot.S::                      
-* kernel.c::                    
+* multiboot2.h::
+* boot_i386.S::
+* boot_mips.S::
+* kernel.c::
 * Other Multiboot2 kernels::
 @end menu
 
@@ -1587,13 +1592,23 @@ This is the source code in the file @file{multiboot2.h}:
 @end example
 
 
-@node boot.S
-@subsection boot.S
+@node boot_i386.S
+@subsection boot_i386.S
+
+In the file @file{boot_i386.S}:
+
+@example
+@include boot_i386.S.texi
+@end example
+
+
+@node boot_mips.S
+@subsection boot_mips.S
 
-In the file @file{boot.S}:
+In the file @file{boot_mips.S}:
 
 @example
-@include boot.S.texi
+@include boot_mips.S.texi
 @end example
 
 
-- 
2.26.2