








                         README for XFree86 on OpenBSD

                                Matthieu Herrb

                      Last modified on: 29 December 1998



1.  What and Where is XFree86?

XFree86 is a port of X11R6.3 that supports several versions of Intel-based
Unix.  It is derived from X386 1.2, which was the X server distributed with
X11R5.  This release consists of many new features and performance improvements
as well as many bug fixes.  The release is available as source patches against
the X Consortium X11R6.3 code, as well as binary distributions for many archi-
tectures.

See the Copyright Notice.

The sources for XFree86 are available by anonymous ftp from:

ftp://ftp.XFree86.org/pub/XFree86/current

Binaries for OpenBSD 2.4 and later are available from:

ftp://ftp.XFree86.org/pub/XFree86/current/binaries/OpenBSD

A list of mirror sites is provided by ftp://ftp.XFree86.org/pub/XFree86/MIRRORS

XFree86 also builds on other OpenBSD architectures. See section Building on
other architectures (section 8.2, page 6) for details.


2.  Bug Reports for This Document

Send email to matthieu@laas.fr (Matthieu Herrb) or XFree86@XFree86.org if you
have comments or suggestions about this file and we'll revise it.


3.  New features in this release

See the Release Notes for new features in XFree86.


4.  Installing the Binaries

Refer to section 5 of the Release Notes  for detailed installation instruc-
tions.






README for XFree86 on OpenBSD                                                 1





README for XFree86 on OpenBSD                                                 2



5.  Configuring X for Your Hardware

The /etc/XF86Config file tells the X server what kind of monitor, video card
and mouse you have.  You must create it to tell the server what specific hard-
ware you have.

The easiest way to create this file is to run the XF86Setup utility as root.
Refer to QuickStart.doc for details about its use.

You'll need info on your hardware:

   o Your mouse type, baud rate and its /dev entry.

   o The video card's chipset (e.g. ET4000, S3, etc).

   o Your monitor's sync frequencies.

The recommended way to generate an XF86Config file is to use the XF86Setup
utility.  The xf86config text utility is still there for the (few) cases where
XF86Setup can't be used. Also, there is a sample file installed as
/usr/X11R6/lib/X11/XF86Config.eg, which can be used as a starting point.

For details about the XF86Config file format, refer to the XF86Config(5) manual
page.

Once you've set up a XF86Config file, you can fine tune the video modes with
the xvidtune utility.

5.1  About mouse configuration

If your serial mouse does not work try using kermit or tip to connect to the
mouse serial port and verify that it does indeed generate characters.

The OpenBSD pms driver  provides both ``raw'' and ``cooked'' (translated)
modes.  ``raw'' mode does not do protocol translation, so XFree86 would use the
PS/2 protocol for talking to the device in that mode.  ``Cooked'' mode is the
old BusMouse translation.  The driver runs in ``raw'' mode when using the
/dev/psm0 device name.

On OpenBSD 2.2, only standard PS/2 mice are supported by this driver.

On OpenBSD 2.3 and later include there is support for recent PS/2 mice that
send more than three bytes at a time (especially intellimouse, or mouseman+
with a "3D" roller).

See README.mouse  for general instruction on mouse configuration in XFree86.

5.2  Other input devices

XFree86  supports the dynamic loading of drivers for external input devices
using the XInput extension. Currently supported devices are:

   o Joystick (xf86Jstk.so)









README for XFree86 on OpenBSD                                                 3



   o Wacom tablets (Wacom IV protocol only, xf86Wacom.so)

   o SummaSketch tablets (xf86Summa.so)

   o Elographics touchscreen (xf86Elo.so)

To use a specific device, add the line

     load "module"


in the Module section of XF86Config, where module is the name of the .so file
corresponding to your device.  You also need to set up a XInput section in
XF86Config.  Refer to the XF86Config(5) man page for detailed configuration
instructions.

You can then change the device used to drive the X pointer with the xset-
pointer(1) command.

For joystick support, you'll need to enable the joystick device driver in the
kernel.  See joy(4) for details.

5.3  Configuring PEX and XIE extensions

The PEX and XIE extensions are  supported as external modules.  If you want to
have access to these extensions, add the following lines to the Module section
of XF86Config:

        load    "pex5.so"
        load    "xie.so"


6.  Running X

8mb of memory is a recommended minimum for running X.  The server, window man-
ager and an xterm take about 4 Mb of memory themselves.  On a 4Mb system that
would leave nothing left over for other applications like gcc that expect a few
meg free.  X will work with 4Mb of memory, but in practice compilation while
running X can take 5 or 10 times as long due to constant paging.

6.1  Starting xdm, the display manager

To start the display manager, log in as root on the console and type: ``xdm
-nodaemon''.

You can start xdm automatically on bootup un-commenting the following code in
/etc/rc.local:

       if [ -x /usr/X11R6/bin/xdm ]; then
         echo -n ' xdm'; /usr/X11R6/bin/xdm
       fi

On the default OpenBSD 2.2 installation, you will need to create the virtual
console device for the X server:








README for XFree86 on OpenBSD                                                 4



     cd /dev
      ./MAKEDEV ttyC5

Note that the binary distributions of XFree86 for OpenBSD don't include support
for the XDM-AUTHORIZATION-1 protocol.

6.2  Running X without the display manager

The easiest way for new users to start X windows is to type: ``startx >&
startx.log''.  Error messages are lost unless you redirect them because the
server takes over the screen.

To get out of X windows, type: ``exit'' in the console xterm.  You can cus-
tomize your X by creating .xinitrc, .xserverrc, and .twmrc files in your home
directory as described in the xinit and startx man pages.


7.  Kernel Support for X

To make sure X support is enabled under  OpenBSD, the following line must be in
your config file in /sys/arch/i386/conf:

     options XSERVER

7.1  Console drivers

The server supports the two standard  OpenBSD/i386 console drivers: pccons and
pcvt. They are detected at runtime and no configuration of the server itself is
required.

The pcvt console driver is the default in OpenBSD.  It offers several virtual
consoles and international keyboard support.

7.2  Aperture Driver

By default OpenBSD includes the BSD 4.4 kernel security feature that disable
access to the /dev/mem device when in multi-users mode. But XFree86 servers can
take advantage (or require) linear access to the display memory.

The P9000, Mach64 and AGX servers require linear memory access, other acceler-
ated servers can take advantage of it, but do not require it.  Some drivers in
the SVGA server require linear memory access too, notably the Matrox driver.

The preferred  way to allow XFree86 to access linear memory is to use the aper-
ture driver

Ths step is highly dependent from your exact operating system version:

   o  OpenBSD 2.0

     Use the aperture driver from /usr/lkm:

     add the following lines to the end of /etc/rc.local:









README for XFree86 on OpenBSD                                                 5



           KERNDIR=/usr/lkm
           if [ -f ${KERNDIR}/ap.o ]; then
             modload -o ${KERNDIR}/ap -e ap -p \
             ${KERNDIR}/apinstall ${KERNDIR}/ap.o
           fi



   o  OpenBSD 2.1, 2.2

     Uncomment the lines loading the aperture driver from /etc/rc.securelevel

   o  OpenBSD 2.3

     The aperture driver is part of the kernel.  Add 'option APERTURE' to your
     kernel configuration file, build and install the new kernel and run
     ./MAKEDEV std in /dev. Edit /etc/sysctl.conf to set the variable
     machdep.allowaperture to 1.

   o  OpenBSD 2.4 and later

     OpenBSD now requires the aperture driver to be enabled for all X servers,
     because the aperture driver also controls access to the I/O ports of the
     video boards.

After doing that, reboot your system. XFree86 will auto-detect the aperture
driver if available.

Warning: if you boot another kernel than /bsd, loadable kernel modules can
crash your system. Always boot in single user mode when you want to run another
kernel.

     Caveat: the aperture driver only allows one access at a time (so that
     the system is in the same security state once X is launched). This
     means that if you run multiple servers on multiples VT, only the
     first one will have linear memory access.  Use 'option INSECURE' if
     you need more that one X server at a time.

Another (less recommended) way to enable linear memory access is to disable the
kernel security feature by adding ``option INSECURE'' in your kernel configura-
tion file and build a new kernel.  In OpenBSD 2.2 and later, you will also need
to comment out the line initializing securelevel to 1 in /etc/rc.securelevel.

7.3  MIT-SHM

OpenBSD supports System V shared memory. If XFree86 detects this support in
your kernel, it will support the MIT-SHM extension.

To add support for system V shared memory to your kernel add the lines:

      # System V-like IPC
      options         SYSVMSG
      options         SYSVSEM
      options         SYSVSHM








README for XFree86 on OpenBSD                                                 6



to your kernel config file.


8.  Rebuilding the XFree86 Distribution

The server link kit allow you to rebuild just the X server with a minimum
amount of disk space.  Just unpack it, make the appropriate changes to the
xf86site.def, type ``./mkmf'' and ``make'' to link the server.  See
/usr/X11R6/lib/Server/README for more info.

See INSTALL for instructions on unbundling and building the source distribu-
tion.

You should configure the distribution by editing xc/config/cf/host.def  before
compiling.  To compile the sources, invoke ``make World'' in the xc directory.

8.1  Console drivers

XFree86 has a configuration option to select the console drivers to use in
xf86site.def:

   o  if you're using pccons only put:

           #define XFree86ConsoleDefines -DPCCONS_SUPPORT

   o if you're using pcvt only put:

           #define XFree86ConsoleDefines -DPCVT_SUPPORT


If you don't define XFree86ConsoleDefines in xf86site.def the pccons and pcvt
drivers will be supported.

8.2  Building on other architectures

XFree86 also compiles on other OpenBSD architectures.

The XFree86 servers can also been built on OpenBSD/mips. The S3 server has been
tested on an Acer Mips system with a S3/928 board. Contact Per Fogelstrom
(pefo@OpenBSD.org) for details.

The Xsun server patches from Dennis Ferguson and Matthew Green for NetBSD have
been integrated in xc/programs/Xserver/hw/sun. The Xsun server can be built on
the sparc and the sun3.

The client side of XFree86 also builds on the alpha, pmax, amiga, mac68k and
mvme68k architectures.

Problems with this port should be reported directly to the OpenBSD mailing
lists rather than to the xfree86 mailing list.


Note that OpenBSD project has now its own source tree, based on the XFree86
source tree, with some local modifications. You may want to start with this








README for XFree86 on OpenBSD                                                 7



tree to rebuild from sources.  The OpenBSD X11 source tree is available by
anoncvs from all OpenBSD anoncvs servers. See http://www.openbsd.org/anon-
cvs.html for details on anoncvs.


9.  Building New X Clients

The easiest way to build a new client (X application) is to use xmkmf if an
Imakefile is included in the sources.  Type ``xmkmf -a'' to create the Make-
files, check the configuration if necessary and type ``make''.  Whenever you
install additional man pages you should update whatis.db by running ``make-
whatis /usr/X11R6/man''.

     Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/OpenBSD.sgml,v 1.1.2.9 1999/01/05 07:15:47 hohndel Exp $





     $XConsortium$










































README for XFree86 on OpenBSD                                                 8





































































                                   CONTENTS



1. What and Where is XFree86? ............................................... 1

2. Bug Reports for This Document ............................................ 1

3. New features in this release ............................................. 1

4. Installing the Binaries .................................................. 1

5. Configuring X for Your Hardware .......................................... 2
   5.1 About mouse configuration ............................................ 2
   5.2 Other input devices .................................................. 2
   5.3 Configuring PEX and XIE extensions ................................... 3

6. Running X ................................................................ 3
   6.1 Starting xdm, the display manager .................................... 3
   6.2 Running X without the display manager ................................ 4

7. Kernel Support for X ..................................................... 4
   7.1 Console drivers ...................................................... 4
   7.2 Aperture Driver ...................................................... 4
   7.3 MIT-SHM .............................................................. 5

8. Rebuilding the XFree86 Distribution ...................................... 6
   8.1 Console drivers ...................................................... 6
   8.2 Building on other architectures ...................................... 6

9. Building New X Clients ................................................... 7

























                                       i


