vbatts/grub
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

* docs/grub.texi (Platform limitations): New section.

Browse source 
(Platform-specific operations): Likewise.
	* docs/grub-dev.texi (Porting): Likewise.
This commit is contained in:
Vladimir 'phcoder' Serbinenko 2012-01-26 19:40:47 +01:00
parent 7626111087
commit ca1dacea3c
3 changed files with 483 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
2012-01-25 Vladimir Serbinenko <phcoder@gmail.com>
* docs/grub.texi (Platform limitations): New section.
(Platform-specific operations): Likewise.
* docs/grub-dev.texi (Porting): Likewise.
2012-01-25 Vladimir Serbinenko <phcoder@gmail.com>
IEEE1275 disk write support.

310
docs/grub-dev.texi
View file

@ -77,6 +77,7 @@ This edition documents version @value{VERSION}.
* Finding your way around::
* Coding style::
* Contributing Changes::
* Porting::
* Error Handling::
* CIA::
* BIOS port memory map::
@ -447,6 +448,315 @@ If your intention is to just get started, please do not submit a inclusion
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

170
docs/grub.texi
View file

@ -91,6 +91,8 @@ This edition documents version @value{VERSION}.
* 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
@ -4072,6 +4074,167 @@ adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
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
@ -4129,7 +4292,7 @@ X86 support is summarised in the following table. ``Yes'' means that the kernel
@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)
@ -4155,7 +4318,7 @@ X86 support is summarised in the following table. ``Yes'' means that the kernel
@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)
@ -4189,7 +4352,8 @@ X86 support is summarised in the following table. ``Yes'' means that the kernel
@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