.\"
.\" P_R_P_Q_# (C) COPYRIGHT IBM CORPORATION 1986, 1987
.\" LICENSED MATERIALS - PROPERTY OF IBM
.\" REFER TO COPYRIGHT INSTRUCTIONS FORM NUMBER G120-2083
.\"
.\"$Header: consemul,v 10.4 87/07/02 09:52:20 adams Exp $
.\"$Source: /ibm/acis/usr/doc/ibmdoc/smm/05.consemul/RCS/consemul,v $
.\"
.\"This file uses tbl and -me macros.
.nr si 3n
.eh '4.3/RT-SMM:5-%''4.3/RT Console Emulators'
.oh '4.3/RT Console Emulators''4.3/RT-SMM:5-%'
.fo '''July 1987'
.in 0
.bp
.(l C 
.sz 14
4.3/RT Console Emulators
.sz
.sp 2
.)l
.(x
4.3/RT Console Emulators
.)x
.(l F
.ce
ABSTRACT
.sp
This paper explains the need for, and design of, console emulators in
4.3/RT.
It contains the following sections:
.)l
.ip \fB1.\fP
.b
Overview
.r
describes the need for console emulators.
.ip \fB2.\fP
.b
Emulator Package Functions
.r
describes the functions provided.
.ip \fB3.\fP
.b
Output Emulator Interface
.r
describes the interface between the emulator and 
the display-dependent routines.
.ip \fB4.\fP
.b
Input Emulator Interface
.r
describes the interface between the devices and the input emulator.
.ip \fB5.\fP
.b
Window Manager Device-dependent Routines
.r
describes the low-level routines available for controlling a graphics cursor.
.ip \fB6.\fP
.b
System Interface to the Emulator
.r
lists all the routines necessary for a device driver to interface with
an emulator.
.ip \fB7.\fP
.b
Console Driver's Relationship to 4.3/RT
.r
shows the levels of flow between the console driver and the standard 4.3/RT
system.
.ip \fB8.\fP
.b
User Interface to the Emulator
.r
describes the systems calls to the console driver and the mouse.
.ip \fB9.\fP
.b
Files Included with the Emulator
.r
defines the files contains in the emulator package.
.)l
.bp
.sh 1 OVERVIEW
.lp
This emulator package was developed under 4.3/RT to support
the complex data streams characteristic of advanced workstations.
Traditional line disciplines and console driver interfaces are not
powerful enough to manage elaborate bit-mapped displays.
Sophisticated keyboards, mouse devices, and multiple consoles 
add complexity to console management.
.lp
Emulators written using the 4.3/RT emulator package can handle
normal line-discipline I/O functions as though they were 
normal \fItty\fP hardware drivers.
The emulator package also supports window-manager 
device-dependent routines, allowing an emulator to act as an interface to a
window-manager/graphics system and to control screen output.
.sh 2 "Bit-Map Terminal Requirements"
.lp
Bit-map terminals are bit-addressable; they deal not with characters,
but with individual bits.
To represent a single character on the screen, 
a bit-map terminal turns bits at 
different locations on or off.  In scrolling,
all bits on a bit-map screen move up a line at a time, while 
bits on the bottom line turn off.
Some bit-map terminals handle some or all of this in hardware.
However, to act as a normal \fIglass tty\fP console, 
each terminal must also be able to perform standard I/O operations.
Supporting multiple display types requires code to emulate
a glass tty on each display without reproducing the same code for each.
.lp
An emulator package solves the inability of bit-map displays to
deal directly with characters.  It provides a standard interface needed 
by
the low-level, device-dependent
drivers
and called by the higher-level line disciplines.
The device-dependent drivers contain functional procedures that determine
where a character appears on the screen, while the device-independent
line disciplines determine what the character looks like.  When requested to
display information on the screen, an emulator package works between the
two to ensure that the correct character appears at the correct
location.
.sh 2 "Output Emulators"
.lp
Emulator code intercepts characters and analyzes them according 
to the type of tty emulated, then calls the appropriate 
routines to operate on the display.
Using this design, any emulator works on any display on the workstation
without knowing anything about the display.
This type of emulator is an \fIoutput emulator\fP.
.sh 2 "Input Emulators"
.lp
The same design approach applies to input emulation.
Any keyboard or mouse on the system must be able to pass data
to the user in a given format.
An \fIinput emulator\fP accepts and deciphers data appropriately.
.sh 1 "EMULATOR PACKAGE FUNCTIONS"
.lp
The emulator package performs the following functions:
.ba +5
.ip \(bu
Initializes each display present on the workstation.
.ip \(bu
Provides a default emulator, defined for any particular hardware.
An application does not have to choose an emulator at
start-up.
.ip \(bu
Allows multiple displays to run on the system simultaneously.
Each display can be associated with a different process.
This allows a separate login to run on each display.
.ba -5
.bp
.lp
The emulator package also allows the user to:
.ba +5
.ip \(bu
Decide which display should be the default on system boot.
.ip \(bu
Reinitialize any hardware or emulator.
.ip \(bu
Select from a set of existing emulators for a display.
.ip \(bu
Switch between the displays currently open on the workstation.
When you switch screens, the focus of the keyboard and
mouse moves to that display.
This allows you to run a different window system on each
display and press a hot-key to switch between them.
.ip \(bu
Find and change the hot-key.
.ip \(bu
Lock out the user or the system from a display.
User lockout is useful for window managers that want to
keep other applications from taking over the screen.
Kernel or system lockout is useful when you don't want the
kernel to attempt to use a non-existent display;
for example, when an adapter has no display attached to it.
.ba -5
.sh 1 "OUTPUT EMULATOR INTERFACE
.lp
An emulator needs general information
about the display it uses, such as the number and
width of lines that fit
on the screen in the current font.
.lp
The following device-dependent procedures
support any basic output emulator:
.np
Determine whether the display is present.
.np
Initialize the display.
.np
Position the cursor anywhere on the display.
.np
Display a character at the cursor position by putting
up a bitmap from an internal data font.
.np
Blank a given section of the display (by character).
.np
Move a group of lines on the display.
.np
Print screen contents on the standard printer.
.lp
The following structure from
<\fImachinecons/screen_conf.h\fP>
describes the interface between
the emulator and the display-dependent routines.  From the top
down to
\fIflags\fP is the standard glass tty information; other entries are
described later.
This structure
is initialized in \fI/sys/machinecons/screen_conf.c\fP.
.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	(*color_table)();		/* Change color table */
	int	(color_entries;		/* Number entries in color table */
	int	(*put_status)();		/* Put status (smart devs only) */
	char	*addr;			/* Screen base address */
};
.fi
.lp
The synopsis below from \fIscreen_conf.h\fP
shows the interface to
the above structure.  The emulator need only use the following
routines and attributes:
.sp
.nf
/* Character Attributes */
#define NORMAL_VIDEO	0x00
#define BLINK			0x01
#define REVERSE_VIDEO	0x02
#define UNDERLINE_VIDEO	0x04
#define HI_INTENSITY	0x08
#define LITERAL_VIDEO	0xff

/* color table values */
#define FOREGROUND_COLOR	0x01
#define BACKGROUND_COLOR	0x00
#define SCREEN_RED		0x04

/* Color Set Flags */
#define COLOR_SET	0x00	/* set the color table entry to color */
#define COLOR_INC	0x01	/* increment the color table entry */
#define COLOR_DEC	0x02	/* decrement the color table entry */

/* Monochrome displays are only interested in the high bit of a color */
#define SCREEN_HIGH_BIT	0x80000000

/* Tell the emulator the printf is from the kernel */
#define SCREEN_KERNEL	0x2

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

#define screen_putc(c, screen_attr, fg, bg) (*screen_sw[WS].s_putc) (c, screen_attr, fg, bg)
	
/* Put the status out (smart devices only, i.e. aed) */
#define screen_put_status(pos,str) (*screen_sw[WS].put_status)(pos,str)

/* color table select */
#define screen_color_table(entry,red,green,blue,flags) (*screen_sw[WS].color_table)(entry,red,green,blue,flags)
	
/*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, fg, bg) (*screen_sw[WS].blank) (s_a, sy, sx, ey, ex, fg, bg)
		
/* Macro for blanking a line */
#define blank_line(s_a, line, fg, bg)
		screen_blank(s_a, line, 0, line, SCREEN_WIDTH-1, fg, bg)

/* 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 description 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(bounds) (*screen_sw[WS].hide_loc) (bounds)

/* APA Screen init */
#define apa_initialize() (*screen_sw[WS].apa_init) ()

/* Real hardware addresses for the displays */
#define screen_addr(n) screen_sw[n].addr

#define lp_pos_cursor(col,line,dev)   (((line)*screen_sw[(dev)].width)+(col))

.fi
.sh 1 "INPUT EMULATOR INTERFACE"
.lp
The low-level interface to the input emulator is not defined as
strictly as the one for the output emulator.
Basically, a set of hardware routines
in \fIkeyboard.c\fP, \fIkls.c\fP, \fIspeaker.c\fP, and \fImouse.c\fP
can be called by an input emulator to control the keyboard, speaker, and
mouse.
The input emulator
receives a data interrupt from the keyboard or mouse.
The emulator deciphers the data and tracks
the state of the device; then passes its
processed data to the user through a \fIline discipline\fP
or some other emulator-specific method, such as shared memory.
.lp 
Few procedures are needed to control a keyboard for setting
the auto keyclick rate, bell tone, and key characteristics
(repeat rate, make/break, etc.).  Because few workstations
support multiple keyboards simultaneously,
there is no need to set up a
switch table for these hardware routines.
Workstation mouse devices also have few control operations (set sampling or
resolution rate); input emulators do not yet deal with these operations 
directly,
but instead pass \fIioctl\fP
system calls to the appropriate driver.
.sh 1 "WINDOW MANAGER DEVICE-DEPENDENT ROUTINES"
.lp
Listed below are the device-dependent routines
available with the \fIscreen_sw\fP
low-level routines.  These are normally used in an input emulator to
control the graphics cursor.
.ip pos_loc()
Position the locator at a given coordinate on the display.
.ip load_loc()
Load a locator bitmap for the display.  This is 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 do not affect the tracking.
.ip apa_init()
Initialize the display for graphic operations needed by
the locator.  Useful for displays with hardware
cursors/locators.
.sh 1 "SYSTEM INTERFACE TO THE EMULATOR"
.lp
A new emulator should be easy to add to a system and must be able to
coexist with other emulators.
An emulator has many functions and system entry points similar to
those of a tty hardware device driver. 
The main difference is that emulators funnel through a single
console driver and call a common set of hardware routines, while
device drivers deal directly with the hardware.
.lp
The emulator switch table below lists all routines necessary
for a device driver to interface with an emulator.  To add
an emulator to the system, add the following routines in the
switch table structure shown below.  This structure (modeled after
line disciplines) is declared in \fIscreen_conf.h\fP,
and the table is initialized in \fIscreen_conf.c\fP.
.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     (*e_color_table)();	
};
.sp 2
.fi
.lp
Each emulator, depending on its needs, has the following
entry points in the kernel:
.ip e_open()
.br
Open the emulator to do any necessary initialization.  Perform initial
operations such as clearing the screen, initializing the cursor, and 
positioning
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 (used only by input emulators). 
For most emulators, this routine forwards the read
request to the user-defined line discipline.  The read routines 
.bp
in line
disciplines currently perform the operations necessary for this routine.
This consists of taking the already-received characters 
off a \fIclist queue\fP
and passing them to the user program's read buffer.
.ip e_write()
.br
Write data to the emulator (used only by output emulators).
This procedure takes a character stream
passed from the
user-level program.  Most emulators call the line discipline
specified by the user 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 to allow flexibility.
Some specialized emulators do use these routines for other
than calling the associated line-discipline routines (see \fIbuf_emul\fP(4)).
.ip e_ioctl()
.br
I/O control to emulator for changing or setting characteristics of the
emulator or performing operations that do not fit into the normal
interface to the emulator.  This routine should return a (\(mi1)
if the command is not recognized.
.ip e_rint()
.br
Receive interrupt to emulator (used only 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 passes the processed input data 
to the user-assigned line-discipline input routine.
Some specialized window-manager emulators do not forward these data to a
line discipline, but do their own queuing and interacting with a window
manager.
.ip e_putc()
.br
Put a character on the display (used only by output emulators). 
This emulator routine receives a
character from a user's write or kernel printf.  The emulator 
deciphers the data and interprets character strings before passing
the appropriate characters to the hardware putc routine.
This procedure makes use of the screen switch table (screen_sw)
in calling the device-dependent routines to perform the emulation on any
display.
.ip e_select()
.br
Select call to emulator (used only by input emulators).
This routine is used to 
perform the normal select duty of informing the user process
when new data are ready.
.ip e_putstatus()
.br
Put status call to emulator (used only by output emulators).
The emulator takes the passed 
string and places it at an offset on the status line.
.ip e_color_table()
.br
Changes the screen's color table (used only by output emulators).
.bp
.sh 1 "CONSOLE DRIVER'S RELATIONSHIP TO 4.3/RT"
.lp
The following diagram shows how the parts of the system described
relate to the standard parts of a 4.3/RT 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	\^
\_	\_	\_
.T&
c s | cb.
Displays/Keyboard/Speaker System or Serial Mouse	Hardware
.TE
.lp
The above is a conceptual view of the system.
It does not show all
parts and interfaces, but indicates
the levels of flow.
The console driver routes normal driver requests 
to the correct display and 
input/output emulator, depending on the minor device specified.
.lp
The following shows how the minor device number 
maps to an emulator and display:
.sp 1
.TS
center, tab(+), allbox;
cb cb cb
c c c.
Output Emulator Flag+Bus+Display#
bits 7 - 4+bit 3+bits 2 - 0
0 or 1+0 or 1+0 - 7
.TE
.lp
The following is a list of currently-used displays supported by 4.3/RT:
.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_APA16	IBM 6155 Extended Monochrome Graphics Display (bitmap)
3	CONS_APA8C	IBM 6154 Advanced Color Graphics Display (bitmap)
4	CONS_APA8	IBM 6153 Advanced Monochrome Graphics Display (bitmap)
5	CONS_EGA	IBM 5154 Enhanced Color Graphics Display (character)
6	CONS_MONO	IBM 5151 Monochrome Display (character)
.TE
.lp
If the bus bit is set, opening the device grants
access to the I/O bus.
Without this bit, it is necessary to open \fI/dev/bus\fP to gain
access to I/O space.
This bit is provided for compatibility;
new applications
should open \fI/dev/bus\fP if they need bus access.
.lp
The emulator field in the minor device number tells the console
driver that the default glass_tty input/output emulators will be used (0),
or indicates that a non-standard output emulator will
be used (nonzero).  If a non-standard output emulator is used,
the system restores the display to the
standard state (\fIdefault emulators\fP)
when the device is closed.
.bp
.lp
The following is a list of emulators currently available:
.sp 1
.TS
center allbox;
cb s s
n l l
.
Emulators Available
_
Emulator #	Symbolic Name	Description
0	E_KBDINPUT	Intelligent keyboard mapping input emulator (standard)
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_AED	Raw AED microcode interface emulator
.TE
.sp 1
.lp
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_KBDINPUT	E_STDOUTPUT
APA16	E_KBDINPUT	E_IBMOUTPUT
APA8C	E_KBDINPUT	E_IBMOUTPUT
APA8	E_KBDINPUT	E_IBMOUTPUT
MONO	E_KBDINPUT	E_IBMOUTPUT
.TE
.sh 2 "Input From Keyboard Scenario"
.np
User types character on keyboard.
.np
Receive interrupt in keyboard driver, keyboard.c, interrupt routine 
\fIkbdint()\fP.
This routine extracts key code from the hardware.
.np
Call emulator receive-interrupt routine from the switch table indexed by
the current
\fIinput focus\fP after setting the 
emulator structure flag, indicating that this was a keyboard interrupt.
.np 
Emulator checks whether this was a keyboard interrupt.
If so, it either translates code into a character
and calls normal line-discipline routine for this console with the 
translated character, or
performs some emulator-specific function such as storing the raw key
code in a shared-memory area (X-like)
and setting a semaphore, also in shared memory, to inform
the user process that a new event has arrived.
.np 
If a line-discipline input routine is called, it performs its
previously-described normal input (editing/mapping) and passes the
result to the user through the read system call interface.
.np
If a shared-memory queue interface is used, the user process notes
the queue update through the semaphore and proceeds to read the data
from the shared memory without performing a read or any other system call.
.np 
In either of the above two cases, a select would be satisfied
if the user had previously done a select call.
.sh 2 "Output To Display Scenario"
.lp
This scenario applies only to glass-tty operations. 
The window-manager system goes directly to the display hardware
through its own graphics routines.
If a user tries to write through the system to the display while
a window manager is controlling the display, a special 
\fIbuffer emulator\fP is called instead of a glass-tty emulator,
as in the scenario below.
.np
The user performs a \fIwrite\fP system call
with a buffer of data for the display.  These data consist of
ASCII data or display order streams.
.np 
The console write routine then calls the write routine of the
output emulator selected by the minor device number.
.np 
For most emulators, the output-emulator write routine then forwards 
these data 
to the line-discipline write routine specified by the user. 
Certain emulators, such as the buffer emulator,
intercept these data and capture them for printing later.
.np 
The line discipline interprets the data and calls the console start
routine to print the ASCII characters.
.np 
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.
.np 
The output emulator put-character routine
then deciphers the data and
calls the appropriate device-dependent routine to display the
character or perform the display command.
.sh 1 "USER INTERFACE TO THE EMULATORS"
.lp
The user interface to the emulators consists of system
calls to the console driver (see 
\fIcons\fP(4) and \fImouse\fP(4)).
.sh 2 "Interface to Keyboard Input and Display Output"
.sh 3 "Standard Interface"
.lp
In the simplest case, a user program still performs the same
operations as in the past, allowing previously-written programs to
work without change.  The following lists the normal scenario and what the
emulator package does:
.sp
.TS
center, tab(+), allbox;
cb s s s s
c c c c c.
Standard Console Interface Device
Permissions+owner+major+minor+device
crw-rw-rw-+root+0+0+/dev/console
.TE
.np
An application such as login opens \fI/dev/console\fP.
Since \fI/dev/console\fP is the special CONS_GEN minor device, in
.q "open" 
the output is
mapped to the current console-focused display. 
The display at which a program is started is the display associated with
the process.  The system starts the default input and output
emulators for that display.
Input is received only if the input focus is set to CONS_GEN.
.np 
The application reads or writes to the file descriptor returned
from the open system call.
The system maps writes to the CONS_GEN minor device
to the display with the current input focus.
This causes the appropriate
display-indexed input/output emulators to be used.
Input is focused to CONS_GEN if no console tty devices
and no console graphic devices are open, except when using the
default input emulator (E_KBDINPUT).
If the input focus is not on CONS_GEN, the input focus follows the 
output focus.
.np 
The application exits or closes the \fI/dev/console\fP file descriptor.
The system closes the 
input/output emulators and the stream for the display with
the current input focus.
.lp
Mapping \fI/dev/console\fP to the current display is important for
most applications that do not need to know on which display they are
running.  This mapping is also important
at system boot time where the single-user
shell does not know on which display it
is starting and is simply mapped to what the system chooses as the
starting input focus.
But some applications (for example, login, window manager) need to know
on which display
they should start.
Therefore, the following devices are provided to support the displays
available on 4.3/RT:
.TS
center allbox;
cb s s s s
c c c c c
l l c c l
.
Standard TTY-like Display Devices
_
Permissions	Owner	Major	Minor	Device
crw-rw-rw-	root	0,	1	/dev/ttyaed
crw-rw-rw-	root	0,	2	/dev/ttyap16
crw-rw-rw-	root	0,	3	/dev/ttyap8c
crw-rw-rw-	root	0,	4	/dev/ttyapa8
crw-rw-rw-	root	0,	5	/dev/ttyega
crw-rw-rw-	root	0,	6	/dev/ttymono
.TE
.lp
To start an application on a particular display,
reassign its standard input and outputs to any of these devices or
have the application specifically open one of them. 
The system routes 
output from the application to the appropriate
display and its default emulators.  Input to the application from the
keyboard only occurs when the console focus is assigned to that display.
To switch between open displays, press the specified hot-key for your
system or use an application which performs an
\fIioctl\fP system call
to set the input focus.
.lp
The different displays on the system are specified in the
.ul
/etc/ttys
file that tells the system to start logins on each of the
displays.  A user can hot-key to the desired display and,
after logging in, run any application needed.  Any application started on that
display stays associated with it, because it was started while the 
console focus was on that display.  Because this is an
application-transparent mapping to that display taking place in the
kernel, a user can log on simultaneously
to as many displays as needed.
.sh 3 "Nonstandard Interface"
.lp
For applications that call for a specific non-default emulator, 
the following devices are provided:
.sp 1
.TS
center allbox;
cb s s s s
c c c c c
l l c c l
.
Nonstandard Display Devices
_
Permissions	Owner	Major	Minor	Device
crw-rw-rw-	root	0,	65	/dev/aed
crw-rw-rw-	root	0,	66	/dev/apa16
crw-rw-rw-	root	0,	67	/dev/apa8c
crw-rw-rw-	root	0,	68	/dev/apa8
crw-rw-rw-	root	0,	69	/dev/ega
crw-rw-rw-	root	0,	70	/dev/mono
.TE
.lp
The emulator flag is nonzero 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 opens the standard input emulator and a special
buffering output emulator, because most applications that
open the nonstandard device take over the screen and want output
from other sources (such as kernel \fIprintf\fPs) to be buffered and displayed
when the display is closed.  See \fIbufemul\fP(4)
for more information.
If bus access is required on open, add 8 to each minor device number.
.lp
The following is a list of commands available through the
\fIioctl\fP 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{
Output 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 output 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 console 
focus (xemul only).
T}
CON_SET_FOCUS_CODE	Yes	Yes	T{
Set the current keyboard code for setting the console 
focus (xemul only), 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
.lp
All of the above commands take integer arguments except the last two.
SCRIOCGETF and SCRIOCSETC use the following structure:
.(l
.nf
struct screen_control   {
	int	device;	/* which screen/display to control */
	int	switches; /* Flags for this screen */
};
.)l
.fi
.sp 1
.TS
center allbox;
cb s 
c c
l l
.
Flags 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_TTY	Tty display has been opened directly by minor device number.
CONSDEV_GRA	Graphics display has been opened directly by minor device number.
.TE
.lp
All of the above
\fIioctl\fP system calls
are device-independent controls
for dealing with the emulators. 
.lp
Each emulator has its own set of \fIioctl\fPs
for its own emulation purposes.  These other \fIioctl\fPs
are used in window-manager 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.
.sh 2 "Mouse Input Interface"
.lp
The interface to the system mouse is similar to that of the keyboard.
If the generic mouse device
.ul
/dev/mouse,
minor device 0, is opened,
the mouse input is attached to the display which has the
current input focus.  Opening any other mouse device attaches the
mouse input stream to the process only when the input focus is on the
associated display.
.lp
The following mouse devices are provided:
.sp 1
.TS
center allbox;
cb s s s s
c c c c c
l l c c l
.
Mouse Input Devices
_
Permissions	Owner	Major	Minor	Device
crw-rw-rw-	root	15,	0	/dev/mouse
crw-rw-rw-	root	15,	1	/dev/msaed
crw-rw-rw-	root	15,	2	/dev/msapa16
crw-rw-rw-	root	15,	3	/dev/msapa8c
crw-rw-rw-	root	15,	4	/dev/msapa8
crw-rw-rw-	root	15,	5	/dev/msega
crw-rw-rw-	root	15,	6	/dev/msmono
.TE
.lp
The
.ul
system mouse
driver is essentially the same as those in other 4.3BSD-based systems.
This driver hooks into the emulator package by selecting a
special line discipline.  The 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 \fItb\fP(4) manual page.
.lp
For compatibility,
the default line discipline may be set using the upper four bits of the minor
device number.
To get the device interface specified in \fImouse\fP(4), use the discipline
MSLINEDISC from <\fImachineio/mouseio.h\fP>.
Any new software that uses the mouse should set its desired
discipline explicitly.
.sh 1 "FILES INCLUDED WITH THE EMULATOR"
.lp
The following tables briefly explain the files contained in the emulator
package.  The tables specify files according to function.
Each table states where the files are located and describes 
.bp
what each file contains.
Tables with a column marked
.ul
User
distinguish between purely kernel files
and user/kernel-shared include files. 
These user include files are needed to access emulator functions.
.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 which displays and screen controls/flags are available.  The
ioctl commands and structure for screen_control are in this file. 
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 that 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 \*(lqEmulator
Package Functions\*(rq, above.
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, 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}
ibmemul.h	\^	\^
_
kbd_emul.c	no	T{
A 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 output emulator routines, which send raw characters to the
display on output.  This output emulator is used for displays
that perform their own emulations.
T}
std_emul.h	\^	\^
_
x_emul.c	no	T{
X window system input emulator, which queues up keyboard and mouse
events into a memory area shared 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 the X emulator
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 
mouse devices 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
aedtty.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}
egatty.c	T{
EGA glass tty low_level device_dependent routines
T}
egatty.h	T{
EGA device_dependent structures and defines
T}
ega_init.h	T{
Initialization sequences for the EGA
T}
ega_font.h	T{
Fonts for the EGA
T}
apaaed.h	T{
Structures and defines for dealing with the AED as an APA display
T}
lptty.c\ \ \ \	T{
APA print screen support and print
T}
monotty.c	T{
Monochrome glass tty low-level device-dependent routines
T}
monocons.h	T{
Monochrome device-dependent structures
T}
monotty.h	T{
Monochrome 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
kls.c	Keyboard/mouse/speaker common routines
kls.h	Keyboard/mouse/speaker low level defines
.TE
.sp 1
.TS
expand allbox;
cb s s
cb s s
c c c
l c ltw(4i)
.
System Mouse Device Driver
_
/sys/machineio
File	User	Description
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}
speaker.c	no	T{
Speaker driver
T}
speakerio.h	yes	T{
Speaker structures and defines
T}
speakervar.h	no	T{
Internal speaker data structures
T}
.TE
.ba 
.if t .if o \{\
.bp
.rs
.sp 25
.ce 
This page intentionally left blank.
.\}