* Finding your way around::
* Coding style::
* Contributing Changes::
+* Porting::
* Error Handling::
* CIA::
* BIOS port memory map::
request. Instead, please subscribe to the mailing list, and communicate first
(e.g. sending a patch, asking a question, commenting on another message...).
+@node Porting
+@chapter Porting
+
+GRUB2 is designed to be easily portable accross platforms. But because of the
+nature of bootloader every new port must be done separately. Here is how I did
+MIPS (loongson and ARC) and Xen ports. Note than this is more of suggestions,
+not absolute truth.
+
+First of all grab any architecture specifications you can find in public
+(please avoid NDA).
+
+First stage is ``Hello world''. I've done it outside of GRUB for simplicity.
+Your task is to have a small program which is loadable as bootloader and
+clearly shows its presence to you. If you have easily accessible console
+you can just print a message. If you have a mapped framebuffer you know address
+of, you can draw a square. If you have a debug facility, just hanging without
+crashing might be enough. For the first stage you can choose to load the
+bootloader across the network since format for network image is often easier
+than for local boot and it skips the need of small intermediary stages and
+nvram handling. Additionally you can often have a good idea of the needed
+format by running ``file'' on any netbootable executable for given platform.
+
+This program should probably have 2 parts: an assembler and C one. Assembler one
+handles BSS cleaning and other needed setup (on some platforms you may need
+to switch modes or copy the executable to its definitive position). So your code
+may look like (x86 assembly for illustration purposes)
+
+@example
+ .globl _start
+_start:
+ movl $_bss_start, %edi
+ movl $_end, %ecx
+ subl %edi, %ecx
+ xorl %eax, %eax
+ cld
+ rep
+ stosb
+ call main
+@end example
+
+@example
+
+static const char msg[] = "Hello, world";
+
+void
+putchar (int c)
+@{
+ ...
+@}
+
+void
+main (void)
+@{
+ const char *ptr = msg;
+ while (*ptr)
+ putchar (*ptr++);
+ while (1);
+@}
+@end example
+
+Sometimes you need a third file: assembly stubs for ABI-compatibility.
+
+Once this file is functional it's time to move it into GRUB2. The startup
+assembly file goes to grub-core/kern/$cpu/$platform/startup.S. You should also
+include grub/symbol.h and replace call to entry point with call to
+EXT_C(grub_main). The C file goes to grub-core/kern/$cpu/$platform/init.c
+and its entry point is renamed to void grub_machine_init (void). Keep final
+infinite loop for now. Stubs file if any goes to
+grub-core/kern/$cpu/$platform/callwrap.S. Sometimes either $cpu or $platform
+is dropped if file is used on several cpus respectivelyplatforms.
+Check those locations if they already have what you're looking for.
+
+Then modify in configure.ac the following parts:
+
+CPU names:
+
+@example
+case "$target_cpu" in
+ i[[3456]]86) target_cpu=i386 ;;
+ amd64) target_cpu=x86_64 ;;
+ sparc) target_cpu=sparc64 ;;
+ s390x) target_cpu=s390 ;;
+ ...
+esac
+@end example
+
+Sometimes CPU have additional architecture names which don't influence booting.
+You might want to have some canonical name to avoid having bunch of identical
+platforms with different names.
+
+NOTE: it doesn't influence compile optimisations which depend solely on
+chosen compiler and compile options.
+
+@example
+if test "x$with_platform" = x; then
+ case "$target_cpu"-"$target_vendor" in
+ i386-apple) platform=efi ;;
+ i386-*) platform=pc ;;
+ x86_64-apple) platform=efi ;;
+ x86_64-*) platform=pc ;;
+ powerpc-*) platform=ieee1275 ;;
+ ...
+ esac
+else
+ ...
+fi
+@end example
+
+This part deals with guessing the platform from CPU and vendor. Sometimes you
+need to use 32-bit mode for booting even if OS runs in 64-bit one. If so add
+your platform to:
+
+@example
+case "$target_cpu"-"$platform" in
+ x86_64-efi) ;;
+ x86_64-emu) ;;
+ x86_64-*) target_cpu=i386 ;;
+ powerpc64-ieee1275) target_cpu=powerpc ;;
+esac
+@end example
+
+Add your platform to the list of supported ones:
+
+@example
+case "$target_cpu"-"$platform" in
+ i386-efi) ;;
+ x86_64-efi) ;;
+ i386-pc) ;;
+ i386-multiboot) ;;
+ i386-coreboot) ;;
+ ...
+esac
+@end example
+
+If explicit -m32 or -m64 is needed add it to:
+
+@example
+case "$target_cpu" in
+ i386 | powerpc) target_m32=1 ;;
+ x86_64 | sparc64) target_m64=1 ;;
+esac
+@end example
+
+Finally you need to add a conditional to the following block:
+
+@example
+AM_CONDITIONAL([COND_mips_arc], [test x$target_cpu = xmips -a x$platform = xarc])
+AM_CONDITIONAL([COND_sparc64_ieee1275], [test x$target_cpu = xsparc64 -a x$platform = xieee1275])
+AM_CONDITIONAL([COND_powerpc_ieee1275], [test x$target_cpu = xpowerpc -a x$platform = xieee1275])
+@end example
+
+Next stop is gentpl.py. You need to add your platform to the list of supported
+ones (sorry that this list is duplicated):
+
+@example
+GRUB_PLATFORMS = [ "emu", "i386_pc", "i386_efi", "i386_qemu", "i386_coreboot",
+ "i386_multiboot", "i386_ieee1275", "x86_64_efi",
+ "mips_loongson", "sparc64_ieee1275",
+ "powerpc_ieee1275", "mips_arc", "ia64_efi",
+ "mips_qemu_mips", "s390_mainframe" ]
+@end example
+
+You may also want already to add new platform to one or several of available
+groups. In particular we always have a group for each CPU even when only
+one platform for given CPU is available.
+
+Then comes grub-core/Makefile.core.def. In the block ``kernel'' you'll need
+to define ldflags for your platform ($cpu_$platform_ldflags). You also need to
+declare startup asm file ($cpu_$platform_startup) as well as any other files
+(e.g. init.c and callwrap.S) (e.g. $cpu_$platform = kern/$cpu/$platform/init.c).
+At this stage you will also need to add dummy dl.c and cache.S with functions
+grub_err_t grub_arch_dl_check_header (void *ehdr), grub_err_t
+grub_arch_dl_relocate_symbols (grub_dl_t mod, void *ehdr) (dl.c) and
+void grub_arch_sync_caches (void *address, grub_size_t len) (cache.S). They
+won't be used for now.
+
+You will need to create directory include/$cpu/$platform and a file
+include/$cpu/types.h. The later folowing this template:
+
+@example
+#ifndef GRUB_TYPES_CPU_HEADER
+#define GRUB_TYPES_CPU_HEADER 1
+
+/* The size of void *. */
+#define GRUB_TARGET_SIZEOF_VOID_P 4
+
+/* The size of long. */
+#define GRUB_TARGET_SIZEOF_LONG 4
+
+/* mycpu is big-endian. */
+#define GRUB_TARGET_WORDS_BIGENDIAN 1
+/* Alternatively: mycpu is little-endian. */
+#undef GRUB_TARGET_WORDS_BIGENDIAN
+
+#endif /* ! GRUB_TYPES_CPU_HEADER */
+@end example
+
+You will also need to add a dummy file to datetime and setjmp modules to
+avoid any of it having no files. It can be just completely empty at this stage.
+
+You'll need to make grub-mkimage.c (util/grub_mkimage.c) aware of the needed
+format. For most commonly used formats like ELF, PE, aout or raw the support
+is already present and you'll need to make it follow the existant code paths
+for your platform adding adjustments if necessary. When done compile:
+
+@example
+./autogen.sh
+./configure --target=$cpu --with-platform=$platform TARGET_CC=.. OBJCOPY=... STRIP=...
+make > /dev/null
+@end example
+
+And create image
+
+@example
+./grub-mkimage -d grub-core -O $format_id -o test.img
+@end example
+
+And it's time to test your test.img.
+
+If it works next stage is to have heap, console and timer.
+
+To have the heap working you need to determine which regions are suitable for
+heap usage, allocate them from firmware and map (if applicable). Then call
+grub_mm_init_region (vois *start, grub_size_t s) for every of this region.
+As a shortcut for early port you can allocate right after _end or have
+a big static array for heap. If you do you'll probably need to come back to
+this later. As for output console you should distinguish between an array of
+text, terminfo or graphics-based console. Many of real-world examples don't
+fit perfectly into any of these categories but one of the models is easier
+to be used as base. In second and third case you should add your platform to
+terminfokernel respectively videoinkernel group. A good example of array of
+text is i386-pc (kern/i386/pc/init.c and term/i386/pc/console.c).
+Of terminfo is ieee1275 (kern/ieee1275/init.c and term/ieee1275/console.c).
+Of video is loongson (kern/mips/loongson/init.c). Note that terminfo has
+to be inited in 2 stages: one before (to get at least rudimentary console
+as early as possible) and another after the heap (to get full-featured console).
+For the input there are string of keys, terminfo and direct hardware. For string
+of keys look at i386-pc (same files), for termino ieee1275 (same files) and for
+hardware loongson (kern/mips/loongson/init.c and term/at_keyboard.c).
+
+For the timer you'll need to call grub_install_get_time_ms (...) with as sole
+argument a function returning a grub_uint64_t of a number of milliseconds
+elapsed since arbitrary point in the past.
+
+Once these steps accomplished you can remove the inifinite loop and you should
+be able to get to the minimal console. Next step is to have module loading
+working. For this you'll need to fill kern/$cpu/dl.c and kern/$cpu/cache.S
+with real handling of relocations and respectively the real sync of I and D
+caches. Also you'll need to decide where in the image to store the modules.
+Usual way is to have it concatenated at the end. In this case you'll need to
+modify startup.S to copy modules out of bss to let's say ALIGN_UP (_end, 8)
+before cleaning out bss. You'll probably find useful to add total_module_size
+field to startup.S. In init.c you need to set grub_modbase to the address
+where modules can be found. You may need grub_modules_get_end () to avoid
+declaring the space occupied by modules as usable for heap. You can test modules
+with:
+
+@example
+./grub-mkimage -d grub-core -O $format_id -o test.img hello
+@end example
+
+and then running ``hello'' in the shell.
+
+Once this works, you should think of implementing disk access. Look around
+disk/ for examples.
+
+Then, very importantly, you probably need to implement the actual loader
+(examples available in loader/)
+
+Last step to have minimally usable port is to add support to grub-install to
+put GRUB in a place where firmware or platform will pick it up.
+
+Next steps are: filling datetime.c, setjmp.S, network (net/drivers),
+video (video/), halt (lib/), reboot (lib/).
+
+Please add your platform to Platform limitations and Supported kernels chapter
+in user documentation and mention any steps you skipped which result in reduced
+features or performance. Here is the quick checklist of features. Some of them
+are less important than others and skipping them is completely ok, just needs
+to be mentioned in user documentation.
+
+Checklist:
+@itemize
+@item Is heap big enough?
+@item Which charset is supported by console?
+@item Does platform have disk driver?
+@item Do you have network card support?
+@item Are you able to retrieve datetime (with date)?
+@item Are you able to set datetime (with date)?
+@item Is serial supported?
+@item Do you have direct disk support?
+@item Do you have direct keyboard support?
+@item Do you have USB support?
+@item Do you support loading through network?
+@item Do you support loading from disk?
+@item Do you support chainloading?
+@item Do you support network chainloading?
+@item Does cpuid command supports checking all
+CPU features that the user might want conditionalise on
+(64-bit mode, hypervisor,...)
+@item Do you support hints? How reliable are they?
+@item Does platform have ACPI? If so do ``acpi'' and ``lsacpi'' modules work?
+@item Do any of platform-specific operations mentioned in the relevant section of
+user manual makes sense on your platform?
+@item Does your platform support PCI? If so is there an appropriate driver for
+GRUB?
+@item Do you support badram?
+@end itemize
+
@node Error Handling
@chapter Error Handling
* Commands:: The list of available builtin commands
* Internationalisation:: Topics relating to language support
* Security:: Authentication and authorisation
+* Platform limitations:: The list of platform-specific limitations
+* Platform-specific operations:: Platform-specific operations
* Supported kernels:: The list of supported kernels
* Troubleshooting:: Error messages produced by GRUB
* Invoking grub-install:: How to use the GRUB installer
commands.
+@node Platform limitations
+@chapter Platform limitations
+
+GRUB2 is designed to be portable and is actually ported across platforms. We
+try to keep all platforms at the level. Unfortunately some platforms are better
+supported than others. This is detailed in current and 2 following sections.
+
+ARC platform is unable to change datetime (firmware doesn't seem to provide a
+function for it).
+EMU has similar limitation.
+
+Console charset refers only to firmware-assisted console. gfxterm is always
+Unicode (see Internationalisation section for its limitations). Serial is
+configurable to UTF-8 or ASCII (see Internationalisation). In case of qemu
+and coreboot ports the refered console is vga_text. Loongson always uses
+gfxterm.
+
+Most limited one is ASCII. CP437 provides additionally pseudographics.
+GRUB2 doesn't use any language characters from CP437 as often CP437 is replaced
+by national encoding compatible only in pseudographics.
+Unicode is the most versatile charset which supports many languages. However
+the actual console may be much more limited depending on firmware
+
+On BIOS network is supported only if the image is loaded through network.
+On sparc64 GRUB is unable to determine which server it was booted from.
+
+On platforms not having direct serial support (as indicated in the line serial)
+you can still redirect firmware console to serial if it allows so.
+
+Direct ATA/AHCI support allows to circumvent various firmware limitations but
+isn't needed for normal operation except on baremetal ports.
+
+AT keyboard support allows keyboard layout remapping and support for keys not
+available through firmware. It isn't needed for normal operation except
+baremetal ports.
+
+USB support provides benefits similar to ATA (for USB disks) or AT (for USB
+keyboards). In addition it allows USBserial.
+
+Chainloading refers to the ability to load another bootloader through the same protocol
+
+Hints allow faster disk discovery by already knowing in advance which is the disk in
+question. On some platforms hints are correct unless you move the disk between boots.
+On other platforms it's just an educated guess.
+Note that hint failure results in just reduced performance, not a failure
+
+BadRAM is the ability to mark some of the RAM as ``bad''. Note: due to protocol
+limitations mips-loongson (with Linux protocol)
+and mips-qemu_mips can use only memory up to first hole.
+
+@multitable @columnfractions .20 .20 .20 .20 .20
+@item @tab BIOS @tab Coreboot @tab Multiboot @tab Qemu
+@item video @tab yes @tab yes @tab yes @tab yes
+@item console charset @tab CP437 @tab CP437 @tab CP437 @tab CP437
+@item network @tab yes (*) @tab no @tab no @tab no
+@item serial @tab yes @tab yes @tab yes @tab yes
+@item ATA/AHCI @tab yes @tab yes @tab yes @tab yes
+@item AT keyboard @tab yes @tab yes @tab yes @tab yes
+@item USB @tab yes @tab yes @tab yes @tab yes
+@item chainloader @tab local @tab yes @tab yes @tab no
+@item cpuid @tab partial @tab partial @tab partial @tab partial
+@item hints @tab guess @tab guess @tab guess @tab guess
+@item PCI @tab yes @tab yes @tab yes @tab yes
+@item badram @tab yes @tab yes @tab yes @tab yes
+@item compression @tab always @tab pointless @tab no @tab no
+@item exit @tab yes @tab no @tab no @tab no
+@end multitable
+
+@multitable @columnfractions .20 .20 .20 .20 .20
+@item @tab ia32 EFI @tab amd64 EFI @tab ia32 IEEE1275 @tab Itanium
+@item video @tab yes @tab yes @tab no @tab no
+@item console charset @tab Unicode @tab Unicode @tab ASCII @tab Unicode
+@item network @tab yes @tab yes @tab yes @tab yes
+@item serial @tab yes @tab yes @tab yes @tab no
+@item ATA/AHCI @tab yes @tab yes @tab yes @tab no
+@item AT keyboard @tab yes @tab yes @tab yes @tab no
+@item USB @tab yes @tab yes @tab yes @tab no
+@item chainloader @tab local @tab local @tab no @tab local
+@item cpuid @tab partial @tab partial @tab partial @tab no
+@item hints @tab guess @tab guess @tab good @tab guess
+@item PCI @tab yes @tab yes @tab yes @tab no
+@item badram @tab yes @tab yes @tab no @tab yes
+@item compression @tab no @tab no @tab no @tab no
+@item exit @tab yes @tab yes @tab yes @tab yes
+@end multitable
+
+@multitable @columnfractions .20 .20 .20 .20 .20
+@item @tab Loongson @tab sparc64 @tab Powerpc @tab ARC
+@item video @tab yes @tab no @tab yes @tab no
+@item console charset @tab N/A @tab ASCII @tab ASCII @tab ASCII
+@item network @tab no @tab yes (*) @tab yes @tab no
+@item serial @tab yes @tab no @tab no @tab no
+@item ATA/AHCI @tab yes @tab no @tab no @tab no
+@item AT keyboard @tab yes @tab no @tab no @tab no
+@item USB @tab yes @tab no @tab no @tab no
+@item chainloader @tab yes @tab no @tab no @tab no
+@item cpuid @tab no @tab no @tab no @tab no
+@item hints @tab good @tab good @tab good @tab no
+@item PCI @tab yes @tab no @tab no @tab no
+@item badram @tab yes (*) @tab no @tab no @tab no
+@item compression @tab configurable @tab no @tab no @tab configurable
+@item exit @tab no @tab yes @tab yes @tab yes
+@end multitable
+
+@multitable @columnfractions .20 .20 .20 .20 .20
+@item @tab MIPS qemu @tab emu
+@item video @tab no @tab no
+@item console charset @tab CP437 @tab ASCII
+@item network @tab no @tab yes
+@item serial @tab yes @tab no
+@item ATA/AHCI @tab yes @tab no
+@item AT keyboard @tab yes @tab no
+@item USB @tab N/A @tab yes
+@item chainloader @tab yes @tab no
+@item cpuid @tab no @tab no
+@item hints @tab guess @tab no
+@item PCI @tab no @tab no
+@item badram @tab yes (*) @tab no
+@item compression @tab configurable @tab no
+@item exit @tab no @tab yes
+@end multitable
+
+@node Platform-specific operations
+@chapter Outline
+
+Some platforms have features which allows to implement
+some commands useless or not implementable on others.
+
+Quick summary:
+
+Information retrieval:
+
+@itemize
+@item mipsel-loongson: lsspd
+@item mips-arc: lsdev
+@item efi: lsefisystab, lssal, lsefimmap
+@item i386-pc: lsapm
+@item acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-efi): lsacpi
+@end itemize
+
+Workarounds for platform-specific issues:
+@itemize
+@item i386-efi/x86_64-efi: loadbios, fixvideo
+@item acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-efi):
+ acpi (override ACPI tables)
+@item i386-pc: drivemap
+@item i386-pc: sendkey
+@end itemize
+
+Advanced operations for power users:
+@itemize
+@item x86: iorw (direct access to I/O ports)
+@end itemize
+
+Miscelaneous:
+@itemize
+@item cmos (x86-*, ieee1275, mips-qemu_mips, mips-loongson): cmostest
+ (used on some laptops to check for special power-on key)
+@item i386-pc: play
+@end itemize
+
@node Supported kernels
@chapter Supported boot targets
@end multitable
@multitable @columnfractions .50 .22 .22
-@item @tab 32-bit EFI @tab 64-bit EFI
+@item @tab ia32 EFI @tab amd64 EFI
@item BIOS chainloading @tab no (1) @tab no (1)
@item NTLDR @tab no (1) @tab no (1)
@item Plan9 @tab no (1) @tab no (1)
@end multitable
@multitable @columnfractions .50 .22 .22
-@item @tab IEEE1275
+@item @tab ia32 IEEE1275
@item BIOS chainloading @tab no (1)
@item NTLDR @tab no (1)
@item Plan9 @tab no (1)
@item Requires ACPI
@end enumerate
-PowerPC and Sparc ports support only Linux. MIPS port supports Linux and multiboot2.
+PowerPC, IA64 and Sparc64 ports support only Linux. MIPS port supports Linux
+and multiboot2.
@chapter Boot tests
projects / thirdparty / grub.git / commitdiff
