historical/m0-applesillicon.git/xnu-qemu-arm64-5.1.0/roms/sgabios/design.txt

=============================================
Google Serial Graphics Adapter BIOS (SGABIOS)

Copyright 2007 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
=============================================
Status: Implemented (as of 2007-08-08)

Nathan Laredo <nil@google.com>
Modified: 2008-02-14 13:45 PDT


Objective
---------

The Google Serial Graphics Adapter BIOS or SGABIOS provides a means
for legacy pc software to communicate with an attached serial console
as if a vga card is attached.

Background
----------

The headless server problem

When building a lot of systems for data center use, it makes
no sense to install hardware that will rarely if ever be used.
Graphics adapters are not very useful even if they are installed
in a data center environment since often the person interested in
seeing the output is separated from the device by tens to thousands
of miles.

While it's possible to use remote management hardware that provides
a remotely accessible display and keyboard, this hardware is much
more expensive than the hardware that it replaces, and often this
hardware sends only images of the display rather than something
suitable for logging.

Since most systems already have a serial port, it's an obvious
target as a replacement for the primary display and keyboard.
The problem is that while an operating system like Linux can
support this arrangement, all of the output that would normally
appear on a graphics adapter before Linux boots is lost on modern
x86 hardware without modifications to the system firmware.

While some vendors provide firmware that enables the serial port to
be used as the primary display, this is usually a "premium" option
and isn't universally available for all x86 platforms.  Often such
services aren't implemented in a way that is friendly to saving logs
of boot activity.  One particularly ugly implementation might send
the same text hundreds of times as it tries to refresh the entire
display each timer tick.   Others have ansi control sequences
between every single character output which, while readable in a
terminal, is almost unusable when referring to serial log files.
Behavior like this slows down the serial output by up to fifteen
times in some cases, using sometimes that many extra characters
of control sequences for each character output.

The need for detailed system logs

None of the vendor-supplied serial redirection implementations
include facilities for logging boot message for later capture by
an operating system.  Being able to refer to the boot messages
after an operating system has loaded, or having a history of such
messages can be a useful debug, analysis, and management feature.

Even on systems with graphics adapters attached, once the display
is scrolled or refreshed with enough new text, the old messages
are only available in the user's own brain, which often isn't
very good at accurately recalling more than two or three items
that aren't grammatically meaningful in the user's native language.

Overview
---------
SGABIOS is designed to be inserted into a bios as an option rom
to provide over a serial port the display and input capabilites
normally handled by a VGA adapter and a keyboard, and additionally
provide hooks for logging displayed characters for later collection
after an operating system boots.

It is designed to handle all text mode output sent to the legacy
bios int 10h service routine.  Int 10h is the most common method
for displaying characters in 16-bit legacy x86 code.

Occasionally some code may write directly to the vga memory in
the interest of "speed," and this output will be missed, but
it's rather uncommon for any code involved in booting a system
to be concerned with the speed of display output.  SGABIOS is not
designed to handle these cases since those applications that make
such assumptions generally write to an area of memory that typically
already in use for system management mode and unusable outside of
that mode.   Paging tricks could be used to capture such output,
but enabling paging requires protected mode to be enabled which
instantly breaks all segment loads in legacy 16-bit real- mode code
(which is the traditional boot environment).

Detailed Design
----------------

VGA BIOS int 10h is hooked and chained to any existing handler or
the default handler that the BIOS previously setup.

During initialization, the option rom also probes the serial port
for reply from an attached terminal.  If the terminal replies to
a specific sequence, the terminal size is recorded and used for
all future display calculations.   If a VGA card is attached at
the same time, the width of the terminal is limited to 80 columns
in order to have sensible output on both the VGA card and on the
serial console.  If no reply comes from the serial terminal within
a very short timeout of about 8 milliseconds (or more accurately,
65536 reads of the serial status port), a default size of 80x24
is used.  The detected size is displayed at the end of option rom
init to the serial console.

Because of the way the cursor is updated, if the cursor is never
moved upwards or more than one line down by int 10h calls, output
will still be appear completely appropriate for whatever sized
terminal is attached but failed to get detected.

Whenever int 10h is invoked, SGABIOS gets control first and decides
whether to act based on register state.   With the exception of
functions for getting current mode info or the current cursor
position, whether it acts or not, register state is ultimately
restored to the state on entry and a far jump is made to the
original handler.

SGABIOS maintains two active cursor positions.  One contains the
traditional VGA cursor position at the traditional location in
the BIOS Data Area, while the other maintains the position the
serial console's cursor is located.  The serial cursor position
is located in a BDA location that traditionally contains the
base io port address for LPT3, but since builtin printer ports are
disappearing over time, this location is reused. These two values
will often differ since serial terminal output will always move
the cursor to the next position on the screen while many VGA
operations don't update the cursor position at all, or some only
at the start of the string, but leave the old value at the end.
Keeping track of two active cursor positions means that SGABIOS
can collapse a string of "set cursor" calls into perhaps a single
one or none if the serial console cursor already happens to be at
the target location.    Cursor movements are further optimized
by sending newline characters to move the cursor down one row,
carriage return characters to move the cursor back to column 0,
and backspace characters to send the cursor back one or two spaces.

To avoid problems when a video card is connected, any Bios Data
Area location that would be updated by a VGA card is left alone
to be updated by the VGA card.  SGABIOS will update the cursor
position as usual, but just before chaining to an existing vga
card's handler, it will restore the values to those on entry,
and for those functions that return data, it will defer completely
to the chained routines rather than taking those over as it does
when no video card is detected.

Cursor position updates to serial console are deferred until the
next character of terminal output is available.   This collapses
the cases where the cursor is updated more than one time between
each character output (this is surprisingly common).

The goal of tracking the cursor so closely and minimizing the number
of characters required to update the cursor position is to both to
make the display of output as efficient and fast as possible and
to allow one to grep a raw log of serial console output for text
(which without such optimization may be impossible or extremely
difficult with movement escape sequences between every character).

In the same way cursor position is tracked, vga character attributes
are tracked so that it's possible to minimize the number of times
an attribute change escape sequence is sent to the serial console.

A BIOS Data Area location traditionally used for storing the
current palette value is used to store the last attribute sent to
the serial console.  As SGABIOS processes new calls, if the value
is the same, after masking off bright background colors which
aren't supported in ansi escape codes, then no attribute update
is sent to the serial console, else an escape sequence is sent
that gives the new background and foreground colors and whether
the foreground is bold or not.

Data communication

Whenever the call is made to output text, SGABIOS first updates
the serial terminal cursor to match the current position of
the vga cursor (if necessary), outputs any attribute change if
applicable to the particular int 10h call made, and finally sends
the text character (or characters) out to the serial port, and then
updates its own view of where the serial console cursor is located.
After the text is sent, a logging routine is called to store that
text in a private area of memory allocated at option rom init.

For keyboard/terminal input, SGABIOS hooks bios int 16h which is
typically called to poll for a keypress.  Before passing the call
along, SGABIOS looks for any pending input on the serial port and
stuffs the keyboard buffer with any pending byte after translating
it to a compatible keyboard scancode.   If the character received
is an escape, SGABIOS will continue to poll for up to four extra
characters of input for several milliseconds in order to detect
ANSI/VT100/xterm/etc cursor keys and function keys, looking up
appropriate scancodes in a table of escape sequences for all
known non-conflicting terminal types.

SGABIOS also hooks the serial port interrupts, and on receiving
an interrupt blocks out interrupts, calls the same polling
routines as above, following the same processing of multi-byte
input as well, stuffing the keyboard buffer as appropriate,
and finally acknowledging the interrupt and returning from the
handler. [ serial port interrupts are now DISABLED ]

Optionally the serial port input/output can be replaced with
a SMI trigger that calls into an EFI BIOS in order to tie into
its own console input and output routines rather than directly
hitting the serial port.   In this particular case it's assumed
that all logging is handled in the EFI module that will be called.
BIOS int 15h, ax = 0d042h is used to trigger SMI.  The parameters
passed will need to be changed to be specific to the EFI or SMI
handler put in place.   In the example in SMBIOS, for output,
ebx = 0xf00d0000 | (char << 8), and for input, ebx = 0xfeed0000,
with the character, if any, returned in the eax register with ZF
set and eax=0 if no character was available.

Summary of new enhancements
---------------------------
SGABIOS now keeps a log of the last 256 characters written to
the screen and where they were written in the event an application
like lilo asks for the current character under the cursor.  These
are currently stored in a 1KB EBDA allocation which can be expanded
as needed.  This method avoids having to store a 64KB buffer for
the largest possible serial terminal supported (255x255).

When lilo 22.6 is detected, SGABIOS now knows how to disable
lilo's serial output in favor of its own.  This avoids having
double character output from both serial and VGABIOS interleaved.

Possible future enhancements
----------------------------
Previous future ideas have now been implemented.

Known Bugs
----------
With some versions of DOS, only the last character of every line
is displayed once dos boots since DOS will use direct access to
the VGA framebuffer until the end of line is reached, at which
point it will start using int 10h.  Dual cursor tracking might
fix this issue by maintaining positions for dos that look like
the end of line and another for internal use to know where to
output next.

Caveats
-------
It may be possible for someone to construct a terminal reply for
the terminal sizing code that is completely invalid and attempts
to either setup variables to overrun buffers or else overruns
the input buffer itself.   This situation is currently handled
by limiting the reply to between eight and fourteen characters
and ignoring any values outside the range from ten to two hundred
fifty-five for both the number of rows and the number of columns.
In these situations a default size of 80x24 is used (unless a
video card is present, in which case its size is used).   If the
resize code detects several unexpected characters during the
terminal size detection, it currently assumes that someone has
left a loopback device plugged into the serial port and redirects
the serial input and output to the fourth serial port at 0x2e8.


Security considerations
-----------------------
None.  This is already 16-bit real-mode x86 code.  The entire
system may be crashed or bent to do anyone's bidding at any time
by any other running code outside of SGABIOS.


Opensource Plan
---------------
This source code was approved for release to the public for use under
the Apache License, Version 2.0 on http://code.google.com/p/sgabios


Document History
----------------
Date		Author	Description
2008-02-14	nil	fix for release
2007-10-04	nil	new features
2007-08-31	nil	sga+vga fixes
2007-08-08	nil	Initial version

$Id$