XFree86 on Darwin and Mac OS X DP4
XFree86, a free implementation of X Windows,
has been ported to Darwin
and Mac OS X, Developer's Preview
4. This page is a collection of useful patches and information for anyone
experimenting with running X Windows on Apple's
next generation operating system. Please send any comments on this page
or the update to torrey@mrcla.com.
If you are also working on modifications to the Darwin X server, please
let me know.
News
- August 21, 2000: I did my part for documentation. :-) I finished a first draft at HeaderDoc documentation of IOGraphicsLib.h, which XFree86 for Darwin makes many calls to. Update E was also integrated in Apple's CVS repository today and should be available for public CVS soon.
-
August 20, 2000: Update D (without Naoki's patch) has been integrated into
Apple's CVS repository. Naoki and I have finished a new update, which integrates
multi-button support for new kernels in a way that is safe for older kernels
and that adds support for scroll wheels.
-
August 17, 2000: Naoki Hamada released a patch to Update C that adds multi-button
mouse support for new versions of the kernel and I fixed a problem with
caps lock on some machines. Both of these things are rolled into Update
D.
-
August 12, 2000: Update C is now available. This update fixes many keymapping
bugs, including the shift-repeat problem, and adds the ability to tell
left and right modifier keys apart.
-
July 30, 2000: A new update (Update B) is now available that adds support
for 8 bit color and older PowerBook G3's.
-
July 25, 2000: I added a page with help on building and running XFree86
for the first time.
-
July 24, 2000: Update A is available.
Contents
I have put together a page to help people get started building and running
XFree86 on Darwin and Mac OS X DP4 here. The rest
of this page assumes you have already built XFree86.
Updates
The XFree86 distribution modified to build on Darwin 1.0 or Mac OS X DP4
is available from the Apple
CVS site. Note that this version will not work with earlier versions
of Mac OS X or Darwin. The original version of XFree86 on Darwin was a
somewhat preliminary implementation. I have produced several updates to
address some of the more important issues. The updates are available, rolled
together, as a new darwin.c file to put in your
XFree86/xc/programs/Xserver/hw/darwin/ directory or as a patch. (Older
updates are also available below.) All updates
are meant to replace version 1.3 in the repository, dated August 18, 2000,
and have been tested on Dawin 1.0.2 and Mac OS X DP4. There are still a
number of outstanding issues, summarized below, that
have not yet been addressed. If you notice other problems not listed below
or want to contribute to fixing them, please let
me know.
Get the Updated Files
New Features of Update E
-
Naoki's multibutton patch could potentially lock up your computer if -multibutton
enabled with an older kernel. This has been fixed and multibutton support
is now always enabled. On older kernels all mouse buttons will function
as mouse button 1, but on newer kernels your extra buttons will automatically
work. There is no longer a need to use a -multibutton command line option
and you will get an error if you do.
-
Naoki created another patch to support mouse scroll wheels. After a little
tweaking and testing this works beautifully, at least on an Microsoft Intellimouse
Explorer. You will need to change some of your X client applications to
get them to support the scroll wheel. A good overview of how to do this
can be found at Colas Nahaboo's X
mouse wheel web page.
New Features of Update D
-
Danny Hembree pointed out that the caps lock problem was not fixed on his
older PowerBook G3. I confirmed that this was also true on iBooks, although
caps lock functioned properly on PowerMac G4's. This update should fix
the caps lock problem on all machines.
-
Naoki Hamada submitted a patch to Update C on the Darwin
Development mailing list that adds multi-button mouse support. This
patch is only useful if you are running a kernel that is newer than August
10, 2000 as there was an important change in Darwin's event handler. To
enable the patch, specify the -multibutton option. I have not yet tested
this patch on a newer kernel, but the X server builds and runs happily
on older kernels as long as you do not specify -multibutton. If you
are running an older kernel, do not use -multibutton or you will lose all
mouse button events. I have folded Naoki's patch into Update D, and
by default multi-button mouse support is off. I have, however, provided
another version of darwin.c without the patch for the non-thrill seekers.
:-)
New Features of Update C
This update is a complete rewrite of the X server's keyboard mapping routines.
The X window keyboard map is now set by querying Darwin for its keyboard
map and translating it appropriately. This fixes a number of problems and
adds some new features:
-
Fixed infamous shift repeat problem: On previous versions, typing the pattern
Shift-down, j-down, Shift-up, j-up would produce "Jj" in a text window.
(The pattern Shift-down, j-down, j-up, Shift-up worked correctly, on the
other hand.) This shift-repeating strangeness is now fixed.
-
Fixed caps lock problem: The caps stay locked even after the Caps lock
key was unlocked on previous versions. (You had to relock the caps and
then unlock again to get back to lower case.) Caps lock now works as expected.
-
Left and right keyboard keys are distinct: There is now support for telling
the difference between left and right modifier keys. On my PowerMac G4,
the shift keys are correctly mapped between left and right, but the Command
keys are not due to a problem with the Darwin keyboard map. (Sadly my keyboard
only has one Control and Option.)
-
Numerical keypad keys are distinct: The X server now knows the difference
between keys on the numeric keypad and equivalent keys on the normal keyboard.
-
Miscellaneous keymapping fixes: Enter now maps to KP_Enter instead of nothing.
If you experience problems with keymapping with Update C or want more information
on how the new routines are different, please see the section below
on keymapping.
New Features of Update B
-
8-bit color (PseudoColor) support: 8-bit color depth is now supported.
Previously, using -depth 0 or running on hardware that only supports 8-bit
color would cause the X server to crash. In particular, older PowerBook
G3's can now run X server as described below.
New Features of Update A
-
Multi-button mouse emulation: Most Macs use a single button mouse and the
early Darwin drivers don't support most multi-button mice. The update adds
the ability to turn on this emulation so that Command-Button1 = Button2
and Option-Button1=Button3. The emulation is off by default, but can be
turned on with the command line switch -fakebuttons.
-
Screen resolution, refresh rate, and depth: The screen resolution, refresh
rate, and pixel depth can be changed when starting up the X server with
command line options. Changing resolutions dynamically after the X server
has started is not supported.
-
Uses the IOConnectMapMemory() and IOConnectAddClient() calls instead of
the deprecated IOMapMemory() and IORegisterClient().
-
More comments added to the source code.
Installation Instructions
-
Download the new file here. (Older PowerBook G3
users should be sure to apply the additional change described below.)
-
Put the updated file in your XFree86/xc/programs/Xserver/hw/darwin/ directory.
-
Go to the XFree86/xc/programs/Xserver/ directory and type "make".
-
su to root
-
Type "make install".
Usage Instructions
The new features of this update are controlled by command line options.
The easiest way to issue command line options to the X server is to put
a .xserverrc file in your home directory with the following text:
X [options] >& xserver.log
This will write the text output from the X server to a file in your home
directory called xserver.log. This may be useful for diagnostic purposes.
The options accepted are:
| -fakebuttons |
Emulate a 3 button mouse using Command and Option |
| -nofakebuttons |
Don't emulate a 3 button mouse (default) |
| -size <width> <height> |
Set the screen resolution for the X server to use |
| -depth <depth> |
Pixel depth to use (0 = 8 bits,1 = 15 bits, 2 = 24 bits) |
| -refresh <rate> |
Refresh rate to use in Hz |
If neither -size, -depth, or -refresh are specified the current screen
parameters are used. If only one or two are specified, some sensible combination
of the unspecified parameters is chosen by the X server. Note, that if
you choose an invalid combination of screen resolution, depth, and refresh
rate the X server will quit with an error message to the log file. Unfortunately
the screen will not be put back into a well behaved state and you will
have to logout and back in again to get back to the console. This is due
to the server shutdown problem described below. (The X server will not
set your display to an invalid mode, it just doesn't have a way to exit
cleanly at this point.)
Note for Laptops: On the iBook I tested the update on, -refresh
0 had to be specified if any -size options were given. Without -refresh
0 the screen went totally black and took a restart to fix. This is because
Darwin reports 60 Hz as a valid refresh rate which the X server tries to
use it by default. I believe this is a bug in Darwin's (still evolving)
low level graphics code. I would suggest using -refresh 0 if you specify
any -size options on a laptop.
Note for older PowerBook G3 laptops:
The Darwin video driver for older PowerBook G3 laptops only supports one
display mode: 1024 x 768 at 75 Hz with 8-bit color although other modes
are available in Classic Mac OS. Unfortunately the original version of
XFree86 for Darwin or Update A crashes with 8-bit color. Update B or later
allows you to run X windows, with the following caveat: The display driver
for these PowerBooks doesn't currently allow setting the colormap. Unfortunately
the display driver doesn't correctly report this fact. Thus, you must apply
the following patch to run X server:
48c48
< #undef OLD_POWERBOOK_G3
---
> #define OLD_POWERBOOK_G3
With this patch applied, you can start the X server successfully, but you
must not specify any options for -size, -depth, or -refresh. Once started,
the X server is useable but the colors are not entirely correct. Future
upgrades to the IOFramebuffer service interface and/of to the display driver
for these PowerBooks should improve things. (Thanks to Edward Brown for
testing various updates and helping discover what was causing this problem.)
Keymapping
The original version of XFree86 for Darwin translated keyboard events from
Darwin to X window events by passing the character code plus an offset.
The device independent layer of XFree86 expects key codes on the other
hand. Key codes are numbers which represent, which key was pressed, while
character codes represent what character should be displayed on the screen.
So, for example, there is one key code for the "A" key and two character
codes, one for "A" and one for "a". The keyboard map translates between
The sequence shift-down, A-down, shift-up, a-up confuses the device independent
layer because it believes you have pushed and released different keys (A
and a) if you pass it character codes.
The way other versions of XFree86 handle this is to pass key codes rather
than character codes. The reason why key codes were not used previously
is that they are device dependent and the keyboard map has to be adjusted
for the hardware you are using. Update C queries Darwin for its keyboard
map and then translates this to an equivalent X window keyboard map.
If you have a problem with Update C that you don't see on earlier versions
of XFree86, then the X server may not be translating the keyboard map correctly.
To diagnose this problem, please send me a copy of the stderr output from
the X server as well as a dump of your Darwin keyboard map. By default
the X window keymap is dumped to stderr. (You can turn this off by undefining
DUMP_DARWIN_KEYMAP in darwin.c.) To dump the Darwin keymap, use the command
line tool dumpkeymap by Eric Sunshine. The source code for this useful
diagnostic tool is available here. To build
dumpkeymap, do the following:
cc -Wall -framework IOKit -I/System/Library/Frameworks/Kernel.framework/Headers
-o dumpkeymap dumpkeymap.cc
Outstanding Issues with the X server
-
The bell is broken.
-
Server shutdown problem: After quitting the X server the colored beachball
cursor reappears, but the screen never returns to the console display.
The console is accepting input however, so typing "logout" will return
you to the login prompt.
-
shmat() problem: The shmat() function fails in Xserver/Xext/xf86bigfont.c
because of error EMFILE. This presumably renders the BigFont extension
nonfunctional.
-
Screen saver not supported.
-
Mouse acceleration can not be adjusted.
-
Key repeat rate can not be adjusted.
Here is some documentation of general interest to Darwin developers. The documentation is in HeaderDoc form and can be seen as web pages or as a patch to relevant header file.
- IOGraphicsLib: If you are interested in how a winder server interacts with an IOFramebuffer service, this is a good reference. None of the acceleration functions are currently covered and there are some other missing bits, but it should be useful. (The header file patch is here.)
Copyright © 2000 Torrey T. Lyons.