XAPOLLO(1) SysV XAPOLLO(1)
NAME
Xapollo - Apollo Domain/X11 "shared" X window system server
SYNOPSIS
Xapollo [-D1] [ s{+|-}r{+|-} ] [ -K keyboardfile ]
DESCRIPTION
Xapollo is the Apollo Domain/X11 "shared" X window system server. It
supports the MIT X11 version of the X protocol.
Xapollo is called a "shared server" because it can run in two modes
wherein X and Apollo Display Manager (DM) windows are displayed on the
screen together, "sharing" the display.
See below under "Implementation Notes" for a detailed description of
server features.
CONFIGURATIONS
Xapollo runs on Domain/OS, under Apollo software release SR10.2. TCP/IP,
available at SR10 as a bundled product, must also be installed and
running to take full advantage of X's remote display ability, but it is
not necessary for local-only connections using Unix domain sockets.
Xapollo operates on any Apollo color or monochrome display hardware. It
requires a keyboard with a mouse.
OPTIONS
The Xapollo server program takes the following device dependent options.
In addition, the "standard" X11 server command line options can also be
used. These options are described under Xserver(1).
-D<unit>
This option gives the display unit number to which the following s
(share mode) and r (own root) options should apply. Since at
present Apollo does not support multiple display devices, only -D1,
meaning display unit 1, is meaningful. -D1 is the default.
s{+|-}r{+|-}
s specifies whether the Domain/X11 server should "share" the display
with the Apollo Display Manager (DM). s+ means, "yes, share the
display." In this mode, you can have both DM and X clients on the
screen at the same time. s+ is the default.
s- means "do not share the display." In this mode, the Domain/X11
server will borrow the entire display and you can run only X
clients. (This is the way that the public-domain servers from MIT
and from ADUS behave.) If you are going to use s-, you should give
the Xapollo command as part of an xinit(1) command so that you can
also start an xterm(1) at the same time. This way, when the server
borrows the display you have something you can type to. See the man
page for xinit(1).
The s switch can alternately be specified with a capital S,
depending on whether or not the X server takes advantage of the fact
that the DM has multiple input focal points. s+ signifies only one
input focal point, and S+ signifies multiple input focal points.
This switch only affects reparenting window managers (such as mwm
and twm) that are used with DM pads. The server can thus be started
with either one or multiple input focal points, as in:
/etc/Xapollo -D1 s+r- = One input focal point
/etc/Xapollo -D1 S+r- = Multiple input focal points
With one input focal point (s+), a reparenting window manager
doesn't know when the cursor is in a DM pad. You must move the
cursor to the reparented border to issue window manager commands.
(The reparented border is highlighted when the cursor is on the
border but not when the cursor is in the pad.)
With multiple input focal points (S+), the reparenting window
manager knows when the cursor is in the pad. This is signified by
the reparented border staying highlighted. This implementation
causes a minor but very visible bug. The X server doesn't know when
or if the cursor has left the reparented border and moved into the
DM pad. This means a cursor image is left displayed on the border
even when the cursor is in the DM pad (i.e., the user sees two
cursors images on the screen; of these, the cursor image in the pad
is correct, and the cursor image in the border is incorrect). This
problem also occurs in all disowned windows.
r{+|-} specifies (given s+) which of the two Apollo window systems-
-the DM or X--should own the root (background) window and be
responsible for window management. r- means that the DM should own
the root. It is the default. r+ means that Domain/X11 should own
the root window.
s and r should form a single string without embedded blanks, e.g.:
s+r-
-K keyboardfile
The -K option specifies a keyboard configuration file. -K is useful
when:
- The server is being run s+r- (share mode, DM owning the root).
You need the configuration file when the DM owns the root so that
you can Pop, Move, and Grow X windows.
- The server is being run in X-owns root or borrow mode. In this
case the configuration file can specify a key to use as a "Quit
server" key.
If -K keyboardfile is not specified, by default all keys go to the X
server. By default, there is no "Quit server" key.
The keyboard configuration file contains simple one-statement-per-line
commands that parcel out the keys on the keyboard (either keyboard 2 or
3) between the DM and X. There are three commands:
quit <Xkeysym>
Names a key that will exit the X server when pressed in "X
territory." X territory is any X window listening to keypress
events, or the background root window if X owns the root. (Most
X clients take keypress events e.g., xterm(1). A very few--
xclock(1) is one--do not.)
The main purpose here is to provide a way to kill the X server
and return the DM if the X server should hang in borrow mode.
The quit key will work in any server mode, however. By default,
there is no quit key.
exclude <Xkeysym>
When the X server initializes, by default it "takes" all keys on
the keyboard to itself. If you press a key in X territory, then
X gets first crack at the keyboard event. (Only in the rare "no
keypress event" clients like xclock does the event pass through
to the parent window--which might be the background owned by X or
the DM.)
This behavior is in keeping with the idea that X should be able
to run on Apollos as though it were the only window system
present, and clients should be able to assume they can use the
whole keyboard.
Practically, though, there are keys you want the DM to receive,
even if they are pressed in X territory. For example, if the DM
owns the root and is handling window management, you probably
want Pop, Move/Grow, Cmd, NextWndw, etc. to work in X windows.
Saying "exclude <Xkeysym>" means "exclude this key from X and
give it to the DM."
! Comment character. (After the fashion of xmodmap(1).) This must
appear in column 1 in order to denote that the line is a comment.
/usr/lib/X11/keyboard/keyboard.config is a sample keyboard configuration
file. All non-white-key X keysyms on Apollo keyboard 2 (no keypad) and
keyboard 3 (keypad and F0, F9) are shown. You should copy this to your
home directory and customize it as you see fit. A reasonable choice of
DM keys are already listed as "excluded" meaning that they will go to the
DM no matter what territory they are pressed in. A Quit key command is
commented out.
STARTING XAPOLLO
We recommend that you start Xapollo at boot time with the configuration
files specified for it in /etc/rc, by adding an empty file named Xapollo
in your /etc/daemons directory:
touch /etc/daemons/Xapollo
You may also want to start Xapollo at login by adding the line
/usr/bin/X11/startx
to one of your startup files (e.g., .login). The startx script uses
xinit to start the server. In addition, it references the files xinitrc
and xserverrc in /usr/lib/X11/xinit. (We have placed other files in that
directory that you may wish to copy into your home directory as files
.xinitrc and .xserverrc, depending on whether you want to start Xapollo
in DM- or X-root modes.) See /usr/lib/X11/xinit/xserverrc for the exec
command that starts the server.
Do not run the server from the command line using only Xapollo <options>
&
IMPLEMENTATION NOTES
What Is a Shared Server?
Xapollo is called a "shared server" because X and DM windows can share
the screen in two modes:
- The DM "owns" the background (root) window, draws the cursor as its
familiar arrow, and does all window management (move, resize,
iconify, etc.) for both X and DM windows. The DM acts as the primary
window system.
- The X window System "owns" the background (root) window and draws the
cursor as its familiar "X". DM window management has been explicitly
turned off. An X window manager (probably uwm(1) ) has been started
and is used to move, resize, iconify, etc., both X and DM windows. X
is the primary window system.
"Shared" can be contrasted with "borrow mode." The ADUS Apollo X11 and
MIT-tape X11 Apollo servers were both "borrow mode" servers where the X
server takes over the entire display. You can switch back and forth
between X and the DM, but you cannot display both types of windows at
once.
Having the Domain/X11 shared server makes it possible, for example, to
use the Apollo debug utility (which is written to use DM PAD calls) to
debug an X client and view both on the screen simultaneously.
DM PAD call and/or Apollo native graphics-based programs do not have to
be recoded, recompiled, or relinked in order to work with the Domain/X11
server in either share mode. If it did run, it will run.
X clients linked to the ADUS X11 Apollo Xlib should be relinked with the
Domain/X11 Xlib.
"Shared server" does not mean that one program has been written that acts
as both an X and a DM window system. The Xapollo server and the DM
remain distinct programs.
X and the DM are able to co-exist because of a pair of low-level Apollo
system facilities called the Rectangle Manager (RM) and Input
Demultiplexor (IDM). Introduced at SR9.5, these internal facilities
underlie both X and the DM.
The Rectangle Manager (RM) manages a workstation global database of
rectangular display areas on the screen. The database describes size,
location, the hierarchical stacking order of the rectangles,
parent/sibling relationships, which windows are obscured, and which
process owns them. RM does not "draw" anything on the screen; that is
the responsibility of the owning process. It is just a database of
rectangle trees.
The Input Demultiplexor (IDM) controls workstation input from the
keyboard and mouse. It maintains a global database of hierarchical input
focus trees (related to the RM's rectangles), event queues, and provides
a mechanism to bind particular devices, events, and processes together.
The RM/IDM together form a kind of window system in the abstract. The RM
keeping an abstract representation of the screen layout, the IDM an
abstract model of keyboard and mouse input.
Both the Domain/X11 X server and the DM use RM calls to create and
manipulate windows. Both use IDM calls to handle input events. Because
there is one database with window and input information that both appeal
to, X and the DM can manipulate each others' windows and input is routed
properly. So subtle a problem as passing the keyboard focus back and
forth between X and the DM as the cursor slides over a random mixture of
X and DM windows on the screen can be handled smoothly.
Normally, RM and IDM are invisible to the user, but it occasionally helps
to know that this is what is actually going on. RM/IDM are part of
/lib/gprlib.
Native Graphics Protocol Extension
Apollo has added one extension to the X11 protocol. This extension lets
X clients initialize and call Apollo native graphics routines in a
subwindow. It is therefore possible to write a program that has an X
interface (whether straight Xlib, Open Dialogue, the MIT X Toolkit, etc.)
surrounding, say, a 3D GMR, GPR, or PHIGS graphics application.
Such hybrid clients will not run across a remote client/server connection
(because Apollo native graphics are not protocol requests) nor are they
directly portable to non-Apollo hardware platforms. They do, however
give access to the speed of native graphics, provide a halfway house for
vendors trying to port existing native graphics programs to X, and
provide a way to do 3-D graphics, which X presently lacks.
This mechanism has come to be called "disowning a window." Example
programs are in /usr/X11/examples/x_and_gpr and
/usr/X11/examples/x_and_3dgmr.
Server Features
- The server supports monochrome, 4, or 8-plane color. The number of
planes is detected automatically at server startup.
- When running on monochrome DN300, DN330, DN440, DN460 nodes, the
server uses the portable but slow Monochrome Frame Buffer (MFB)
driver code. On all other nodes, whether color or monochrome
(DN560, DN570, DN580, DN590, DN3000, DN3500, DN4000) the Domain/X11
server is optimized to use Apollo native graphics interfaces.
- The server calls the Apollo Color Table Manager (CTM) to
allocate/free color cells in the color map. It will thus not
interfere with other programs that are well-behaved enough to use
the CTM.
- The server provides full support, as defined in the X Protocol, for
Apollo keyboard 3. (Keyboard 2 does not have hardware "up"
transitions, such transitions are emulated.) Apollo international
keyboards 3a-g are also supported, meaning that appropriate keysyms
are assigned from the Latin 1 alphabet to the different
multinational boards automatically at server initialization.
The exception to keyboard support is ChangeKeyboardControl
(controlled with the xset(1) command). xset(1) functions
controlling the pointer motion buffer, threshhold and acceleration
factors are not implemented. Apollo keyboard hardware does not
allow for implementing xset(1)'s keyclick, bell pitch, or volume
control.
- Domain/X11 includes a set of FORTRAN and Pascal "interludes" that
make it possible to write Pascal or FORTRAN clients that call Xlib,
which is written in C. The interludes bridge the incompatible
conventions of case and parameter-passing between C and Pascal and
Fortran. Interludes exist only for Xlib subroutine calls; the many
macros do not have interludes.
- The Domain/X11 libraries have also been slightly modified so that
they can be linked to X clients that were compiled and type-stamped
under the "bsd4.2," "bsd4.3," or "sys5.3" environments. Some X
libraries, e.g., x11lib and xtlib, are installed in the /lib
directory as run-time libraries with globally-known symbols. Xlib
must be included in the client node's /etc/sys.conf files with the
line
lib x11lib, optional
(Note: The default sys.conf contains x11lib.) To keep Domain/X11
compatible with the X Consortium's X11, libX11.a is provided as a
"dummy" library in /usr/lib/X11. When a program is linked against
this dummy library, no symbols are resolved, and the runtime library
will be used instead.
All other X libraries in /lib have corresponding archive libraries
in /usr/lib/X11. These libraries might change from X release to X
release, causing clients using globally-known symbols not to work
with the next release of the library. Because of possible changes
to libraries, the application developer must determine which style
of library should be used. Clients linked with archive libraries
will be larger but will never need recompiling or relinking.
Clients using run-time libraries with globally-known symbols will be
smaller but will probably require recompiling or relinking to
synchronize with the new run-time library.
ERROR LOGGING
Domain/X11 server errors are logged in the file
`node_data/system_logs/X0msgs , which is a link to /usr/adm/X0msgs of
errors. If possible, it includes fault diagnostic information and a
traceback.
LIMITATIONS
You cannot cut/paste between X and DM windows. X and DM windows do not
share X window properties.
The underlying support necessary to make "reparenting" window managers
such as twm(1) work on both X and DM windows is not fully implemented.
You can run twm(1) and it does work, but anomalous behavior does occur,
particularly surrounding newly-created DM windows.
SEE ALSO
X(1), Xserver(1), xinit (1), xownroot (1).
COPYRIGHT
Copyright 1988, 1989, 1990 Apollo Computer Inc.
AUTHORS
Joe Bowbeer, Dave Gorgen, Jim Hamilton, Steve Reber, Bob Terek,
Craig Wolpert
Apollo Computer Inc.