![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to design.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Qemu by Fabrice Bellard] / qemu / roms / sgabios|
Return to design.txt CVS log | Up to [Qemu by Fabrice Bellard] / qemu / roms / sgabios |
1.1 root 1: =============================================
2: Google Serial Graphics Adapter BIOS (SGABIOS)
3:
4: Copyright 2007 Google Inc.
5:
6: Licensed under the Apache License, Version 2.0 (the "License");
7: you may not use this file except in compliance with the License.
8: You may obtain a copy of the License at
9:
10: http://www.apache.org/licenses/LICENSE-2.0
11:
12: Unless required by applicable law or agreed to in writing, software
13: distributed under the License is distributed on an "AS IS" BASIS,
14: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15: See the License for the specific language governing permissions and
16: limitations under the License.
17: =============================================
18: Status: Implemented (as of 2007-08-08)
19:
20: Nathan Laredo <[email protected]>
21: Modified: 2008-02-14 13:45 PDT
22:
23:
24: Objective
25: ---------
26:
27: The Google Serial Graphics Adapter BIOS or SGABIOS provides a means
28: for legacy pc software to communicate with an attached serial console
29: as if a vga card is attached.
30:
31: Background
32: ----------
33:
34: The headless server problem
35:
36: When building a lot of systems for data center use, it makes
37: no sense to install hardware that will rarely if ever be used.
38: Graphics adapters are not very useful even if they are installed
39: in a data center environment since often the person interested in
40: seeing the output is separated from the device by tens to thousands
41: of miles.
42:
43: While it's possible to use remote management hardware that provides
44: a remotely accessible display and keyboard, this hardware is much
45: more expensive than the hardware that it replaces, and often this
46: hardware sends only images of the display rather than something
47: suitable for logging.
48:
49: Since most systems already have a serial port, it's an obvious
50: target as a replacement for the primary display and keyboard.
51: The problem is that while an operating system like Linux can
52: support this arrangement, all of the output that would normally
53: appear on a graphics adapter before Linux boots is lost on modern
54: x86 hardware without modifications to the system firmware.
55:
56: While some vendors provide firmware that enables the serial port to
57: be used as the primary display, this is usually a "premium" option
58: and isn't universally available for all x86 platforms. Often such
59: services aren't implemented in a way that is friendly to saving logs
60: of boot activity. One particularly ugly implementation might send
61: the same text hundreds of times as it tries to refresh the entire
62: display each timer tick. Others have ansi control sequences
63: between every single character output which, while readable in a
64: terminal, is almost unusable when referring to serial log files.
65: Behavior like this slows down the serial output by up to fifteen
66: times in some cases, using sometimes that many extra characters
67: of control sequences for each character output.
68:
69: The need for detailed system logs
70:
71: None of the vendor-supplied serial redirection implementations
72: include facilities for logging boot message for later capture by
73: an operating system. Being able to refer to the boot messages
74: after an operating system has loaded, or having a history of such
75: messages can be a useful debug, analysis, and management feature.
76:
77: Even on systems with graphics adapters attached, once the display
78: is scrolled or refreshed with enough new text, the old messages
79: are only available in the user's own brain, which often isn't
80: very good at accurately recalling more than two or three items
81: that aren't grammatically meaningful in the user's native language.
82:
83: Overview
84: ---------
85: SGABIOS is designed to be inserted into a bios as an option rom
86: to provide over a serial port the display and input capabilites
87: normally handled by a VGA adapter and a keyboard, and additionally
88: provide hooks for logging displayed characters for later collection
89: after an operating system boots.
90:
91: It is designed to handle all text mode output sent to the legacy
92: bios int 10h service routine. Int 10h is the most common method
93: for displaying characters in 16-bit legacy x86 code.
94:
95: Occasionally some code may write directly to the vga memory in
96: the interest of "speed," and this output will be missed, but
97: it's rather uncommon for any code involved in booting a system
98: to be concerned with the speed of display output. SGABIOS is not
99: designed to handle these cases since those applications that make
100: such assumptions generally write to an area of memory that typically
101: already in use for system management mode and unusable outside of
102: that mode. Paging tricks could be used to capture such output,
103: but enabling paging requires protected mode to be enabled which
104: instantly breaks all segment loads in legacy 16-bit real- mode code
105: (which is the traditional boot environment).
106:
107: Detailed Design
108: ----------------
109:
110: VGA BIOS int 10h is hooked and chained to any existing handler or
111: the default handler that the BIOS previously setup.
112:
113: During initialization, the option rom also probes the serial port
114: for reply from an attached terminal. If the terminal replies to
115: a specific sequence, the terminal size is recorded and used for
116: all future display calculations. If a VGA card is attached at
117: the same time, the width of the terminal is limited to 80 columns
118: in order to have sensible output on both the VGA card and on the
119: serial console. If no reply comes from the serial terminal within
120: a very short timeout of about 8 milliseconds (or more accurately,
121: 65536 reads of the serial status port), a default size of 80x24
122: is used. The detected size is displayed at the end of option rom
123: init to the serial console.
124:
125: Because of the way the cursor is updated, if the cursor is never
126: moved upwards or more than one line down by int 10h calls, output
127: will still be appear completely appropriate for whatever sized
128: terminal is attached but failed to get detected.
129:
130: Whenever int 10h is invoked, SGABIOS gets control first and decides
131: whether to act based on register state. With the exception of
132: functions for getting current mode info or the current cursor
133: position, whether it acts or not, register state is ultimately
134: restored to the state on entry and a far jump is made to the
135: original handler.
136:
137: SGABIOS maintains two active cursor positions. One contains the
138: traditional VGA cursor position at the traditional location in
139: the BIOS Data Area, while the other maintains the position the
140: serial console's cursor is located. The serial cursor position
141: is located in a BDA location that traditionally contains the
142: base io port address for LPT3, but since builtin printer ports are
143: disappearing over time, this location is reused. These two values
144: will often differ since serial terminal output will always move
145: the cursor to the next position on the screen while many VGA
146: operations don't update the cursor position at all, or some only
147: at the start of the string, but leave the old value at the end.
148: Keeping track of two active cursor positions means that SGABIOS
149: can collapse a string of "set cursor" calls into perhaps a single
150: one or none if the serial console cursor already happens to be at
151: the target location. Cursor movements are further optimized
152: by sending newline characters to move the cursor down one row,
153: carriage return characters to move the cursor back to column 0,
154: and backspace characters to send the cursor back one or two spaces.
155:
156: To avoid problems when a video card is connected, any Bios Data
157: Area location that would be updated by a VGA card is left alone
158: to be updated by the VGA card. SGABIOS will update the cursor
159: position as usual, but just before chaining to an existing vga
160: card's handler, it will restore the values to those on entry,
161: and for those functions that return data, it will defer completely
162: to the chained routines rather than taking those over as it does
163: when no video card is detected.
164:
165: Cursor position updates to serial console are deferred until the
166: next character of terminal output is available. This collapses
167: the cases where the cursor is updated more than one time between
168: each character output (this is surprisingly common).
169:
170: The goal of tracking the cursor so closely and minimizing the number
171: of characters required to update the cursor position is to both to
172: make the display of output as efficient and fast as possible and
173: to allow one to grep a raw log of serial console output for text
174: (which without such optimization may be impossible or extremely
175: difficult with movement escape sequences between every character).
176:
177: In the same way cursor position is tracked, vga character attributes
178: are tracked so that it's possible to minimize the number of times
179: an attribute change escape sequence is sent to the serial console.
180:
181: A BIOS Data Area location traditionally used for storing the
182: current palette value is used to store the last attribute sent to
183: the serial console. As SGABIOS processes new calls, if the value
184: is the same, after masking off bright background colors which
185: aren't supported in ansi escape codes, then no attribute update
186: is sent to the serial console, else an escape sequence is sent
187: that gives the new background and foreground colors and whether
188: the foreground is bold or not.
189:
190: Data communication
191:
192: Whenever the call is made to output text, SGABIOS first updates
193: the serial terminal cursor to match the current position of
194: the vga cursor (if necessary), outputs any attribute change if
195: applicable to the particular int 10h call made, and finally sends
196: the text character (or characters) out to the serial port, and then
197: updates its own view of where the serial console cursor is located.
198: After the text is sent, a logging routine is called to store that
199: text in a private area of memory allocated at option rom init.
200:
201: For keyboard/terminal input, SGABIOS hooks bios int 16h which is
202: typically called to poll for a keypress. Before passing the call
203: along, SGABIOS looks for any pending input on the serial port and
204: stuffs the keyboard buffer with any pending byte after translating
205: it to a compatible keyboard scancode. If the character received
206: is an escape, SGABIOS will continue to poll for up to four extra
207: characters of input for several milliseconds in order to detect
208: ANSI/VT100/xterm/etc cursor keys and function keys, looking up
209: appropriate scancodes in a table of escape sequences for all
210: known non-conflicting terminal types.
211:
212: SGABIOS also hooks the serial port interrupts, and on receiving
213: an interrupt blocks out interrupts, calls the same polling
214: routines as above, following the same processing of multi-byte
215: input as well, stuffing the keyboard buffer as appropriate,
216: and finally acknowledging the interrupt and returning from the
217: handler. [ serial port interrupts are now DISABLED ]
218:
219: Optionally the serial port input/output can be replaced with
220: a SMI trigger that calls into an EFI BIOS in order to tie into
221: its own console input and output routines rather than directly
222: hitting the serial port. In this particular case it's assumed
223: that all logging is handled in the EFI module that will be called.
224: BIOS int 15h, ax = 0d042h is used to trigger SMI. The parameters
225: passed will need to be changed to be specific to the EFI or SMI
226: handler put in place. In the example in SMBIOS, for output,
227: ebx = 0xf00d0000 | (char << 8), and for input, ebx = 0xfeed0000,
228: with the character, if any, returned in the eax register with ZF
229: set and eax=0 if no character was available.
230:
231: Summary of new enhancements
232: ---------------------------
233: SGABIOS now keeps a log of the last 256 characters written to
234: the screen and where they were written in the event an application
235: like lilo asks for the current character under the cursor. These
236: are currently stored in a 1KB EBDA allocation which can be expanded
237: as needed. This method avoids having to store a 64KB buffer for
238: the largest possible serial terminal supported (255x255).
239:
240: When lilo 22.6 is detected, SGABIOS now knows how to disable
241: lilo's serial output in favor of its own. This avoids having
242: double character output from both serial and VGABIOS interleaved.
243:
244: Possible future enhancements
245: ----------------------------
246: Previous future ideas have now been implemented.
247:
248: Known Bugs
249: ----------
250: With some versions of DOS, only the last character of every line
251: is displayed once dos boots since DOS will use direct access to
252: the VGA framebuffer until the end of line is reached, at which
253: point it will start using int 10h. Dual cursor tracking might
254: fix this issue by maintaining positions for dos that look like
255: the end of line and another for internal use to know where to
256: output next.
257:
258: Caveats
259: -------
260: It may be possible for someone to construct a terminal reply for
261: the terminal sizing code that is completely invalid and attempts
262: to either setup variables to overrun buffers or else overruns
263: the input buffer itself. This situation is currently handled
264: by limiting the reply to between eight and fourteen characters
265: and ignoring any values outside the range from ten to two hundred
266: fifty-five for both the number of rows and the number of columns.
267: In these situations a default size of 80x24 is used (unless a
268: video card is present, in which case its size is used). If the
269: resize code detects several unexpected characters during the
270: terminal size detection, it currently assumes that someone has
271: left a loopback device plugged into the serial port and redirects
272: the serial input and output to the fourth serial port at 0x2e8.
273:
274:
275: Security considerations
276: -----------------------
277: None. This is already 16-bit real-mode x86 code. The entire
278: system may be crashed or bent to do anyone's bidding at any time
279: by any other running code outside of SGABIOS.
280:
281:
282: Opensource Plan
283: ---------------
284: This source code was approved for release to the public for use under
285: the Apache License, Version 2.0 on http://code.google.com/p/sgabios
286:
287:
288: Document History
289: ----------------
290: Date Author Description
291: 2008-02-14 nil fix for release
292: 2007-10-04 nil new features
293: 2007-08-31 nil sga+vga fixes
294: 2007-08-08 nil Initial version
295:
296: $Id$
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.