switch-coreboot/README

-------------------------------------------------------------------------------
coreboot README
-------------------------------------------------------------------------------

Coreboot is a Free Software project aimed at replacing the proprietary
BIOS you can find in most of today's computers.

It performs just a little bit of hardware initialization and then executes
one of many possible payloads.


Payloads
--------

After the basic initialization of the hardware has been performed, any
desired "payload" can be started by coreboot. Examples include:

 * A Linux kernel
 * FILO (a simple bootloader with filesystem support)
 * GRUB2 (a free bootloader; support is in development)
 * OpenBIOS (a free IEEE1275-1994 Open Firmware implementation)
 * Open Firmware (a free IEEE1275-1994 Open Firmware implementation)
 * SmartFirmware (a free IEEE1275-1994 Open Firmware implementation)
 * GNUFI (a free, UEFI-compatible firmware)
 * Etherboot (for network booting and booting from raw IDE or FILO)
 * ADLO (for booting Windows 2000 or OpenBSD)
 * Plan 9 (a distributed operating system)
 * memtest86 (for testing your RAM)


Supported Hardware
------------------

Coreboot supports a wide range of chipsets, devices, and mainboards.

For details please consult:

 * http://www.coreboot.org/Supported_Motherboards
 * http://www.coreboot.org/Supported_Chipsets_and_Devices


Build Requirements
------------------

 * gcc / g++
 * make
 * bison
 * flex
 * libncurses5-dev

Optional (for generating/viewing documentation):

 * lyx
 * doxygen


Building And Installing
-----------------------

Note: Currently only the x86 QEMU target is supported in coreboot-v3.

1) Build a payload:

  THIS IS NOT IMPLEMENTED YET. PLEASE BUILD YOUR PAYLOAD MANUALLY.

  $ make payload

  This step is optional. The 'make payload' command will execute a
  helper tool which allows you to easily build and configure a wide
  variety of payloads. The result of this step is usually a file
  called 'payload.elf' in the top-level directory.

2) Configure coreboot:

  $ make menuconfig

  Select at least the desired mainboard vendor, the mainboard device, and
  the size of your ROM chip. Per default coreboot will look for a file
  called 'payload.elf' in the current directory and use that as the payload.

  If that's not what you want, you can change the path/filename of the
  payload to use some other payload file. Or you can choose 'No payload'
  in the configuration menu, in which case the resulting coreboot ROM image
  will not contain any payload. You'll have to manually add a payload
  later using the 'lar' utility for the coreboot ROM image to be useful.

3) Build the coreboot ROM image:

  $ make

  The generated ROM image is the file coreboot.rom in the build/ directory.

4) Flash the coreboot ROM image on a BIOS chip:

  $ flashrom -wv coreboot.rom

  NOTE: This step will OVERWRITE the current BIOS located on the ROM chip!
  Make sure you have adequate backup facilities before performing this
  step, otherwise you might not be able to recover in case of problems.
  If you have any questions, please contact us on the mailing list!

  The 'flashrom' tool is located in util/flashrom where you can build it
  from source code by typing 'make'. Alternatively, your favorite Linux
  distribution might ship a 'flashrom' package which provides the 'flashrom'
  program in (e.g.) /usr/sbin. On Debian GNU/Linux systems you can get
  the flashrom package via 'apt-get install flashrom'.


Testing coreboot Without Modifying Your Hardware
-------------------------------------------------

If you want to test coreboot without any risks before you really decide
to use it on your hardware, you can use the QEMU system emulator to run
coreboot virtually in QEMU.

The required steps are:

  $ make menuconfig

    Select 'Emulated systems' as mainboard vendor and 'QEMU x86' as
    mainboard model.

  $ make

  $ qemu -L build -hda /dev/zero -serial stdio

  This will run coreboot in QEMU and output all debugging messages (which
  are usually emitted to a serial console) on stdout. It will not do
  anything useful beyond that, as you provided no virtual harddrive to
  QEMU (-hda /dev/zero).

  If you have a full QEMU hard drive image (say /tmp/qemu.img) with a Linux
  distribution installed, you can boot that Linux kernel by using a proper
  FILO payload with coreboot and typing:

  $ qemu -L build -hda /tmp/qemu.img -serial stdio

  Installing a Linux distribution in QEMU and building the FILO payload is
  beyond the scope of this document.


Website and Mailing List
------------------------

Further details on the project, a FAQ, many HOWTOs, news, development
guidelines and more can be found on the coreboot website:

  http://www.coreboot.org

You can contact us directly on the coreboot mailing list:

  http://www.coreboot.org/Mailinglist


Copyright and License
---------------------

The copyright on coreboot is owned by quite a large number of individual
developers and companies. Please check the individual source files for details.

Coreboot is licensed under the terms of the GNU General Public License (GPL).
Some files are licensed under the "GPL (version 2, or any later version)",
and some files are licensed under the "GPL, version 2". For some parts,
which were derived from other Free Software projects, other (GPL-compatible)
licenses may apply. Please check the individual source files for details.

This makes the resulting coreboot images licensed under the GPL, version 2.