MULTIBOOT-ARM 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164
  1. Multiboot ARM extensions v0.1
  2. -----------------------------
  3. This is an unofficial extension to the the Multiboot Specification version
  4. 0.6.96, available from
  5. http://www.gnu.org/software/grub/manual/multiboot/multiboot.html.
  6. It has been adapted to support booting on the ARM architecture.
  7. Please note the changes to the following sections:
  8. 3.2 Machine state
  9. -----------------
  10. Replace all information with the following:
  11. When the boot loader invokes the 32-bit operating system, the machine must have
  12. the following state:
  13. 'R0'
  14. Must contain the magic value '0x2BADB002'; the presence of this value
  15. indicates to the operating system that it was loaded by a
  16. Multiboot-compliant boot loader (e.g. as opposed to another type of boot
  17. loader that the operating system can also be loaded from).
  18. 'R1'
  19. Must contain the 32-bit physical address of the Multiboot information
  20. provided by the boot loader (see Boot information format).
  21. 'R2'
  22. Will either contain '0' or a valid 'ARM Linux Machine Type', a list of
  23. which are maintained at http://www.arm.linux.org.uk/developer/machines/
  24. 'R3'
  25. Will either contain '0' or a valid pointer to a table of functions
  26. provided by the boot loader for enhanced early OS functionality
  27. (see 3.2.1 ARM (rpi-boot) Bootloader functions).
  28. 'SP'
  29. There will be a valid stack provided, however its size is not
  30. guaranteed. The OS image must create its own stack as soon as
  31. possible.
  32. All other registers are undefined.
  33. In addition, the system will be running in supervisor mode with virtual
  34. memory disabled. Interrupts will be disabled.
  35. The first 1 MiB of physical memory is reserved for the bootloader. This is
  36. not reflected in the memory map provided in the multiboot header. Once the
  37. OS image has finished parsing the tables provided to it by the bootloader
  38. and is no longer using any Bootloader functions (see 3.2.1) this memory is
  39. free for use by the OS.
  40. 3.2.1 ARM (rpi-boot) Bootloader functions
  41. -----------------------------------------
  42. This is a new section containing the following:
  43. The reference implementation of the Multiboot ARM extensions (rpi-boot)
  44. provides the OS image with functions providing functionality to
  45. enhance early OS development, particularly concerned with debugging
  46. output and loading files from the file system.
  47. If R3 on boot contains a value other than '0' then it points to a table
  48. of function pointers as defined in multiboot.h, with members defined as per
  49. POSIX.
  50. Non-POSIX functions are:
  51. void clear():
  52. Clear the screen and reset the cursor to the top left position
  53. rpi_boot_output_state output_get_state():
  54. Return the current state of the output subsystem (for later restoring
  55. with output_restore_state())
  56. void output_restore_state(rpi_boot_output_state state):
  57. Restore the output state previously stored with output_get_state()
  58. void output_[enable/disable]_[method]():
  59. Enable or disable the use of a particular output method. Supported
  60. methods are:
  61. uart: output on the UART
  62. fb: framebuffer
  63. log: use the file specified by the 'console log'
  64. configuration option or register_log_file()
  65. custom: use the function specified to
  66. register_custom_output_function()
  67. int mb_arm_version():
  68. Return the version of the multiboot arm functions structure in use by
  69. the current bootloader. Note that later structures will be backward
  70. compatible with earlier ones.
  71. long fsize(FILE *stream):
  72. Return the length of a stream.
  73. int ramdisk_init(uintptr_t address, size_t size, int fs_type, char *name):
  74. Define a ramdisk, starting at 'address', of length 'size'. The typical
  75. usage is to load a ramdisk image to memory (using fopen/fread etc) then
  76. register it with the bootloader with this function. fs_type is the type
  77. of file system to expect to find (standard partition type code as per
  78. http://www.win.tue.nl/~aeb/partitions/partition_types-1.html
  79. 'name' is the name to give the device in the bootloader e.g. if named
  80. 'ramdisk', its entries can be accessed as (ramdisk)/dir/file.txt
  81. int register_custom_output_function(int (*putc_function)(int c)):
  82. Register the putc() function to call for the 'custom' output method.
  83. int register_log_file(FILE *fp, size_t buffer_size):
  84. Register the file to output the log to if the 'log' output method is
  85. enabled. If buffer_size is > 0 it is the number of bytes to buffer
  86. before writing to the output stream. A call to fclose() will flush
  87. the buffer to the stream.
  88. FILE *get_log_file():
  89. Return the current log file in use, for passing to fflush() for example.
  90. Path names use the '/' character as a directory delimiter. Files on a FAT
  91. filesystem are referenced by their lowercase name (in particular, looking for
  92. a file using capital letters will cause the search to fail). Paths can be
  93. prepended by a device name in round parentheses '()' to determine on which
  94. device to look for a file. e.g. to look for the file called testfile.txt
  95. in the root directory of device 'emmc0_0' the appropriate path would be:
  96. '(emmc0_0)/testfile.txt'.
  97. 3.3 Boot information format
  98. ---------------------------
  99. Please be aware of the following when reading this section:
  100. In the flags field, the following bits will never be set: 8, 10
  101. The following fields have special meaning:
  102. boot_device:
  103. This is a pointer to a null terminated string containing the name of the
  104. device from which the OS image was loaded.
  105. drives_addr:
  106. This is a pointer to a list of pointers to null terminated strings
  107. containing all the storage device names known to the bootloader.
  108. drives_length:
  109. This is the length of the above list.
  110. vbe_control_info, vbe_mode_info, vbe_mode, vbe_interface_seg,
  111. vbe_interface_off, vbe_interface_len:
  112. These are redefined to the following:
  113. Offset Name Function
  114. 72 fb_addr Physical address of the linear framebuffer
  115. 76 fb_size Frame buffer width << 16 | height
  116. 80 fb_pitch Bytes between each physical line
  117. 84 fb_depth Bits per pixel << 16 | pixel_order
  118. pixel_order:
  119. 0: BGR
  120. 1: RGB