path: root/xc/programs/Xserver/hw/xfree86/doc/sgml/NetBSD.sgml

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

<article>
<title>README for XFree86 &relvers; on NetBSD
<author>Rich  Murphey,
David Dawes,
Marc  Wandschneider,
Mark  Weaver,
Matthieu Herrb
<Date>Last modified on: 20 February 2000

<ident>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/NetBSD.sgml,v 3.52 2000/02/21 18:05:47 dawes Exp $
</ident>
<toc>


<sect>What and Where is XFree86?

<p>
XFree86 is a port of X11R6.4 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.  

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

The sources for XFree86 are available by anonymous ftp from:

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

Binaries for NetBSD 1.3 and later are available from:
<htmlurl name="ftp://ftp.XFree86.org/pub/XFree86/snapshots/&relvers;/binaries/NetBSD"
url="ftp://ftp.XFree86.org/pub/XFree86/snapshots/&relvers;/NetBSD">


A list of mirror sites is provided by
<htmlurl name="ftp://ftp.XFree86.org/pub/XFree86/MIRRORS"
url="ftp://ftp.XFree86.org/pub/XFree86/MIRRORS">


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

XFree86 also supports NetBSD on PC98 machines. 


<sect>Bug Reports for This Document

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

<sect>New OS dependant 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 3.9.18
<p>
<itemize>
<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>Support for <em>silken mouse</em> with the wsmouse protocol has
been added.
<item>A new version of the XFree86 Aperture driver which provides MTRR 
support is included.
</itemize>


<sect>Installing the Binaries

<p>
Refer to section 5 of the <htmlurl url="RELNOTES.html" name="Release
Notes">  for detailed installation instructions.

<sect>Configuring X for Your Hardware

<p>
The <tt>/etc/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/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 <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>
The NetBSD pms mouse driver handles PS/2 style mice as
Busmouse. Specify the protocol as ``<bf/busmouse/'' in the mouse
section of your 
<tt/XF86Config/ file if you're using a PS/2 mouse.
<p>
Only standard PS/2 mice are supported by this driver. Newest PS/2
mice that send more than three bytes at a time (especially
Intellimouse, or MouseMan+ with a ``3D'' roller) are not supported yet. 
<p>
XFree86 &relvers; also has support for the mouse driver included in
the new <bf/wscons/ console driver introduced by NetBSD 1.4. Specify
``<tt/wsmouse/'' as the protocol and ``<tt>/dev/wsmouse0</tt>'' as the 
device in <tt>/etc/XF86Config</tt> if you're using NetBSD 1.4 with
wscons. 
<p>
See <htmlurl url="mouse.html" name="README.mouse">  for general
instruction on mouse configuration in XFree86.

<sect>Running X

<p>
The easiest way for new users to start X windows is to type: 
<tscreen><verb>
startx >& startx.log
</verb></tscreen> 
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.

<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=NO			xdm_flags=""            # x11 display manager
</verb></tscreen>
to:
<tscreen><verb>
xdm=YES			xdm_flags=""            # x11 display manager
</verb></tscreen>
in <tt>/etc/rc.conf</tt>. 

<p>
Under NetBSD 1.4 with the wscons console driver, you must enable a
virtual console for the X server first. To do this follow these steps:
<itemize>
<item>Make sure the device file exists. If not, ``<tt>cd /dev ;
./MAKEDEV wscons</tt>''. 
<item>Next, make sure your kernel wants to do wscons. (see <ref
id="wscons" name="below">).
<item>Next, make sure ``<tt>wscons=YES</tt>'' in
<tt>/etc/rc.conf</tt>.
<item>Next, make sure <tt>/etc/wscons.conf</tt> exists. The relevant
bits:
<tscreen><verb>
#screen	0	-	vt100
screen	1	-	vt100
screen	2	-	vt100
screen	3	-	vt100
screen	4	-	-
screen	5	-	vt100
</verb></tscreen>
</itemize>
(Thanks to Mason Loring Bliss <tt>&lt;mason@acheron.middleboro.ma.us&gt;</tt> for
this explanation)
<p>
Note that the binary distributions of XFree86 for NetBSD don't include
support for the XDM-AUTHORIZATION-1 protocol. 

<sect>Kernel Support for X

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

<tscreen>
 options XSERVER, UCONSOLE
</tscreen>

<sect1>Console drivers

<p>
The server supports the standard NetBSD/i386
console drivers: pccons, pcvt and wscons (in pcvt compatibility
mode). They are detected at runtime and no 
configuration of the server itself is required.

<p>
The pccons driver is the most widely tested and is the console driver
contained in the NetBSD binary distribution's kernels.

<p>
The pcvt console driver is bundled with NetBSD. The pcvt X
mode is compatible with the pccons driver X mode. It offers several
virtual consoles and international keyboard support. In order to use
this driver, change the line:

<tscreen>
 device          pc0     at isa? port "IO_KBD" irq 1
</tscreen>

to

<tscreen>
 device         vt0     at isa? port "IO_KBD" irq 1
</tscreen>

in your kernel config file, and rebuild and install your kernel.

<p>
<label id="wscons">
XFree86 will also run with the wscons console driver in
NetBSD 1.4. For now, it uses the pcvt compatibility mode, so be
sure to have the lines:
<tscreen><verb>
options         WSDISPLAY_COMPAT_PCVT           # emulate some ioctls
options         WSDISPLAY_COMPAT_SYSCONS        # emulate some ioctls
options         WSDISPLAY_COMPAT_USL		# VT handling
options         WSDISPLAY_COMPAT_RAWKBD         # can get raw scancodes
</verb></tscreen>
in your kernel configuration file if you're using wscons. Refer to the 
<em>wscons(4)</em> and <em>wsmouse(4)</em> manual pages for
informations on how to configure wscons into the kernel.

<sect1>Aperture Driver
<p>
By default NetBSD include the BSD 4.4 kernel security
feature that disable access to the <tt>/dev/mem</tt> device when in
multi-users mode. But XFree86 servers can take advantage (or require)
linear access to the display memory.

Most XFree86 &relvers; card drivers require linear memory access.
There are two ways to allow XFree86 to access linear memory:

The first way is to disable the kernel security feature by adding
``<tt/option INSECURE/'' in the kernel configuration file and build a new
kernel.


The second way is to install the aperture driver, included in source form in
<tt>xc/programs/Xserver/hw/xfree86/etc/apNetBSD.shar</tt> in the
XFree86 &relvers; source distribution. Unpack it in a new directory of your 
choice by running:
<tscreen><verb>
  sh apNetBSD.shar
</verb></tscreen>
By default the aperture driver will be installed in
<tt>/usr/local/aperture</tt>. You can change this default directory by 
editing <tt/Makefile.inc/ before building it. 

Then run ``<tt>make build</tt>'' as root to install it. To enable it, 
add the following line to  <tt>/etc/lkm.conf</tt>:
<tscreen><verb>
/usr/local/aperture/lkm/xf86.o  -  - /usr/local/aperture/lkm/xf86_mod_install - -
</verb></tscreen> 
and set ``<tt/lkm=YES/'' in <tt>/etc/rc.conf</tt>

Reboot your system. XFree86 will auto-detect the aperture
driver if available.

<bf/Warning 1:/ if you boot another kernel than <tt>/netbsd</tt>,
loadable kernel modules can crash your system. Always boot in
single user mode when you want to run another kernel.

<p>
<bf/Warning 2:/ 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.

<p>
Starting with XFree86 3.9.17, the XFree86 aperture driver
also supports MTRR write combining on Pentiums II
and AMD K6 class processors. 

<sect1>MIT-SHM
<p>
NetBSD 1.0 and later 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>
See <htmlurl url="INSTALL.html" name="INSTALL"> for instructions on
unbundling and building the source distribution.

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>Aperture driver
<p>
To build the XFree86 server with the Aperture driver enabled, you
should unpack <tt>apNetBSD.shar</tt> and install it first. 

Then edit <tt>xc/config/cf/host.def</tt> and add the line
<tscreen><verb>
#define HasNetBSDApertureDriver    YES
</verb></tscreen>
to it.

And finally run <tt/make World/ in the <tt/xc/ directory. 

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

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

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

<p> 
Note that the NetBSD 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 NetBSD xsrc source tree is available at: 
<htmlurl url="ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/xsrc/"
name="ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/xsrc/">

<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>''.


When porting clients to *BSD
systems, make use of the symbol <bf/BSD/ for code which is truly
BSD-specific.  The value of the symbol can be used to distinguish
different BSD releases.  For example, code specific to the Net-2 and
later releases can use:

<tscreen>                   
#if (BSD >= 199103)
</tscreen>

To ensure that this symbol is correctly defined, include
<tt>&lt;sys/param.h&gt;</tt> in the source that requires it.  Note that
the symbol <bf/CSRG_BASED/ is defined for *BSD systems in XFree86 3.1.1
and later.  This should be used to protect the inclusion of
<tt>&lt;sys/param.h&gt;</tt>.

For code that really is specific to a particular i386 BSD port, use
<bf/__FreeBSD__/ for FreeBSD, <bf/__NetBSD__/ for NetBSD,
<bf/__OpenBSD__/ for OpenBSD,
and <bf/__bsdi__/ for BSD/386.


<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>