diff options
Diffstat (limited to 'qemu/roms/seabios/docs')
| -rw-r--r-- | qemu/roms/seabios/docs/Build_overview.md | 34 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Contributing.md | 20 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Debugging.md | 27 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Developer_Documentation.md | 11 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Download.md | 6 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Execution_and_code_flow.md | 2 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Linking_overview.md | 12 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Releases.md | 29 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/Runtime_config.md | 191 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/SeaBIOS.md | 2 | ||||
| -rw-r--r-- | qemu/roms/seabios/docs/SeaVGABIOS.md | 39 |
11 files changed, 340 insertions, 33 deletions
diff --git a/qemu/roms/seabios/docs/Build_overview.md b/qemu/roms/seabios/docs/Build_overview.md index 26db22691..8c6b2f458 100644 --- a/qemu/roms/seabios/docs/Build_overview.md +++ b/qemu/roms/seabios/docs/Build_overview.md @@ -52,6 +52,34 @@ CSM_ENABLE'. The SeaBIOS binary will be included as a discrete file within the 'Flash Volume' which is created, and there are tools which will extract it and allow it to be replaced. +Distribution builds +=================== + +If one is building a binary version of SeaBIOS as part of a package +(such as an rpm) or for wide distribution, please provide the +EXTRAVERSION field during the build. For example: + +`make EXTRAVERSION="-${RPM_PACKAGE_RELEASE}"` + +The EXTRAVERSION field should provide the package version (if +applicable) and the name of the distribution (if that's not already +obvious from the package version). This string will be appended to the +main SeaBIOS version. The above information helps SeaBIOS developers +correlate defect reports to the source code and build environment. + +If one is building a binary in a build environment that does not have +access to the git tool or does not have the full SeaBIOS git repo +available, then please use an official SeaBIOS release tar file as +source. If building from a snapshot (where there is no official +SeaBIOS tar) then one should generate a snapshot tar file on a machine +that does support git using the scripts/tarball.sh tool. For example: + +`scripts/tarball.sh` + +The tarball.sh script encodes version information in the resulting tar +file which the build can extract and include in the final binary. The +above EXTRAVERSION field should still be set when building from a tar. + Overview of files in the repository =================================== @@ -61,11 +89,7 @@ drivers. The **src/fw/** directory contains source code for platform firmware initialization. The **src/std/** directory contains header files describing standard bios, firmware, and hardware interfaces. -The **vgasrc/** directory contains code for VGA BIOS implementations. -This code is separate from the main BIOS code in the src/ directory. -When the build is configured to produce a VGA BIOS the resulting -binary is found in out/vgabios.bin. The VGA BIOS code is always -compiled in 16bit mode. +The **vgasrc/** directory contains code for [SeaVGABIOS](SeaVGABIOS). The **scripts/** directory contains helper utilities for manipulating and building the final roms. diff --git a/qemu/roms/seabios/docs/Contributing.md b/qemu/roms/seabios/docs/Contributing.md new file mode 100644 index 000000000..d0f2b5b5e --- /dev/null +++ b/qemu/roms/seabios/docs/Contributing.md @@ -0,0 +1,20 @@ +SeaBIOS welcomes contributions of code (either fixing bugs or adding +new functionality). At a high level, the process to contribute a +change is: + +1. [Obtain](Download) the current code and documentation +2. Enhance and test the code locally +3. Submit changes to the SeaBIOS [mailing list](Mailinglist) as a + patch +4. Receive feedback, answer questions, and possibly provide updated + patches +5. When accepted, a maintainer (Kevin O'Connor or Gerd Hoffman) will + commit the change to the master SeaBIOS repository + +The SeaBIOS patch submission process is similar to the +[QEMU process](http://wiki.qemu.org/Contribute/SubmitAPatch). Please +review the QEMU process for more details and tips on the best way to +submit patches. The SeaBIOS C code does follow a slightly different +coding style from QEMU (eg, mixed code and C99 style variable +declarations are encouraged, braces are not required around single +statement blocks), however patches in the QEMU style are acceptable. diff --git a/qemu/roms/seabios/docs/Debugging.md b/qemu/roms/seabios/docs/Debugging.md index 03567de4d..7ab5d02d8 100644 --- a/qemu/roms/seabios/docs/Debugging.md +++ b/qemu/roms/seabios/docs/Debugging.md @@ -55,8 +55,10 @@ rate. The tool can also timestamp the messages from the QEMU debug port. To use with QEMU run the following: -`mkfifo qemudebugpipe`\ -`qemu -chardev pipe,path=qemudebugpipe,id=seabios -device isa-debugcon,iobase=0x402,chardev=seabios ...` +``` +mkfifo qemudebugpipe +qemu -chardev pipe,path=qemudebugpipe,id=seabios -device isa-debugcon,iobase=0x402,chardev=seabios ... +``` and then in another session: @@ -84,20 +86,23 @@ bios 16bit code) or out/rom.o (to debug bios 32bit code). For example: `gdb out/rom16.o` -Once in gdb, use the command "target remote localhost:1234" to have +Once in gdb, use the command `target remote localhost:1234` to have gdb connect to QEMU. See the QEMU documentation for more information on using gdb and QEMU in this mode. -When debugging 16bit code, also run the following commands in gdb: +When debugging 16bit code it is necessary to load the 16bit symbols +twice in order for gdb to properly handle break points. To do this, +run the following command `objcopy --adjust-vma 0xf0000 out/rom16.o +rom16offset.o` and then run the following in gdb: -`set architecture i8086`\ -`add-symbol-file out/rom16.o 0xf0000` +``` +set architecture i8086 +add-symbol-file rom16offset.o 0 +``` -The second command loads the 16bit symbols a second time at an offset -of 0xf0000, which helps gdb set and catch breakpoints correctly. - -To debug a VGA BIOS image, run "gdb out/vgarom.o" add use the gdb -command "add-symbol-file out/vgarom.o 0xc0000" to load the 16bit VGA +To debug a VGA BIOS image, run `gdb out/vgarom.o`, create a +vgaromoffset.o file with offset 0xc0000, add use the gdb +command `add-symbol-file out/vgaromoffset.o 0` to load the 16bit VGA BIOS symbols twice. If debugging the 32bit SeaBIOS initialization code with gdb, note that diff --git a/qemu/roms/seabios/docs/Developer_Documentation.md b/qemu/roms/seabios/docs/Developer_Documentation.md index d50455d36..24bf48a3e 100644 --- a/qemu/roms/seabios/docs/Developer_Documentation.md +++ b/qemu/roms/seabios/docs/Developer_Documentation.md @@ -10,15 +10,16 @@ page. See details on [building SeaBIOS](Build overview). There is also information on the SeaBIOS [Memory Model](Memory Model). - Along with information on SeaBIOS [Execution and code flow](Execution -and code flow). +and code flow). A description of the process of linking the final +SeaBIOS binary is available at [Linking overview](Linking overview). -A description of the process of linking the final SeaBIOS binary is -available at [Linking overview](Linking overview). +The list of available runtime configuration items is at +[runtime config](Runtime_config). To debug SeaBIOS and report problems see SeaBIOS -[debugging](Debugging). +[debugging](Debugging). To contribute changes to SeaBIOS see +[contributing](Contributing). Useful links to specifications is available at [Developer links](Developer links). diff --git a/qemu/roms/seabios/docs/Download.md b/qemu/roms/seabios/docs/Download.md index a49c6fb74..9b1492ac5 100644 --- a/qemu/roms/seabios/docs/Download.md +++ b/qemu/roms/seabios/docs/Download.md @@ -9,8 +9,10 @@ The SeaBIOS project uses the [git](http://git-scm.com/) revision control system. To download the latest source from revision control, run: -`$ git clone git://git.seabios.org/seabios.git seabios`\ -`$ cd seabios` +``` +$ git clone git://git.seabios.org/seabios.git seabios +$ cd seabios +``` There's also a [website](http://git.seabios.org/) to browse the latest source code online. diff --git a/qemu/roms/seabios/docs/Execution_and_code_flow.md b/qemu/roms/seabios/docs/Execution_and_code_flow.md index 9396ecaa4..a54776eef 100644 --- a/qemu/roms/seabios/docs/Execution_and_code_flow.md +++ b/qemu/roms/seabios/docs/Execution_and_code_flow.md @@ -36,7 +36,7 @@ process. The POST phase itself has several sub-phases. -* The "preinit" sub-phase: code run prior to code relocation. +* The "preinit" sub-phase: code run prior to [code relocation](Linking overview#Code relocation). * The "init" sub-phase: code to initialize internal variables and interfaces. * The "setup" sub-phase: code to setup hardware and drivers. diff --git a/qemu/roms/seabios/docs/Linking_overview.md b/qemu/roms/seabios/docs/Linking_overview.md index fb938b632..bcb8298c3 100644 --- a/qemu/roms/seabios/docs/Linking_overview.md +++ b/qemu/roms/seabios/docs/Linking_overview.md @@ -92,15 +92,9 @@ those situations where an address of a C function in another mode is required the build supports symbols with a special "\_cfuncX_" prefix. The layoutrom.py script detects these references and will emit a corresponding symbol definitions in the linker script that points to -the C code of the specified mode. This is typically seen with code -like: - -`extern void _cfunc32flat_process_op(void);`\ -`return call32(_cfunc32flat_process_op, 0, 0);` - -In the above example, when the build finds the symbol -"\_cfunc32flat_process_op" it will emit that symbol with the physical -address of the 32bit "flat" version of the process_op() C function. +the C code of the specified mode. The call32() and stack_hop_back() +macros automatically add the required prefix for C code, but the +prefixes need to be explicitly added in assembler code. Build garbage collection ------------------------ diff --git a/qemu/roms/seabios/docs/Releases.md b/qemu/roms/seabios/docs/Releases.md index 6a1ecd564..c24d3c0b7 100644 --- a/qemu/roms/seabios/docs/Releases.md +++ b/qemu/roms/seabios/docs/Releases.md @@ -1,6 +1,25 @@ History of SeaBIOS releases. Please see [download](Download) for information on obtaining these releases. +SeaBIOS 1.9.0 +============= + +Available on 20151117. Major changes in this release: + +* The default boot menu key is now the ESC key (instead of F12) +* Initial support for Trusted Platform Module (TPM) hardware and BIOS calls +* Initial support for chain loading SeaBIOS from Grub (via multiboot + support) +* Initial support for booting from SD cards on real hardware +* virtio 1.0 device support +* The build will no longer include the build hostname or build time on + "clean" builds. This makes the build binaries more "reproducible". +* Basic support for running SeaBIOS on Baytrail Chromebooks +* SeaVGABIOS improvements: + * Improved support for old versions of x86emu (the "leal" + instruction is now emulated) +* Several bug fixes and code cleanups + SeaBIOS 1.8.0 ============= @@ -23,6 +42,16 @@ two release numbers (eg, 1.8) and stable releases will use three numbers (eg, 1.8.1). The prior behavior of using a forth number (eg, 1.7.5.1) for stable releases will no longer be used. +SeaBIOS 1.8.1 +------------- + +Available on 20150316. Stable release containing only bug fixes. + +SeaBIOS 1.8.2 +------------- + +Available on 20150617. Stable release containing only bug fixes. + SeaBIOS 1.7.5 ============= diff --git a/qemu/roms/seabios/docs/Runtime_config.md b/qemu/roms/seabios/docs/Runtime_config.md new file mode 100644 index 000000000..d6fea2827 --- /dev/null +++ b/qemu/roms/seabios/docs/Runtime_config.md @@ -0,0 +1,191 @@ +SeaBIOS can read several configuration items at runtime. On coreboot +the configuration comes from files located in CBFS. When SeaBIOS runs +natively on QEMU the files are passed from QEMU via the fw_cfg +interface. + +This page documents the user visible configuration and control +features that SeaBIOS supports. + +LZMA compression +================ + +On coreboot, when scanning files in CBFS, any filename that ends with +a ".lzma" suffix will be treated as a raw file that is compressed with +the lzma compression algorithm. This works for option ROMs, +configuration files, floppy images, etc. . (This feature should not be +used with embedded payloads - to compress payloads, use the standard +section based compression algorithm that is built into the payload +specification.) + +For example, the file **pci1106,3344.rom.lzma** would be treated the +same as **pci1106,3344.rom**, but will be automatically uncompressed +when accessed. + +A file is typically compressed with the lzma compression command line +tool. For example: + +`lzma -zc /path/to/somefile.bin > somefile.bin.lzma` + +However, some recent versions of lzma no longer supply an uncompressed +file size in the lzma header. (They instead populate the field with +zero.) Unfortunately, SeaBIOS requires the uncompressed file size, so +it may be necessary to use a different version of the lzma tool. + +File aliases +============ + +It is possible to create the equivalent of "symbolic links" so that +one file's content appears under another name. To do this, create a +**links** file with one line per link and each line having the format +of "linkname" and "destname" separated by a space character. For +example, the **links** file may look like: + +``` +pci1234,1000.rom somerom.rom +pci1234,1001.rom somerom.rom +pci1234,1002.rom somerom.rom +``` + +The above example would cause SeaBIOS to treat "pci1234,1000.rom" or +"pci1234,1001.rom" as files with the same content as the file +"somerom.rom". + +Option ROMs +=========== + +SeaBIOS will scan all of the PCI devices in the target machine for +option ROMs on PCI devices. It recognizes option ROMs in files that +have the form **pciVVVV,DDDD.rom**. The VVVV,DDDD should correspond to +the PCI vendor and device id of a device in the machine. If a given +file is found then SeaBIOS will deploy the file instead of attempting +to extract an option ROM from the device. In addition to supplying +option ROMs for on-board devices that do not store their own ROMs, +this mechanism may be used to prevent a ROM on a specific device from +running. + +SeaBIOS always deploys the VGA rom associated with the active VGA +device before any other ROMs. + +In addition, SeaBIOS will also run any file in the directory +**vgaroms/** as a VGA option ROM not specific to a device and files in +**genroms/** as a generic option ROM not specific to a device. The +ROMS in **vgaroms/** are run immediately after running the option ROM +associated with the primary VGA device (if any were found), and the +**genroms/** ROMs are run after all other PCI ROMs are run. + +Bootsplash images +================= + +SeaBIOS can show a custom [JPEG](http://en.wikipedia.org/wiki/JPEG) +image or [BMP](http://en.wikipedia.org/wiki/BMP_file_format) image +during bootup. To enable this, add the JPEG file to flash with the +name **bootsplash.jpg** or BMP file as **bootsplash.bmp**. + +The size of the image determines the video mode to use for showing the +image. Make sure the dimensions of the image exactly correspond to an +available video mode (eg, 640x480, or 1024x768), otherwise it will not +be displayed. + +SeaBIOS will show the image during the wait for the boot menu (if the +boot menu has been disabled, users will not see the image). The image +should probably have "Press ESC for boot menu" embedded in it so users +know they can enter the normal SeaBIOS boot menu. By default, the boot +menu prompt (and thus graphical image) is shown for 2.5 seconds. This +can be customized via a [configuration +parameter](#Other_Configuration_items). + +The JPEG viewer in SeaBIOS uses a simplified decoding algorithm. It +supports most common JPEGs, but does not support all possible formats. +Please see the [trouble reporting section](Debugging) if a valid image +isn't displayed properly. + +Payloads +======== + +On coreboot, SeaBIOS will treat all files found in the **img/** +directory as a coreboot payload. Each payload file will be available +for boot, and one can select from the available payloads in the +bootmenu. SeaBIOS supports both uncompressed and lzma compressed +payloads. + +Floppy images +============= + +It is possible to embed an image of a floppy into a file. SeaBIOS can +then boot from and redirect floppy BIOS calls to the image. This is +mainly useful for legacy software (such as DOS utilities). To use this +feature, place a floppy image into the directory **floppyimg/**. + +Using LZMA file compression with the [.lzma file +suffix](#LZMA_compression) is a useful way to reduce the file +size. Several floppy formats are available: 360K, 1.2MB, 720K, 1.44MB, +2.88MB, 160K, 180K, 320K. + +The floppy image will appear as writable to the system, however all +writes are discarded on reboot. + +When using this system, SeaBIOS reserves high-memory to store the +floppy. The reserved memory is then no longer available for OS use, so +this feature should only be used when needed. + +Configuring boot order +====================== + +The **bootorder** file may be used to configure the boot up order. The +file should be ASCII text and contain one line per boot method. The +description of each boot method follows an [Open +Firmware](https://secure.wikimedia.org/wikipedia/en/wiki/Open_firmware) +device path format. SeaBIOS will attempt to boot from each item in the +file - first line of the file first. + +The easiest way to find the available boot methods is to look for +"Searching bootorder for" in the SeaBIOS debug output. For example, +one may see lines similar to: + +``` +Searching bootorder for: /pci@i0cf8/*@f/drive@1/disk@0 +Searching bootorder for: /pci@i0cf8/*@f,1/drive@2/disk@1 +Searching bootorder for: /pci@i0cf8/usb@10,4/*@2 +``` + +The above represents the patterns SeaBIOS will search for in the +bootorder file. However, it's safe to just copy and paste the pattern +into bootorder. For example, the file: + +``` +/pci@i0cf8/usb@10,4/*@2 +/pci@i0cf8/*@f/drive@1/disk@0 +``` + +will instruct SeaBIOS to attempt to boot from the given USB drive +first and then attempt the given ATA harddrive second. + +SeaBIOS also supports a special "HALT" directive. If a line that +contains "HALT" is found in the bootorder file then SeaBIOS will (by +default) only attempt to boot from devices explicitly listed above +HALT in the file. + +Other Configuration items +========================= + +There are several additional configuration options available in the +**etc/** directory. + +| Filename | Description +|---------------------|--------------------------------------------------- +| show-boot-menu | Controls the display of the boot menu. Set to 0 to disable the boot menu. +| 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.) +| 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. +| boot-menu-wait | Amount of time (in milliseconds) to wait at the boot menu prompt before selecting the default boot. +| 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 +| 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. +| 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. +| 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. +| 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). +| s3-resume-vga-init | Set this to a non-zero value to instruct SeaBIOS to run the vga rom on an S3 resume. +| 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. +| 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. +| floppy0 | Set this to the type of the first floppy drive in the system (only type 4 for 3.5 inch drives is supported). +| floppy1 | The type of the second floppy drive in the system. See the description of **floppy0** for more info. +| 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. +| 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. diff --git a/qemu/roms/seabios/docs/SeaBIOS.md b/qemu/roms/seabios/docs/SeaBIOS.md index 831bfced9..e24913a64 100644 --- a/qemu/roms/seabios/docs/SeaBIOS.md +++ b/qemu/roms/seabios/docs/SeaBIOS.md @@ -10,6 +10,8 @@ information on using SeaBIOS in coreboot. Please see the [releases](Releases) page for information on recent releases. See the [download](Download) page to obtain SeaBIOS. +[SeaVGABIOS](SeaVGABIOS) is a sub-project of SeaBIOS. + Please join the [mailing list](Mailinglist) to contribute to SeaBIOS. Information on the internals of SeaBIOS is available on the [Developer Documentation](Developer Documentation) page. diff --git a/qemu/roms/seabios/docs/SeaVGABIOS.md b/qemu/roms/seabios/docs/SeaVGABIOS.md new file mode 100644 index 000000000..7ec27804d --- /dev/null +++ b/qemu/roms/seabios/docs/SeaVGABIOS.md @@ -0,0 +1,39 @@ +SeaVGABIOS is a sub-project of the SeaBIOS project - it is an open +source implementation of a 16bit X86 +[VGA BIOS](http://en.wikipedia.org/wiki/Video_BIOS). SeaVGABIOS is the +default VGA BIOS on [QEMU](http://www.qemu.org/). SeaVGABIOS can also +run natively on some X86 VGA hardware with +[coreboot](http://www.coreboot.org/). + +Building SeaVGABIOS +=================== + +To build SeaVGABIOS, obtain the [code](Download), run `make +menuconfig` and select the type of VGA BIOS to build in the "VGA ROM" +menu. Once selected, run `make` and the final VGA BIOS binary will be +located in "out/vgabios.bin". + +The choice of available VGA BIOSes within "make menuconfig" is +dependent on whether CONFIG_QEMU, CONFIG_COREBOOT, or CONFIG_CSM is +selected. Also, the debug options under the "Debugging" menu apply to +SeaVGABIOS. All other options found in "make menuconfig" apply only to +SeaBIOS and will not impact the SeaVGABIOS build. + +If SeaVGABIOS is needed for multiple different devices (eg, QEMU's +cirrus emulation and QEMU's "dispi" emulation), then one must compile +SeaVGABIOS multiple times with the appropriate config for each build. + +SeaVGABIOS code +=============== + +The source code for SeaVGABIOS is located in the SeaBIOS +[git repository](Download). The main VGA BIOS code is located in the +"vgasrc/" directory. The VGA BIOS code is always compiled in 16bit +mode. + +The SeaVGABIOS builds to a separate binary from the main SeaBIOS +binary, and much of the VGA BIOS code is separate from the main BIOS +code. However, much of the SeaBIOS +[developer documentation](Developer_Documentation) applies to +SeaVGABIOS. To contribute, please join the +[SeaBIOS mailing list](Mailinglist). |