qemu/roms/seabios/docs/Runtime_config.md

   1 SeaBIOS can read several configuration items at runtime. On coreboot
   2 the configuration comes from files located in CBFS. When SeaBIOS runs
   3 natively on QEMU the files are passed from QEMU via the fw_cfg
   4 interface.
   5
   6 This page documents the user visible configuration and control
   7 features that SeaBIOS supports.
   8
   9 LZMA compression
  10 ================
  11
  12 On coreboot, when scanning files in CBFS, any filename that ends with
  13 a ".lzma" suffix will be treated as a raw file that is compressed with
  14 the lzma compression algorithm. This works for option ROMs,
  15 configuration files, floppy images, etc. . (This feature should not be
  16 used with embedded payloads - to compress payloads, use the standard
  17 section based compression algorithm that is built into the payload
  18 specification.)
  19
  20 For example, the file **pci1106,3344.rom.lzma** would be treated the
  21 same as **pci1106,3344.rom**, but will be automatically uncompressed
  22 when accessed.
  23
  24 A file is typically compressed with the lzma compression command line
  25 tool. For example:
  26
  27 `lzma -zc /path/to/somefile.bin > somefile.bin.lzma`
  28
  29 However, some recent versions of lzma no longer supply an uncompressed
  30 file size in the lzma header. (They instead populate the field with
  31 zero.) Unfortunately, SeaBIOS requires the uncompressed file size, so
  32 it may be necessary to use a different version of the lzma tool.
  33
  34 File aliases
  35 ============
  36
  37 It is possible to create the equivalent of "symbolic links" so that
  38 one file's content appears under another name. To do this, create a
  39 **links** file with one line per link and each line having the format
  40 of "linkname" and "destname" separated by a space character. For
  41 example, the **links** file may look like:
  42
  43 ```
  44 pci1234,1000.rom somerom.rom
  45 pci1234,1001.rom somerom.rom
  46 pci1234,1002.rom somerom.rom
  47 ```
  48
  49 The above example would cause SeaBIOS to treat "pci1234,1000.rom" or
  50 "pci1234,1001.rom" as files with the same content as the file
  51 "somerom.rom".
  52
  53 Option ROMs
  54 ===========
  55
  56 SeaBIOS will scan all of the PCI devices in the target machine for
  57 option ROMs on PCI devices. It recognizes option ROMs in files that
  58 have the form **pciVVVV,DDDD.rom**. The VVVV,DDDD should correspond to
  59 the PCI vendor and device id of a device in the machine. If a given
  60 file is found then SeaBIOS will deploy the file instead of attempting
  61 to extract an option ROM from the device. In addition to supplying
  62 option ROMs for on-board devices that do not store their own ROMs,
  63 this mechanism may be used to prevent a ROM on a specific device from
  64 running.
  65
  66 SeaBIOS always deploys the VGA rom associated with the active VGA
  67 device before any other ROMs.
  68
  69 In addition, SeaBIOS will also run any file in the directory
  70 **vgaroms/** as a VGA option ROM not specific to a device and files in
  71 **genroms/** as a generic option ROM not specific to a device. The
  72 ROMS in **vgaroms/** are run immediately after running the option ROM
  73 associated with the primary VGA device (if any were found), and the
  74 **genroms/** ROMs are run after all other PCI ROMs are run.
  75
  76 Bootsplash images
  77 =================
  78
  79 SeaBIOS can show a custom [JPEG](http://en.wikipedia.org/wiki/JPEG)
  80 image or [BMP](http://en.wikipedia.org/wiki/BMP_file_format) image
  81 during bootup. To enable this, add the JPEG file to flash with the
  82 name **bootsplash.jpg** or BMP file as **bootsplash.bmp**.
  83
  84 The size of the image determines the video mode to use for showing the
  85 image. Make sure the dimensions of the image exactly correspond to an
  86 available video mode (eg, 640x480, or 1024x768), otherwise it will not
  87 be displayed.
  88
  89 SeaBIOS will show the image during the wait for the boot menu (if the
  90 boot menu has been disabled, users will not see the image). The image
  91 should probably have "Press ESC for boot menu" embedded in it so users
  92 know they can enter the normal SeaBIOS boot menu. By default, the boot
  93 menu prompt (and thus graphical image) is shown for 2.5 seconds. This
  94 can be customized via a [configuration
  95 parameter](#Other_Configuration_items).
  96
  97 The JPEG viewer in SeaBIOS uses a simplified decoding algorithm. It
  98 supports most common JPEGs, but does not support all possible formats.
  99 Please see the [trouble reporting section](Debugging) if a valid image
 100 isn't displayed properly.
 101
 102 Payloads
 103 ========
 104
 105 On coreboot, SeaBIOS will treat all files found in the **img/**
 106 directory as a coreboot payload. Each payload file will be available
 107 for boot, and one can select from the available payloads in the
 108 bootmenu. SeaBIOS supports both uncompressed and lzma compressed
 109 payloads.
 110
 111 Floppy images
 112 =============
 113
 114 It is possible to embed an image of a floppy into a file. SeaBIOS can
 115 then boot from and redirect floppy BIOS calls to the image. This is
 116 mainly useful for legacy software (such as DOS utilities). To use this
 117 feature, place a floppy image into the directory **floppyimg/**.
 118
 119 Using LZMA file compression with the [.lzma file
 120 suffix](#LZMA_compression) is a useful way to reduce the file
 121 size. Several floppy formats are available: 360K, 1.2MB, 720K, 1.44MB,
 122 2.88MB, 160K, 180K, 320K.
 123
 124 The floppy image will appear as writable to the system, however all
 125 writes are discarded on reboot.
 126
 127 When using this system, SeaBIOS reserves high-memory to store the
 128 floppy. The reserved memory is then no longer available for OS use, so
 129 this feature should only be used when needed.
 130
 131 Configuring boot order
 132 ======================
 133
 134 The **bootorder** file may be used to configure the boot up order. The
 135 file should be ASCII text and contain one line per boot method. The
 136 description of each boot method follows an [Open
 137 Firmware](https://secure.wikimedia.org/wikipedia/en/wiki/Open_firmware)
 138 device path format. SeaBIOS will attempt to boot from each item in the
 139 file - first line of the file first.
 140
 141 The easiest way to find the available boot methods is to look for
 142 "Searching bootorder for" in the SeaBIOS debug output. For example,
 143 one may see lines similar to:
 144
 145 ```
 146 Searching bootorder for: /pci@i0cf8/*@f/drive@1/disk@0
 147 Searching bootorder for: /pci@i0cf8/*@f,1/drive@2/disk@1
 148 Searching bootorder for: /pci@i0cf8/usb@10,4/*@2
 149 ```
 150
 151 The above represents the patterns SeaBIOS will search for in the
 152 bootorder file. However, it's safe to just copy and paste the pattern
 153 into bootorder. For example, the file:
 154
 155 ```
 156 /pci@i0cf8/usb@10,4/*@2
 157 /pci@i0cf8/*@f/drive@1/disk@0
 158 ```
 159
 160 will instruct SeaBIOS to attempt to boot from the given USB drive
 161 first and then attempt the given ATA harddrive second.
 162
 163 SeaBIOS also supports a special "HALT" directive. If a line that
 164 contains "HALT" is found in the bootorder file then SeaBIOS will (by
 165 default) only attempt to boot from devices explicitly listed above
 166 HALT in the file.
 167
 168 Other Configuration items
 169 =========================
 170
 171 There are several additional configuration options available in the
 172 **etc/** directory.
 173
 174 | Filename            | Description
 175 |---------------------|---------------------------------------------------
 176 | show-boot-menu      | Controls the display of the boot menu. Set to 0 to disable the boot menu.
 177 | boot-menu-message   | Customize the text boot menu message. Normally, when in text mode SeaBIOS will report the string "\\nPress ESC for boot menu.\\n\\n". This field allows the string to be changed. (This is a string field, and is added as a file containing the raw string.)
 178 | boot-menu-key       | Controls which key activates the boot menu. The value stored is the DOS scan code (eg, 0x86 for F12, 0x01 for Esc). If this field is set, be sure to also customize the **boot-menu-message** field above.
 179 | boot-menu-wait      | Amount of time (in milliseconds) to wait at the boot menu prompt before selecting the default boot.
 180 | boot-fail-wait      | If no boot devices are found SeaBIOS will reboot after 60 seconds. Set this to the amount of time (in milliseconds) to customize the reboot delay or set to -1 to disable rebooting when no boot devices are found
 181 | extra-pci-roots     | If the target machine has multiple independent root buses set this to a positive value. The SeaBIOS PCI probe will then search for the given number of extra root buses.
 182 | ps2-keyboard-spinup | Some laptops that emulate PS2 keyboards don't respond to keyboard commands immediately after powering on. One may specify the amount of time (in milliseconds) here to allow as additional time for the keyboard to become responsive. When this field is set, SeaBIOS will repeatedly attempt to detect the keyboard until the keyboard is found or the specified timeout is reached.
 183 | optionroms-checksum | Option ROMs are required to have correct checksums. However, some option ROMs in the wild don't correctly follow the specifications and have bad checksums. Set this to a zero value to allow SeaBIOS to execute them anyways.
 184 | pci-optionrom-exec  | Controls option ROM execution for roms found on PCI devices (as opposed to roms found in CBFS/fw_cfg).  Valid values are 0: Execute no ROMs, 1: Execute only VGA ROMs, 2: Execute all ROMs. The default is 2 (execute all ROMs).
 185 | s3-resume-vga-init  | Set this to a non-zero value to instruct SeaBIOS to run the vga rom on an S3 resume.
 186 | screen-and-debug    | Set this to a zero value to instruct SeaBIOS to not write characters it sends to the screen to the debug ports. This can be useful when using sgabios.
 187 | advertise-serial-debug-port | If using a serial debug port, one can set this file to a zero value to prevent SeaBIOS from listing that serial port as available for operating system use. This can be useful when running old DOS programs that are known to reset the baud rate of all advertised serial ports.
 188 | floppy0             | Set this to the type of the first floppy drive in the system (only type 4 for 3.5 inch drives is supported).
 189 | floppy1             | The type of the second floppy drive in the system. See the description of **floppy0** for more info.
 190 | threads             | By default, SeaBIOS will parallelize hardware initialization during bootup to reduce boot time. Multiple hardware devices can be initialized in parallel between vga initialization and option rom initialization. One can set this file to a value of zero to force hardware initialization to run serially. Alternatively, one can set this file to 2 to enable early hardware initialization that runs in parallel with vga, option rom initialization, and the boot menu.
 191 | sdcard*             | One may create one or more files with an "sdcard" prefix (eg, "etc/sdcard0") with the physical memory address of an SDHCI controller (one memory address per file).  This may be useful for SDHCI controllers that do not appear as PCI devices, but are mapped to a consistent memory address.