1) About SGABIOS
================
The Google Serial Graphics Adapter BIOS or SGABIOS allows one to interact with
a physical or emulated system independent from the operation system on BIOS
level. It does that by providing over a serial port the output capabilities
normally featured by a VGA graphics card and the input capabilities normally
handled by a keyboard. This is useful for selecting a boot-device during
startup or to access feature provided by option roms (e.g. accessing a gPXE
console). Further details can be found in file design.txt or online at
<https://code.google.com/p/sgabios/>.


2) What does SGABIOS works with?
================================
SGABIOS is a 16bit X86 bios option rom. Therefore it can run only on physical
or emulated x86 hardware and has to be called from a compatible 16bit X86 BIOS.
SeaBIOS <http://www.seabios.org/> is a 16bit X86 BIOS known to work together
with SGABIOS.


2.1) Using SGABIOS on physical X86 hardware
===========================================
If you plan to equip physical X86 hardware with a SGABIOS enabled SeaBIOS, you
can do this by using coreboot. Doing this is not scope of this README, but
instructions how to do this can be found at <https://www.coreboot.org/SeaBIOS>.
Please be warned that you can easily fry your physical X86 hardware if you
flash over our existing BIOS - especially if the new contents of the flash is
not provided by the vendor of our hardware.


2.2) Using SGABIOS on emulated X86 hardware
===========================================
For serial BIOS redirection with emulated X86 hardware, SGABIOS can be used
together with qemu, since SeaBIOS is used by qemu for x86 based emulated
hardware and SeaBIOS features support for addressing the SGABIOS option rom
at the right stage during startup. Other emulators for virtual machines might
support SGABIOS as well, but are not covered by this README.


3) SGABIOS with qemu
====================
Since I/O of the virtual server driven by qemu is provided through a serial
device, it is possible with qemu to redirect this on the host system in
various ways. One possibility is to the redirect it on the host system using
telnet, allowing easy remote access to the virtual server without using VNC.
For other ways to redirect the serial device on the host system, please
take a look into the man page of qemu(1) and search for option "-serial"
in it.


3.1) Using SGABIOS together with qemu
=====================================
Note that you need qemu to emulate X86 hardware for SGABIOS. In Debian you
therefore need to install the package qemu-system-x86.

3.1.1) Standalone SGABIOS
-------------------------
It is possible to use SGABIOS with no other graphic adapter installed. In
order to do so, start qemu with the following additional options:
  -vga none -display none -device sga
Output will be send solely to the serial device in this case.


3.1.1.2) Hybrid SGABIOS and VGA graphic adapter
-----------------------------------------------
Using SGABIOS it is supported to have output on the virtual graphics card
as well as on the serial device. To achieve this, start qemu with the
following two additional options:
  -vga cirrus -device sga
Output will be send to virtual graphics card and the serial device.


3.2) Limitations of SGABIOS with qemu
=====================================
SGABIOS will always use the first serial device configured in qemu using
the option "-serial". By default qemu configures a first serial device of
type "vc" in graphical mode and "stdio" in non graphical mode, as long as
neither option "-nodefaults" nor a option "-serial" is provided. Therefor
it is strongly recommended to always provide a option "-serial (...)"
together with "-device sga".


3.3) Examples how to use SGABIOS together with qemu
===================================================
The commands and qemu-system-i386 and qemu-system-x86_64 mentioned in the
examples below can be found in the Debian package qemu-system-x86.

3.3.1 ) Use VNC to access the graphical and telnet to access the serial output
------------------------------------------------------------------------------

a) Start qemu (you can use either use qemu-system-i386 or qemu-system-x86_64):
# qemu-system-x86_64 -boot menu=on -vga cirrus -vnc localhost:1 \
                     -device sga -serial telnet:localhost:4444,server

b) Connect via telnet:
# telnet localhost 4444

c) Connect via VNC:
# vncviewer localhost:1


3.3.2 ) Only provide serial access via telnet by multiplexing the qemu-monitor
------------------------------------------------------------------------------

a) Start qemu (you can use either use qemu-system-i386 or qemu-system-x86_64):
# qemu-system-x86_64 -boot menu=on -vga none -display none \
                     -device sga -serial mon:telnet:localhost:4444,server

b) Connect via netcat:
# telnet localhost 4444

c) Toggle between serial console and qemu-monitor:
Press '<ctrl>' and 'a' together, followed by a press of 'c'.


 -- Daniel Beyer <dabe@deb.ymc.ch>  Mon, 22 Aug 2016 16:16:03 +0200
