<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN" [
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
]>

<article>
<title>README for XFree86 &relvers; on OpenBSD
<author>
Matthieu Herrb
<Date>Last modified on: 3 March 2000

<ident>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/OpenBSD.sgml,v 1.17 2001/04/05 19:29:43 dawes Exp $
</ident>

<toc>


<sect>What and Where is XFree86?

<p>
XFree86 is the Open Source port of X.Org's X11R6.4 release that supports
several UNIX(R) and UNIX-like (such as Linux, the BSDs and Solaris x86)
operating systems on Intel and other platforms.

See the <htmlurl url="COPYRIGHT.html" name="Copyright Notice">.

The sources for XFree86 &relvers; are available by anonymous ftp from:

<htmlurl name="ftp://ftp.XFree86.org/pub/XFree86/&relvers;"
url="ftp://ftp.XFree86.org/pub/XFree86/&relvers;">

Binaries for OpenBSD/i386 2.8 and later are available from:

<htmlurl name="ftp://ftp.XFree86.org/pub/XFree86/&relvers;/binaries/OpenBSD"
url="ftp://ftp.XFree86.org/pub/XFree86/&relvers;/binaries/OpenBSD">

A list of mirror sites is provided by
<htmlurl name="http://www.xfree86.org/MIRRORS.shtml"
url="http://www.xfree86.org/MIRRORS.shtml">

<p>

XFree86 also builds on other OpenBSD architectures. See section
<ref id="otherarch" name="Building on other architectures"> for details.


<sect>Bug Reports for This Document

<p>
Send email to <email>herrb@xfree86.org</email> (Matthieu Herrb) or
<email>XFree86@XFree86.org</email> if you have comments or suggestions about
this file and we'll revise it.

<sect>New OS dependent features
<p>
See the <htmlurl url="RELNOTES.html" name="Release Notes"> for
non-OS dependent new features in XFree86 &relvers;.

<sect1>New OS dependent features in 4.0.3
<p>
<itemize>
<item>Support for the wscons console driver in post 2.8 OpenBSD.
<item>A fix for multi-threaded libraries support. 
</itemize>

<sect1>New OS dependent features in 4.0.2
<p>
<itemize>
<item>Support for the OpenBSD ports tree, 
<item>Preliminary support for the powerpc architecture (clients build
and work, the server doesn't work yet),
<item>xdm now writes an utmp entry,
<item>startx now creates an Xauthority magic cookie for the display. 
</itemize>

<sect1>New OS dependent features in 4.0.1
<p>
<itemize>
<item>Several features from the OpenBSD X11 tree were merged into xdm:
<itemize>
<item> support for Kerberos IV authentication 
<item>use the arc4random(4) random number generator
<item>add a new resource "allowRootLogin", which can be used to disable
         root logins through xdm
<item>log failed logins to syslogd
<item>verify that the shell is valid using /etc/shell
<item>verify that the account hasn't expired
</itemize>
<item>The Xsun server can be built again on OpenBSD/sparc.
</itemize>

<sect1>New OS dependent features in 4.0
<p>
<itemize>
<item>Multi-thread safe libraries are built by default on OpenBSD 2.6
      and later,
<item>Preliminary APM support.
</itemize>

<sect1>New OS dependent features in 3.9.18
<p>
<itemize>
<item>Support for USB mices has been added on OpenBSD. 
<item>Soft-booting secondary cards through the int10 BIOS interface is 
now possible using the x86emu real mode emulator. 
</itemize>

<sect1>New OS dependent features in 3.9.17
<p>
<itemize>
<item><em>Silken mouse</em> is supported for serial mices, and, under
post 2.6 OpenBSD-current for PS/2 mices.
<item>MTRR Write Combining is enabled under post 2.6 OpenBSD-current. 
</itemize>

<sect>Installing the Binaries

<p>
Refer to the <htmlurl url="Install.html" name="Installation Document">
for detailed installation instructions.

<sect>Configuring X for Your Hardware
<p>
The <tt>/etc/X11/XF86Config</tt> file tells the X server what kind of
monitor, 
video card and mouse you have.  You <em/must/ create it to tell the
server what specific hardware you have.
<p>
You'll need info on your hardware:
<itemize>
<item>Your mouse type, baud rate and its /dev entry.
<item>The video card's chipset (e.g. ET4000, S3, etc).
<item>Your monitor's sync frequencies.
</itemize>

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


For details about the <tt/XF86Config/ file format, refer to the
<em>XF86Config(5)</em> manual page.

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

<sect1>About mouse configuration

<p>
XFree86 &relvers; has support for the mouse driver included in
the new <bf/wscons/ console driver introduced by OpenBSD-current after
2.8. Specify ``<tt/wsmouse/'' as the protocol and
``<tt>/dev/wsmouse0</tt>'' as the  device in <tt>/etc/X11/XF86Config</tt>
if you're using OpenBSD-current with a PS/2 mouse.
<p>
The OpenBSD pms driver  provides both ``raw'' and ``cooked''
(translated) modes.  ``raw'' mode does not do protocol translation, so
XFree86 would use the <bf>PS/2</bf> 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 <tt>/dev/psm0</tt>
device name.
<p>
See <htmlurl url="mouse.html" name="README.mouse">  for general
instruction on mouse configuration in XFree86.


<sect>Running X

<p>

<sect1>Starting xdm, the display manager

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

You can start xdm automatically on bootup by changing the line 
<tscreen><verb>
xdm_flags=NO            # for normal use: xdm_flags=""
</verb></tscreen>
to:
<tscreen><verb>
xdm_flags=""            # for normal use: xdm_flags=""
</verb></tscreen>
in <tt>/etc/rc.conf</tt>. 

<p>
Note that the binary distributions of XFree86 for OpenBSD on
ftp.xfree86.org and its mirrors don't include
support for the XDM-AUTHORIZATION-1 protocol, because of the US export 
rules. 

<sect1>Running X without the display manager
<p>
The easiest way for new users to start X windows is to type: ``<tt/startx
>&amp; startx.log/''.  Error messages are lost unless you redirect them
because the server takes over the screen.

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

<sect>Kernel Support for X

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

<tscreen>
 option XSERVER
 option APERTURE
</tscreen>

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

<p>
The pcvt console driver is the default in OpenBSD up to OpenBSD 2.8.
It offers several virtual consoles and international keyboard support.

<p>
OpenBSD-current after 2.8 has switched to the wscons console
driver. This console driver has a pcvt compatibility mode for X
support. 

<sect1>Aperture Driver
<p>
By default OpenBSD includes the BSD 4.4 kernel security
feature that disable access to the <tt>/dev/mem</tt> device when in
multi-users mode. But the XFree86 server require
linear access to the display memory in most cases.

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.
<p>
To enable the aperture driver, once included in the kernel, set
<tscreen><verb>
machdep.allowaperture=1     
</verb></tscreen>
in <tt>/etc/sysctl.conf</tt>.

Some drivers need a patch to the aperture driver in the kernel to work
correctly with int10 support. If you get warning from xf86ReadBIOS
like this one:
<tscreen><verb>
(II) checkDevMem: using aperture driver /dev/xf86
(WW) xf86ReadBIOS: /dev/mem mmap[s=600,a=0,o=0] failed (Invalid argument)
</verb></tscreen>
you should patch your kernel and rebuild it. Until it's integrated in
OpenBSD-current, or a better fix is found, the patch is available at 
<htmlurl
name="ftp://ftp.laas.fr/pub/ii/matthieu/OpenBSD/patch-kernel-xf4"
url="ftp://ftp.laas.fr/pub/ii/matthieu/OpenBSD/patch-kernel-xf4">.

I've also included it below, if you want to edit the source file by
hand. 

<tscreen><verb>
Index: sys/arch/i386/i386/mem.c
===================================================================
RCS file: /cvs/src/sys/arch/i386/i386/mem.c,v
retrieving revision 1.14
diff -u -r1.14 mem.c
--- sys/arch/i386/i386/mem.c	1999/11/20 11:11:28	1.14
+++ sys/arch/i386/i386/mem.c	2000/11/13 10:54:22
@@ -269,8 +269,8 @@
 /* minor device 4 is aperture driver */
 	case 4:
 		if (allowaperture &&
-		    (((off >= VGA_START && off <= BIOS_END) ||
-		    (unsigned)off > (unsigned)ctob(physmem))))
+		    (off <= BIOS_END || 
+		     (unsigned)off > (unsigned)ctob(physmem)))
 			return i386_btop(off);
 		else 
 			return -1;
</verb></tscreen>

<p>In post 2.8 OpenBSD-current, a modified version of this patch has
been integrated. You should set 
<tscreen><verb>machdep.allowaperture=2</verb></tscreen>
in <tt>/etc/sysctl.conf</tt> in order to achieve this. See the xf86(4)
manual page for details. 
<p>
Another (less recommended) way to enable linear memory and I/O ports
access is to disable the kernel security feature by adding ``option
INSECURE'' in your kernel configuration file and build a new kernel.
You will also need to comment out the line
initializing <tt/securelevel/ to 1 in <tt>/etc/rc.securelevel</tt>.
<p>
<quote>
<bf/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.
</quote>


<sect1>MIT-SHM
<p>
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:

<tscreen><verb>
 # System V-like IPC
 options         SYSVMSG
 options         SYSVSEM
 options         SYSVSHM
</verb></tscreen>
 
to your kernel config file. 

<sect> Rebuilding the XFree86 Distribution

<p>
The server developer's 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 <tt/xf86site.def/, type ``<tt>./mkmf</tt>'' and
``<tt/make/'' to link the server.  See <tt>/usr/X11R6/lib/Server/README</tt>
for more info.

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

<sect1>Console drivers<label id="console-drivers">

<p>
XFree86 has a configuration option to select the console
drivers to use in <tt/host.def/:
<itemize>
<item> if you're using pccons only put:
<tscreen><verb>
 #define XFree86ConsoleDefines -DPCCONS_SUPPORT
</verb></tscreen>
<item>if you're using pcvt only put:
<tscreen><verb>
 #define XFree86ConsoleDefines -DPCVT_SUPPORT
</verb></tscreen>
</itemize>
If you don't define <bf/XFree86ConsoleDefines/ in <tt/host.def/ the
pccons and pcvt drivers will be supported by default.

<p>
Experimental native support for the wscons console driver found on
OpenBSD/powerpc and on OpenBSD/i386 -current  can be built
by adding:
<tscreen><verb>
 #define XFree86ConsoleDefines -DWSCONS_SUPPORT
</verb></tscreen>
to <tt>xc/config/host.def</tt> before rebuilding the server. 
This has not been thoroughly tested, except on the macppc. 

For the i386, you should include both pcvt and wscons support in order
to use the pcvt compatibility mode of wscons:
<tscreen><verb>
 #define XFree86ConsoleDefines -DPCVT_SUPPORT -DWSCONS_SUPPORT
</verb></tscreen>


<sect1>Building on other architectures<label id="otherarch">

<p>
XFree86 should also compiles on other OpenBSD architectures. However,
please note that 3.9.x snapshots have only been tested on the i386 for 
now. 

<p> 
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 tree to rebuild from sources.  The OpenBSD X11
source tree is available by anoncvs from all OpenBSD anoncvs
servers. See <htmlurl url="http://www.openbsd.org/anoncvs.html"
name="http://www.openbsd.org/anoncvs.html"> for details on anoncvs.

<sect>Building New X Clients

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

<sect> Thanks
<p>
Many thanks to all people who contributed to make XFree86 work on
*BSD, in particular, <bf/David Dawes/,
<bf/Pace Willison/, <bf/Amancio Hasty/, <bf/Christoph Robitschko/,
<bf/Nate Williams/, <bf/Rod Grimes/, <bf/Jack Velte/ and <bf/Michael Smith/.

</article>
