.RP
.TL
EMULATORS IN WORKSTATION UNIX
.AU
By David O. Bundy
Research System Programmer for ACIS/IBM
.AL
.AI
Institute for Research in Information and Scholarship
Brown University
Providence, Rhode Island 02912
.AB
This paper explains the need for and design of Emulators in
Workstation UNIX.
The development of this emulator package under UNIX was driven by the
fact that the existing line discipline and console driver interface do not
support the complexities of today's new workstations.
The complexities are that today's workstations do not consist of dumb
hardcopy terminals or character oriented consoles but
elaborate bitmapped displays with an assortment
of sizes, densities, capabilities, and protocols.
Workstations also include sophisticated keyboards
and mice that are separate from the terminal hardware
and need a different device driver.
To further complicate things, we can hang a mouse off any serial
port supported by the workstation and expect these mice to interact with the
console.  Lastly, you can have more than one console or mouse on the 
workstation simultaneously.
The challenge is to develop a package to which it is easy to add existing and
new devices.  This package should be flexible enough to handle any
combination and number of devices at the same time.
.AE
.NH
History
.PP
In traditional UNIX the console driver takes character input
from a hardcopy terminal, send it to the selected line discipline to do
any filtering, and then echo the character back to
the console by passing it back to the hardware with
appropriate parity.
The line discipline filter performs any special functions depending on
the data passed (e.g. on receiving a delete character
the line discipline sends a signal to the process
running on the console).
.PP
Eventually non-hardcopy consoles with more intelligence appeared,
which could
decipher special character sequences for displaying
characters with different
attributes or at any location on the screen.
UNIX was expanded to handle this with the development of the
termcap package which
describes any particular console within a certain set of
capabilities and how operations are performed
on that console.  All this information is represented in fixed rules in a
termcap data base for easy access.
.PP
By giving the user a software package which reads in any particular
terminal's information from the the termcap data base and performs any
requested function based on that terminal's capabilities, the user is now
relieved from knowing what hardware he/she is coding to.
The application only needs to know what functions are available
in the termcap toolbox in order to work on any terminal.
.PP
The cominbation of the termcap data base and line discipline filtering was
sufficient but does not support today's new complications of bitmap displays and
sophisticated keyboards/mice.
.NH
Todays Workstations
.PP
The first problem is that bitmap displays are not character oriented so you
can not send a character to the display and have it appear on the
screen.  Second, bitmap displays do not have capabilities that fit into
the normal termcap data base (e.g. there is no character sequence to tell the
display where to put a character).  Lastly the new keyboards and mice are
separated from the display and do not return ascii characters, but codes
which must be translated to determine what action has taken place
(up and down key transitions, etc.).
.PP
In order to integrate this
into the existing system, it was determined that an extension was needed
to the normal console/line discipline structure.
.PP
Before listing the requirements of the emulator package,
I will explain and compare what
a line discipline and an emulator are and what each is used for.
This will help in understanding why the
.ul
emulator package
was needed.
.NH
What is a Line Discipline?
.PP
A
.ul
line discipline
acts like a filter between the user
and communication hardware on the workstation.
A line discipline is a form of higher level software controller for
communication lines.  Essentially, a line discipline will buffer the user
from handling the data stream responsibilities from/to communication lines.
The following list summarizes the functions that the standard
terminal-oriented line disciplines handle:
.RS
.IP 1.
Input lines are collected and input editing is provided.
The edited line is made available when it is completed by a newline or
when an EOT (end of transmission)
is detected.  A line will be buffered up to 256 characters.
.IP 2.
Any input characters can be mapped to special functions for line editing or
interrupt generation.
.IP 3.
Input characters are buffered if the process can not read the data
faster than it is received.
.IP 4.
Output processing like delay generation, tab expansion,
erasing characters from the screen on input editing, echoing of control
characters and other unprintable characters in special formats, and other
functions such as mapping lower case characters to upper case for terminals
that only handle upper case.
.IP 5.
Flow control for output processing.  This consist of controlling the flow
between the process sending characters and the display.  The line
discipline will buffer data from the process to the terminal/display and
suspend the process if data is arriving faster then the display can show
it.
.IP 6.
A user can control the output flow by typing special control
characters to flush the output, and stop/start the output.
.IP 7.
Other line disciplines allow some or all input/output processing to be
excluded so that character by character input or raw data can be accepted.
.IP 8.
Other line disciplines know about certain protocols that may come in
on networked communication lines.
.RE
.PP
Line discipline filtering is very powerful
and important but does not completely satisfy the requirements of
today's input/output devices.  The major
deficiency is that we need to deal with more than character data
manipulation.
.NH
What is an Emulator?
.PP
Bitmap terminals are bit addressable and
do not deal with characters but with turning on/off and moving
bits on the screen.  To represent a single character on the screen a bitmap
terminal must have a number of bits at different locations turned on/off.
To scroll a bitmap screen you must move all the bits on the screen up a
line and turn off the bits on the bottom line with all this depending on
the size of the font used etc..  Some bitmap terminals will do some or all
of this in hardware for you.
It is then clear that each bitmap terminal must have
code written to control them for doing standard operations in
order to act like a normal
.ul
glass tty style console.
So the question is: What
software do you need to make a bitmap display take characters and command
strings like a glass tty?  Once this software is written it can be
intergrated with the existing line disciplines which handles character
manipulation for us.
.PP
Since we want to support multiple types of displays, the question also
comes up: What is the best way to design the code so that we can emulate a
glass tty on each display without reproducing the same code for each
display?  The emulator package gives you a solution.  It is a
intermediary between the low level device specific drivers and the higher
level line disciplines.  On output it differentiates
the set of Generic functional procedures that must be
device-dependent for controlling each display
and device-independent code which deciphers character streams and
decides when to perform an action on the display.
The device dependent set of procedures have to be sufficient
enough so that a piece of code, emulator, can be written with them and be
able to support normal glass tty operations.
.PP
Therefore, an emulator is the code that intercepts
characters and analyzes them according to the type of tty it emulates and
then calls the appropriate display/device dependent procedures to perform
the operation on the display.  With this separation, any emulator written
will work on any display on the workstation without having to know anything
about the display.  This type of emulator will be know as an
.ul
output emulator.
.PP
This notion can be expanded to input emulation as well.  This would enable
any keyboard or mouse on the system to pass data through an input
emulator filter and have the resulting filtered data be presented to the
user in any particular format.
Therefore, an 
.ul
input emulator
will be know as an emulator that accepts data from a keyboard and a mouse
and deciphers the data to present actual ascii characters (usually), and mouse
button/motion data reports.
.PP
Once an emulator is written it then can take output from or give input to
the normal line discipline routines as if the emulator was a normal UNIX
tty hardware driver.  It should be noted here that the emulator
package also supports window manager type device-dependent
routines.  This facilitates the implementation of
emulators which do not want to act like a
glass tty but rather be an interface to a window manager/graphics system
which takes control of output to the screen.
.NH
The Output Emulator Interface to the Low Level Display Dependent Routines
.PP
I have found that the following device dependent procedures are enough to
support any basic output emulator.
.RS
.IP 1.
Probe the display to see if it is there.
.IP 2.
Initialize the display.
.IP 3.
Position cursor anywhere on the display.
.IP 4.
Take a character and put up a bitmap, from some internal data font,
that represents that
character where your cursor is currently pointing.
.IP 5.
Blank a given section of the display (by character).
.IP 6.
Move a group of lines on the display.
.IP 7.
Print the screen contents on the standard printer.
.RE
.PP
Besides these base procedures, an emulator also needs general information
about the display it will be using like how many lines, and how wide a line
will fit on the screen with the font the display dependent routine is
using.  The following is the structure that describes the interface between
the emulator and the display-dependent routines.  The top part down to
.ul
flags
is the standard glass tty information; the other entries will be
described later when I explain how window manager systems integrate into the
emulator package.  The following is from "screen_conf.h".  This structure
is initialized in "screen_conf.c".
.sp 2
.nf
struct screen_sw {
	char    *name;			/* Name of Display */
	int     (*probe)();		/* Probe for Screen */
	int     (*init)();		/* Initialize Screen */
	int     (*s_putc)();		/* Put character on Screen */
	int	(*pos_cur)();		/* Position Cursor on Screen */
	int	(*blank)();		/* Blank A section of Screen */
	int	(*move)();		/* Move Some lines on Screen */
	int     (*printscreen)();	/* routine to print screen */
	char	*rwaddr;		/* Read & writable addr on screen */
	short	lines;			/* Number of lines on screen */
	short	width;			/* Width of screen in characters */
	short	vbits;			/* Vertical number of screen bits */
	short	hbits;			/* Horizontal number of screen bits */
	int	flags;			/* some flags about the screen */
	int	def_oute;		/* Default output emulator */
	int	(*pos_loc)();		/* Position Locator on Screen */
	int	(*load_loc)();		/* Load Locator description */
	int	(*show_loc)();		/* Show Locator on Screen*/
	int	(*hide_loc)();		/* Hide Locator on Screen */
	int	(*apa_init)();		/* All Points Addressable screen init */
	int	fill_int[14];		/* Fill out to 32 ints (2^7) */
};
.sp 2
.fi
.RE
.PP
The following is a synopsis from "screen_conf.h" which shows the interface to
the above structure.  All that the emulator needs to use are the following
routines and attributes.
.sp 2
.nf
/* General Defines for emulators to use with the screen_sw structure */
#define WS		si->which_screen
#define SCREEN_LENGTH	(screen_sw[WS].lines)
#define SCREEN_WIDTH	(screen_sw[WS].width)
#define SCREEN_SIZE	(SCREEN_LENGTH * SCREEN_WIDTH)
#define STATUS_LINE	(SCREEN_LENGTH - 1)

/* Character Attributes */
#define NORMAL_VIDEO	0x01
#define REVERSE_VIDEO	0x02
#define UNDERLINE_VIDEO	0x04
#define HI_INTENSITY	0x08
#define BLINK		0x10

/* Defines for calling console screen dependent switched routines */

/* Put character 'c' with attribute 'screen_attr' on console */
#define screen_putc(c, screen_attr) (*screen_sw[WS].s_putc) (c, screen_attr)

/* Move cursor to x,y position */
#define pos_cursor(x, y) (*screen_sw[WS].pos_cur) (x, y)

/* blank with screen_attribute from start coordinates to end coordinates */
#define screen_blank(s_a, sy, sx, ey, ex) (*screen_sw[WS].blank) (s_a, sy, sx, ey, ex)

/* Macro for blanking a line */
#define blank_line(s_a, line) screen_blank(s_a, line, 0, line, SCREEN_WIDTH-1)

/* move line1 ... line2 to dest */
#define screen_move(l1, l2, dest) (*screen_sw[WS].move) (l1, l2, dest)

/* Position screen locator on screen at x,y position with msbox restriction */
#define pos_locator(x, y, msbox) (*screen_sw[WS].pos_loc) (x, y, msbox)

/* Load a new screen locator discription with msbox restriction */
#define load_locator(c, msbox) (*screen_sw[WS].load_loc) (c, msbox)

/* Show screen locator with msbox restriction */
#define show_locator(msbox) (*screen_sw[WS].show_loc) (msbox)

/* Hide screen locator */
#define hide_locator() (*screen_sw[WS].hide_loc) ()

/* APA Screen init */
#define apa_initialize() (*screen_sw[WS].apa_init) ()
.sp 2
.fi
.RE
.NH
Input Emulator Interface to Input Device Dependent Routines
.PP
The input emulator low level interface is not as strictly defined as the 
output emulator interface.  Essentially there are a set of hardware routines
in
.ul
keyboard.c
and
.ul
mouse.c
which an input emulator can call to control the keyboard, speaker, and
mouse.
The interface to input emulators is much
less rigid than an output emulator (this should change in the future).
Basically the input emulator
will receive an interrupt with data from the keyboard or mouse along with
an indication of which sent the interrupt.
The emulator is then responsible for deciphering the data and keeping track
of the state of the device.  The input emulator will then pass on its
processed data to the user through a
.ul
line discipline
or through some other emulator specific method (shared memory, etc.).
.PP
There are only a few procedures needed to control a keyboard for setting
things like the auto keyclick rate, bell tone, and key characteristics
(repeat rate, make/break, etc.).  And because any workstation I have run
into so far only supports one keyboard at a time,
there is no reason to set up a
switch table for these hardware routines, yet!
Workstation mice also have few control operations (set sampling or
resolution rate) and input emulators, as yet, do not deal with these directly
but instead pass on
.ul
ioctl
system calls to the appropriate driver for these operations.
.NH
Window Manager Device Dependent Routines
.PP
The following lists the window manager type Device Dependent Routines which
are available with the
.ul
screen_sw
low level routines.  These are normaly used in an input emulator in order to
control the mouse tracking to the display cursor/locator.
.RS
.IP pos_loc()
Position the locator at a given coordinate on the display.
.IP load_loc()
Load a locator bitmap for the display.  This will be the locator until the
next load_loc.
.IP show_loc()
Make the locator visible and keep showing when positioned.
Usually used after a hide_loc.
.IP hide_loc()
Make the locator invisible but does not effect the tracking.
.IP apa_init()
All Points Addressable Init the display for graphic type operations needed
for using the locator on the display.  Usefull for displays with hardware
cursors/locators.
.RE
.NH
System Interface to the Emulator
.PP
Given the above any emulator can be written, but more is needed than
supplying the routines and interface for an emulator to use.
You must be able to add a new emulator to the system easily and have
support for allowing that new emulator to coexist with other emulators.
An emulator is much like a tty hardware device driver with many similar
system entry points and functions.  The main difference is that they
all funnel through one console driver and all call a
common set of hardware routines.  They never deal with the hardware
directly as device drivers do.
To put an emulator into the system you must add the following routines and
place them into the following switch table structure
(modeled after line disciplines).  This structure is declared in
.ul
screen_conf.h
and the table is initialized in
.ul
screen_conf.c.
.sp 2
.nf
/*
 * Emulator line control switch.
 */
struct emulsw
{
	int     (*e_open)();
	int     (*e_close)();
	int     (*e_read)();
	int     (*e_write)();
	int     (*e_ioctl)();
	int     (*e_rint)();
	int     (*e_putc)();
	int     (*e_select)();
	int     (*e_putstatus)();	/* to put up status information */
	int	fill[7];
};
.sp 2
.fi
.PP
This emulator switch table
list all routines necessary for a device driver to interface with an
emulator.
Therefore each emulator, depending on its needs, will have the following
entry points in the kernel.
.RS
.IP E_OPEN
.br
Open the emulator to do any initialization necessary.  Perform initial
operations like clearing the screen, initialize the cursor, and position
the cursor on the screen.
.IP E_CLOSE
.br
Close the emulator; do any cleanup necessary.
.IP E_READ
.br
Read data from the emulator.  This routine usually forwards the read
request to the user defined line discipline.  The read routines in line
disciplines currently perform all the operations necessary for this routine.
This consist of taking the already received characters off a
.ul
clist queue
and passing them to the user program's read buffer.
.IP E_WRITE
.br
Write data to the emulator.  This procedure takes a character stream
passed from the
user level program.  The emulator usually calls the line discipline which
the user has specified to do any character preprocessing.
Again, the line discipline routines already perform the necessary duties
for this routine.  This routine and the E_READ routines are in the emulator
package for completeness and allowing for future flexibility.
You will find that some specialized emulators do use these routines for other
than calling the associated line discipline routines (see buf_emul).
.IP E_IOCTL
.br
I/O control to emulator for changing or setting any characteristics of the
emulator or performing operations which do not fit into the normal
interface to the emulator.  An emulator's IOCTL routine should return a (-1)
if the command is not recognized.
.IP E_RINT
.br
Receive interrupt to emulator.  This procedure is only needed by input
emulators. The emulator receives an interrupt from
a driver's interrupt routine
and processes the data depending on the type of
interrupt received.
This procedure will then pass on the processed input data 
to the user assigned line discipline input routine.
Some specialized window manager emulators will not forward this data to a
line discipline but do their own queuing and interaction with the window
manager.
.IP E_PUTC
.br
Put a character on the display.  This emulator routine is passed a
character from a user's write or kernel print.  The emulator is then
responsible to decipher the data passed and do any emulation before passing
the appropriate characters to the hardware putc routine.
This is the procedure which makes use of the screen switch table (screen_sw)
to call the device dependent routines to perform the emulation on any
display.
.IP E_SELECT
.br
Select call to emulator.  This routine is used in input emulators to
perform the normal select duty of informing the user process
when new data is ready.
.IP E_PUTSTATUS
.br
Put status call to emulator.  The emulator is responsible to take the 
string passed and place it at an offset on the status line.
.RE
.NH
What the Emulator Package gives you
.RS
.IP 1.
Probe and initialize every display that is present on the workstation.
.IP 2.
Decide which display should be the default on bootup.
.IP 3.
A way for the user to reinitialize any hardware or emulator.
.IP 4.
A default emulator is defined for any particular hardware so that at
start up an application does not have to choose an emulator.
.IP 5.
A mechanism to select between the set of existing emulators for a display.
.IP 6.
Multiple displays running on the system simultaneously.
Each display can be associated with a different process.  This allows
a separate login to run on each display.
.IP 7.
Emulators are written to support more than one display at a time,
multithreaded.
.IP 8.
A way to switch between the displays currently open on the workstation.
When you switch screens the focus of the keyboard and mouse follows to that
display.  With this you can run a different window system on each display
and hot-key between them.
.IP 9.
A way to find out and change what the hot-key is.
.IP 10.
A way to lock out the user or system from using the display.
User lockout
is useful for window managers that wish to lock out other applications
from taking over the screen after they have.
Kernel or system lockout is useful when you don't want the kernel to
attempt to use a display for output because the controller has no display
hanging off it.
.RE
.NH
How does the console driver fit all this together?
.PP
The following diagram shows the relation of all the parts of the system I
have described with the standard
parts of a UNIX system.
.sp 1
.TS
center box;
cb s s
c s | cb
c | c | cb
.
Console System Diagram
=
User Application	User Level
\_	\_	\^
System Call Interface	Event Queue in	\^
\^	Shared Memory	\_
\^	\^	Kernel Level
\_	\_	\^
Line Discipline Package	Emulator Package	\^
\_	\_	\^
Standard Device Drivers	Low Level Display	\^
\^	Dependent Routines	\^
\_	\_	\_
Displays/Keyboard/Speaker	System or Serial Mouse	Hardware
.TE
.PP
The above is a conceptual view of the system and does not show you all
the specific parts and what interfaces with what, but it does
give you an idea of the levels of flow. 
The console driver is now a controller/router of sorts.
It takes the normal driver
requests and routes them to the correct display and display's
input/output emulator depending on the minor device specified.
The following shows how the minor device number maps to an emulator and display:
.sp 1
.TS
center allbox;
cb s
c c
.
Minor Device Number
_
Emulator FLAG	Display number
High Nibble	Low Nibble
0 or 1	0 ... 15
.TE
.PP
The following is a list of currently used displays on our system.
.sp 1
.TS
center allbox;
cb s s
n l l
.
Console Displays
_
Display #	Symbolic Name	Description
0	CONS_GEN	Generic console (Current display)
1	CONS_AED	ACIS Experimental Display (Stream ordered)
2	CONS_MONO	Standard Monocrome (Character driven)
3	CONS_APA8	All Points Addr with 8 bit bus (Bitmap)
4	CONS_APA16	All Points Addr with 16 bit bus (Bitmap)
5	CONS_APA8C	All Points Addr color with 8 bit bus (Bitmap)
.TE
.PP
The emulator field in the minor device number is used to tell the console
driver to use the default glass tty input/output emulators for the display (0)
or to indicate that a nonstandard combination of input/output emulators will
be used by the user (1).  This is needed so that the system will know to
restore the display to the
.ul
standard state (default emulators)
wen the program exits.
The following is a list off all current emulators available:
.sp 1
.TS
center allbox;
cb s s
n l l
.
Emulators available
_
Emulator #	Symbolic Name	Description
0	E_STDINPUT	Standard Input Emulator
1	E_STDOUTPUT	Standard Output Emulator
2	E_IBMOUTPUT	IBM 3101 Output Emulator
3	E_ANSIOUTPUT	ANSI Output Emulator (Not implemented)
4	E_XINPUT	X Event Queuing Input Emulator
5	E_BUFOUTPUT	Buffering Output Emulator
6	E_MACINPUT	Macintosh Event Queuing Input Emulator (Not Avail)
7	E_MACOUTPUT	Macintosh Output Emulator (Not Avail)
8	E_KBDINPUT	Intelligent Keyboard mapping Input Emulator
9	E_AED	Raw AED microcode interface Emulator
.TE
.sp 1
.PP
The
.ul
default emulators
for each display are:
.sp 1
.TS
center allbox;
cb s s
l | l l
.
Default Input/Output Emulators for each display
Display	Input Emulator	Output Emulator
AED	E_STDINPUT	E_STDOUTPUT
MONO	E_STDINPUT	E_IBMOUTPUT
APA8	E_STDINPUT	E_IBMOUTPUT
APA16	E_STDINPUT	E_IBMOUTPUT
APA8C	E_STDINPUT	E_IBMOUTPUT
.TE
.NH 2
Input From Keyboard Scenario
.RS
.IP 1.
User types character on keyboard.
.IP 2.
Receive Interrupt in keyboard driver, keyboar.c, interrupt routine 
.ul
cnrint().
This routine extracts the key code from the hardware.
.IP 3.
Call emulator receive interrupt routine from the switch table indexed by
the current
.ul
input focus
after setting the 
emulator structure flag indicating that this was a keyboard interrupt.
.IP 4.
Emulator will check if this was a keyboard interrupt.
If so it will either translate code into a character
and call normal line discipline routine for this console with the character
that it mapped the code to or
perform some emulator specific function like store the raw key
code in a shared memory area (X like)
and set a semaphore, also in shared memory, for
the user process to know that a new event has arrived.
.IP 5.
If a line discipline input routine is called, it will then perform any of
its normal input editing/mapping talked about previously and pass the
result to the user through the read system call interface.
.IP 6.
If a shared memory queue interface was used the user process would note
the queue update through the semaphore and then proceed to read the data
from the shared memory without preforming a read or any other system call.
.IP 7.
In either of the above two cases, if the user has previously done a select
call, he/she would then have the select satisfied.
.RE
.NH 2
Output To Display Scenario
.PP
This
.ul
scenario
only applys to glass tty operations and not window managers since window
manager system go directly to the display hardware through its own
graphics routines.  A special
.ul
buffer emulator
has been set up to handle the case it someone trys to write through the
system to the display while a window manger is controlling the display.
This emulator would then be called, instead of a glass tty like emulator,
in the scenario listed below.
.RS
.IP 1.
The user performs a
.ul
write system call
with a buffer of data for the display.  This data consists of straight
ascii data or display order streams.
.IP 2.
The console write routine will then call the minor device switched
output emulator's write routine.
.IP 3.
The output emulator write will usually then forward this data to the line
discipline write routine specified by the user.  Certain emulators, like the
.ul
buf emulator
mentioned, will intercept this data and capture it for printing latter or
any other specific need.
.IP 4.
The line discipline will interpret the data and call the console start
routine, as normal, to print the ascii characters.
.IP 5.
The console driver's start routine loops through
dequeuing each character and calling
the output emulator put-character routine,
.ul
e_putc,
for each character.
.IP 6.
The output emulator
.ul
put-character routine
then deciphers the data and
calls the appropriate device-dependent routine to display the
character or perform the display command.
.RE
.NH
The User interface to the Emulators
.PP
As with standard UNIX the user interfaces to the system through system
calls to the console driver.  The following explains how this interface has
changed to support the emulator package and multiple devices.
For more details on the
.ul
console and mouse drivers
you should see
.ul
cons(4) and  ms(4).
.NH 2
Interface to Keyboard Input and Display Output
.NH 3
Standard Interface
.PP
In the simplest case a user program would still perform the same
operations as in the past, therefore allowing previously written programs to
work without change.  The following lists the normal scenario and what the
emulator package does:
.RS
.IP 1.
An application, say login, opens "/dev/console".
Since "/dev/console" is the special CONS_GEN minor device, the open is
mapped to the current input focused display.  The effect is that the
display at which you start a program is the display that is associated with
the process.  The system will then start the default input and output
emulators for that display.
.IP 2.
The application reads or writes to the file descriptor returned
from the open system call.
The system will map reads or writes to the GEN_CONSOLE minor device
to the display with the current input focus which causes the appropriate
display indexed input/output emulators to be used.
.IP 3.
The application exits or closes "/dev/console" file descriptor.  The system
will close the input/output emulators and the stream for the display with
the current input focus.
.RE
.PP
This mapping of "/dev/console" to the current display is important for
most applications which do not want to bother with which display they are
running on.  This mapping is also very important
at system bootup time where the single user
shell does not know what display it
is starting on and it is simply mapped to the what the system choose as the
starting input focus. 
But you want to tell some applications (e.g. login, widow manager.) which 
.ul
display
they should start on.
Therefore, the following devices where made to support the displays
available on our system.
.TS
center allbox;
cb s s s s
c c c c c
l l c c l
.
Standard TTY Like Display Devices
_
Protections	Owner	Major	Minor	Device
crw-rw-rw-	root	0,	0	/dev/console
crw-rw-rw-	root	0,	1	/dev/ttyaed
crw-rw-rw-	root	0,	2	/dev/ttymono
crw-rw-rw-	root	0,	3	/dev/ttyapa8
crw-rw-rw-	root	0,	4	/dev/ttyapa16
crw-rw-rw-	root	0,	5	/dev/ttyapa8c
.TE
.PP
To start up an application on a particular display, all that is needed is
to reassign its standard input and outputs to any one of these devices or
have the application specifically open one of them.  The system will then
handle the routing of output from that application to the appropriate
display and its default emulators.  Input to the application from the
keyboard will only occur when the input focus is assigned to that display.
To switch between open displays you can hit the specified hot-key for your
system or use an application which performs an
.ul
ioctl system call
to set the input focus.
.PP
Putting this all together with the startup facilities in UNIX you
can now specify the different displays you have on your system in the
.ul
/etc/ttys
startup file and tell the system to start logins on each one of the
displays.  A user can then hot-key to the display he/she wishes to use and
after logging in run any applications needed.  Any application started on that
display will stay associated with it because it was started while the input
focus was on that display.  Remember that this is an
application transparent mapping to that display taking place in the
kernel.  Therefore a user can log on as many of the displays simultaneously
as needed.
.NH 3
Nonstandard Interface
.PP
For applications which call for a specific emulator that might not be the
default for a particular display, the following devices have been created.
.sp 1
.TS
center allbox;
cb s s s s
c c c c c
l l c c l
.
Nonstandard Display Devices
_
Protections	Owner	Major	Minor	Device
crw-rw-rw-	root	0,	17	/dev/aed
crw-rw-rw-	root	0,	18	/dev/mono
crw-rw-rw-	root	0,	19	/dev/apa8
crw-rw-rw-	root	0,	20	/dev/apa16
crw-rw-rw-	root	0,	21	/dev/apa8c
.TE
.PP
You will notice that the emulator bit flag is on for each of these
devices.  This indicates to the system that a nonstandard input and/or
output emulator is going to be used on this display and that on close the
system should return the display to its default emulators.
The system will open the standard input emulator and a special
buffering output emulator.  This is done because most applications that
open the nonstandard device will take over the screen and want any output
from other sources (such as kernel prints) to be buffered and displayed
when the display is closed.  See the manual page on the
.ul
buf emulator
for more information.
.PP
The following is a list of commands through the
.ul
ioctl system call
to the console emulator package:
.TS
center allbox;
cb s s s
c c c c
l l l ltw(3i)
.
Ioctl Commands to Emulator Package
_
Command	Read	Write	Description
CON_SELECT_SCREEN	Yes	Yes	T{
Input focus is set to display Number (Arg > 0) or to next display in list
(Arg < 0).  Previous display number is returned.
T}
CON_GET_SCREEN	Yes	No	T{
Just returns the current input focus display number.
T}
EIGETD	Yes	No	T{
Get the number of the current input emulator for this display.
T}
EOGETD	Yes	No	T{
Get the number of the current output emulator for this display.
T}
EISETD	Yes	Yes	T{
Set the input emulator and return the previous for this display.
T}
EOSETD	Yes	Yes	T{
Set the output emulator and return the previous for this display.
T}
CON_INIT_SCREEN	No	Yes	T{
Initialize the specified display (Arg >= 0) or
this display (Arg < 0).
T}
CON_GET_FOCUS_CODE	Yes	No	T{
Get the current keyboard code for setting the input focus (hot-key code).
T}
CON_SET_FOCUS_CODE	Yes	Yes	T{
Set the current keyboard code for setting the input focus (hot-key code),
and return the previous code.
T}
SCRIOCGETF	Yes	Yes	T{
Get screen control flags for the given display number.
T}
SCRIOCSETC	Yes	Yes	T{
Set screen control flags for the given display number.
T}
.TE
.PP
All of the above commands take integer arguments except the last two
(SCRIOCGETF and SCRIOCSETC) which use the following structure:
.sp 2
.nf
struct screen_control   {
	int	device;		/* which screen/display to control */
	int	switches;	/* Flags for this screen */
};
.fi
.sp 1
.TS
center allbox;
cb s 
c c
l l
.
Flags/Switches for Each Display
Flag	Description
CONSDEV_PRESENT	Display is present on this system.
CONSDEV_KERNEL	Display is available to the kernel.
CONSDEV_USER	Display is available to the user.
CONSDEV_INIT	Display has been initialized for output.
CONSDEV_OPEN	Display has been open directly by minor device number.
.TE
.PP
All of the above
.ul
ioctl system calls
are
.ul
device independent controls
for dealing with the emulators.  Each emulator has its own set of ioctls
for its own emulation purposes.  These other
.ul
ioctls
are used in window manager type emulators for operations such as
passing/positioning the mouse locator for/on the display.
See the man page for any particular emulator for more information.
.NH 2
Mouse Input Interface and Other Input Devices
.PP
The interface to the system mouse is similar to that for the keyboard.
If you open the generic mouse device
.ul
/dev/ms,
minor device 0, the mouse input will be attached to the display which the
current input focus is on.  Opening any other mouse device will attach the
mouse input stream to the process only when the input focus is on the
associated display.  Since there can be a large assortment of serial type
hardware ports in which you can hang a mouse off of I have decided, for the
present, not to change all the associated drivers to support the console
like minor devices and input focus forwarding.  Therefore a Mouse off a
async port will always report its data to the process no matter what
display it was started on.  If more that one process opens an async mouse
they will compete for data from the mouse.
.sp 1
.TS
center allbox;
cb s s s s
c c c c c
l l c c l
.
Mouse Input Devices
_
Protections	Owner	Major	Minor	Device
crw-rw-rw-	root	15,	0	/dev/ms
crw-rw-rw-	root	15,	1	/dev/msaed
crw-rw-rw-	root	15,	2	/dev/msmono
crw-rw-rw-	root	15,	3	/dev/msapa8
crw-rw-rw-	root	15,	4	/dev/msapa16
crw-rw-rw-	root	15,	5	/dev/msapa8c
.TE
.PP
The
.ul
system mouse
and
.ul
serial port mice
drivers are essentially the same as you find in normal UNIX.  These drivers
hook into the emulator package through a user selecting a
special line discipline.  This line discipline
filters the mouse data and then passes a generic
data packet to the user through normal read system calls
or calls the user specified emulator with the data packet.
This line discipline is explained in the manual page for
.ul
tty_tb(4).
.NH
The Emulator Package RoadMap
.PP
The following tables briefly explains the files that make up the emulator
package.  The tables are split up the different parts that
make up the emulator package according to functionality
Each table state what that functionality is and where the files can be
found as well as a description of what can be found in that file.
Tables with a column marked
.ul
User
distinguishes between purely kernel files
and user/kernel shared include files.  This indicates what files a user
should include to get at the basic emulator functions and any particular
emulator now available.
.bp
.TS
expand allbox;
cb s s
cb s s
c c c
l c ltw(4i)
.
Emulator Control Files
_
"/sys/machinecons"
File	User	Description
cons.c	no	T{
Console Driver, routes requests to appropriate emulator and its Input/Output
device or to the emulator controller.
Console driver is also responsible for console message forwarding.
T}
consdefs.h	no	T{
This file contains hardware interface information about system input
devices.  Emulators as well as device dependent routines use this to
interface with each other and the hardware.
T}
consio.h	yes	T{
Defines for what displays and screen controls/flags are available.  The
IOCTL commands and structure for screen_control are in here.  This file is
indirectly included by screen_conf.h.
T}
consvars.h	no	T{
Emulator control variables are declared here.
T}
bus.c	no	T{
I/O Bus control driver, which allows access to the I/O bus on a per process
basis.  Window managers which need to get directly at the display from user
space should open "/dev/bus".
T}
screen_conf.c	no	T{
Where all the displays and emulators are configured for the system.  This
file also contains the emulator control routines discussed in "What the
Emulator Package gives you".
T}
screen_conf.h	yes	T{
Where all the structures, defines, and macros for the emulator package
live.  This contains all the macros for an emulator to interface with the
Device Dependent routines as well as the IOCTL information for the user to
interface with the Emulator Package.
T}
.TE
.TS
expand box;
cb s s
cb s s
c | c | c
l | c | ltw(4i)
.
Emulators
=
"/sys/machinecons"
_
File	User	Description
aed.c	no	T{
AED raw microcode graphic emulator.
T}
aeddefs.h	\^	\^
_
buf_emul.c	no	T{
Buffering emulator, which saves messages sent to display and then flushes
them when the output emulator is changed.
T}
_
ibm_emul.c	no	T{
IBM3101 output emulator.  Takes a considerable subset of IBM3101 commands
defined in tcap.
T}
mono_tcap.h	\^	\^
_
kbd_emul.c	no	T{
A smarter keyboard emulator which allows mapping of key codes to a character
stream.
T}
kbd_emul.h	\^	\^
kbde_codes.h	\^	\^
_
std_emul.c	no	T{
Standard input and output emulator routines.  A straight key code to
character mapping is done on input and the raw characters are sent to the
display on output.  This output emulator is used for displays which perform
their own emulations.
T}
std_emul.h	\^	\^
_
x_emul.c	no	T{
X window system input emulator.  This queues up keyboard and mouse events
into a shared memory area between kernel and user.  This emulator also has
a variety of IOCTLs for controlling the locator on a display, as well as
performing other X related functions (e.g. tracking the cursor, etc.).
T}
xio.h	yes	T{
X dependent structures and defines for kernel and usr process.
T}
_
qevent.h	yes	T{
Event Queue structures and defines used by only the X emulator currently.
T}
.TE
.bp
.TS
expand allbox;
cb s s
cb s s
c c c
l c ltw(4i)
.
New/Changed Line Discipline files
=
"/sys/sys" and "/sys/h"
_
File	User	Description
tty_conf.c	no	T{
Line discipline configure file.
T}
tty.h	yes	T{
Line discipline structures and defines.
T}
=
tty_tb.c	no	T{
Normal tablet line discipline changed to support system/serial type mice also.
Also changed for forwarding data packets to input emulator if specified.
T}
tbdefs.h	no	T{
Tablet/Mouse generic data packet structures and defines.
T}
tbioctl.h	yes	T{
IOCTL commands and structures.
T}
.TE
.TS
expand allbox;
cb s
cb s
c c
l ltw(4i)
.
Low Level Output Display Dependent Files
_
"/sys/machinecons"
File	Description
aed_tty.h	T{
Macros and defines for interfacing with the Glass TTY microcode for the
AED display.
T}
aed_tty_mcode.h	T{
Glass TTY microcode for download to the AED display.
T}
aedloc.c	T{
AED locator low level device dependent routines.
T}
aedtty.c	T{
AED Glass TTY low level device dependent routines.
T}
apa16loc.c	T{
APA16 locator low level device dependent routines.
T}
apa16tty.c	T{
APA16 Glass TTY low level device dependent routines.
T}
apa16tty.h	T{
APA16 device dependent structures and define.
T}
apa16tty_font.h	T{
APA16 Font for Glass TTY emulation.
T}
apa8cloc.c	T{
APA8 Color locator low level device dependent routines.
T}
apa8ctty.c	T{
APA8 Color Glass TTY low level device dependent routines.
T}
apa8ctty.h	T{
APA8 Color device dependent structures and define.
T}
apa8loc.c	T{
APA8 locator low level device dependent routines.
T}
apa8tty.c	T{
APA8 Glass TTY low level device dependent routines.
T}
apa8tty.h	T{
APA8 device dependent structures and define.
T}
apa8tty_font.h	T{
APA8 and APA8 Color Font for Glass TTY emulation.
T}
apa_fontblt.c	T{
Generic routines for font manipulation on APA displays.
T}
apa_structs.h	T{
Generic structures and defines for font manipulation on APA displays.
T}
apaaed.h	T{
Structures and defines for dealing with the AED as an APA display.
T}
mono.c	T{
Monocrome Glass TTY low level device dependent routines.
T}
monocons.h	T{
Monocrome device dependent structures.
T}
monodefs.h	T{
Monocrome device dependent defines.
T}
.TE
.bp
.TS
expand allbox;
cb s
cb s
c c
l ltw(4i)
.
Low Level Keyboard Device Dependent Routines
_
"/sys/machinecons"
File	Description
keyboard.c	System Keyboard hardware routines.
keyboard.h	System Keyboard hardware structures and defines.
.TE
.sp 1
.TS
expand allbox;
cb s s
cb s s
c c c
l c ltw(4i)
.
System and Serial Mouse Device Drivers
_
"/sys/machineio"
File	User	Description
asy.c	no	T{
Serial asynchronous driver, supports 4 port board and
Parallel/Serial board.
T}
asyregs.h	no	T{
Serial hardware structures and defines.
T}
mouse.c	no	T{
Driver for system mouse.
T}
mouseio.h	yes	T{
System Mouse structures and defines.  Also includes IOCTL controls/defines
for user processes.
T}
mousereg.h	no	T{
System mouse driver declarations.
T}
psp.c	no	T{
System (Planar) Serial Port driver.
T}
pspreg.h	no	T{
Planar Serial Port hardware structures and defines.
T}
.TE
