<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN">

<article>
<title> README for XFree86 on FreeBSD
<author>Rich Murphey, David Dawes
<date>25 Feb 1998

<toc>
 
<sect>What and Where is XFree86?

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

For further details about this beta release, please refer to the
<htmlurl name="Release Notes" url="RELNOTES.html">.

<!--
The release
is available as source patches against the X Consortium X11R6.1 code, as
well as binary distributions for many architectures.
-->

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/current"
url="ftp://ftp.XFree86.org/pub/XFree86/current">
-->

Binaries for XFree86 on FreeBSD 2.1.x, 2.2.x and 3.0-current are available from:

<htmlurl name="ftp://ftp.XFree86.org/pub/XFree86/beta/"
url="ftp://ftp.XFree86.org/pub/XFree86/beta/">
<p>
<!--
<htmlurl name="ftp://XFree86.cdrom.com/pub/XFree86/beta"
url="ftp://XFree86.cdrom.com/pub/XFree86/beta">
-->

Send email to <em/Rich-Murphey@Rice.edu/ or <em/XFree86@XFree86.org/
if you have comments or suggestions about this file and we'll revise
it.


<sect>Installing the Binaries
<p>
If you want to save space, first select which archives you want to
unpack.  If you can't decide what to pick and you have 52Mb of disk
space, it's safe to unpack everything.

At a minimum you need to unpack the 'required' <tt/X332*.tgz/
archives plus at least one server that matches your vga card.  You'll
need 13Mb for the minimum required run-time binaries only.

<descrip>
<tag/Required:/

<descrip>
<tag/X332bin.tgz/
     all the executable X client applications and shared libs

<tag/X332fnts.tgz/
     the misc, 75 dpi and PEX fonts

<tag/X332lib.tgz/
     data files needed at runtime
</descrip>

<tag/Required unless you have already customized your configuration files:

<descrip>
<tag/X332cfg.tgz/
     customizable xinit and xdm runtime configuration files
</descrip>

<tag/Choose at least one server:/

<descrip>
<tag/X3328514.tgz/
     8-bit color for IBM 8514 and true compatibles.

<tag/X332AGX.tgz/
     8 and 16-bit color for AGX and XGA boards.

<tag/X332I128.tgz/
     8 and 16-bit color for I128 boards.

<tag/X332Ma32.tgz/
     8 and 16-bit color for ATI Mach32 boards.

<tag/X332Ma64.tgz/
     8, 16 and 32-bit color for ATI Mach64 boards.

<tag/X332Ma8.tgz/
     8-bit color for ATI Mach8 boards.

<tag/X332Mono.tgz/
     1-bit monochrome for VGA, Super-VGA, Hercules, and others.

<tag/X332P9K.tgz/
     8, 16, and 32-bit color for Weitek P9000 boards (Diamond Viper).

<tag/X332S3.tgz/
     8, 16 and 32-bit color for S3 boards.

<tag/X332S3V.tgz/
     8 and 16-bit color for S3 ViRGE boards.

<tag/X332SVGA.tgz/
     &gt;=8-bit color for Super-VGA cards.

<tag/X332VG16.tgz/
     4-bit color for VGA and Super-VGA cards

<tag/X332W32.tgz/
     8-bit Color for ET4000/W32, /W32i, /W32p and ET6000 cards.

<tag/X3329GAN.tgz/
     8-bit color for PC98 GA-98NB/WAP boards

<tag/X3329480.tgz/
     8-bit color for PC98 PEGC

<tag/X3329NKV.tgz/
     8-bit color for PC98 NEC-CIRRUS/EPSON NKV/NKV2 boards

<tag/X3329WBS.tgz/
     8-bit color for PC98 WAB-S boards

<tag/X3329WEP.tgz/
     8-bit color for PC98 WAB-EP boards

<tag/X3329WSN.tgz/
     8-bit color for PC98 WSN-A2F boards

<tag/X3329EGC.tgz/
     4-bit color for PC98 EGC

<tag/X3329TGU.tgz/
     8 and 16-bit color for PC98 Trident Cyber9320/968x boards

<tag/X3329MGA.tgz/
     &gt;=8-bit color for PC98 Millennium/Mystique cards.

<tag/X3329SVG.tgz/
     8-bit color for PC98 Cirrus755x boards

<tag/X3329NS3.tgz/
     8 and 16-bit color for PC98 NEC S3 boards

<tag/X3329SPW.tgz/
     8 and 16-bit color for PC98 S3 PW/PCSKB boards

<tag/X3329LPW.tgz/
     8 and 16-bit color for PC98 S3 PW/LB boards

<tag/X3329GA9.tgz/
     8, 16 and 32-bit color for PC98 S3 GA-968 boards

<tag/X332nest.tgz/
     A nested server running as a client window on another display.
</descrip>

<tag/Optional:/

<descrip>

<tag/X332doc.tgz/
     READMEs

<tag/X332ps.tgz/
     READMEs in PostScript

<tag/X332html.tgz/
     READMEs in HTML

<tag/X332man.tgz/
     man pages

<tag/X332f100.tgz/
     100dpi fonts

<tag/X332fscl.tgz/
     Speedo and Type1 fonts

<tag/X332fnon.tgz/
     Japanese, Chinese and other non-english fonts

<tag/X332fcyr.tgz/
     Cyrillic fonts

<tag/X332fsrv.tgz/
     the font server and its man page

<tag/X332prog.tgz/
     config, lib*.a and *.h files needed only for compiling

<!--
<tag/X332lkit.tgz/
     (10.8Mb) X server reconfiguration kit

<tag/X332lk98.tgz/
     (14.2Mb) X server reconfiguration kit for PC98 X servers

-->
</descrip>
</descrip>

<sect1>Full Install:
<p>
<enum>
<item> You must be logged in as root to unpack the archives because
     several executables are set-user-id.  Otherwise the server may
     abort if you unpack it as an ordinary user.  You must also use a
     ``<tt/umask/'' value of <tt/022/ because the X server requires
     special permissions.
<tscreen><verb>
 % su
 # umask 022
</verb></tscreen>

<item>If you have 52Mb free in the <tt>/usr</tt> partition ``<tt>cd
     /usr</tt>'' and skip to no. 4.
     Otherwise, create a directory on another partition and sym link it into
     <tt>/usr</tt>:

<tscreen><verb>
 # cd /usr/local
 # mkdir X11R6
 # ln -s /usr/local/X11R6 /usr/X11R6
</verb></tscreen>

<item>Run the preinst.sh script
<tscreen><verb>
 # cd /usr/X11R6
 # sh preinst.sh
</verb></tscreen>

<item>Unpack everything:

     If you are using sh (as root usually does):

<tscreen><verb>
 # for i in X332*.tgz; do
 #   tar -x -z --unlink -f $i
 # done
</verb></tscreen>

     Else, if you are using csh:
<tscreen><verb>
 % foreach i (X332*.tgz)
 %   tar -x -z --unlink -f $i
 % end
</verb></tscreen>

<item>Create a symbolic link ``<tt/X/'' that points to the server
     that matches your video card.  The <em/XF86_*/ man pages list which
     vga chip sets are supported by each server.  For example, if you
     have an ET4000 based card you will use the XF86_SVGA server:

<tscreen><verb>
 # cd /usr/X11R6/bin; rm X; ln -s XF86_SVGA X
</verb></tscreen>
</enum>

<sect1>Minimal Install:
<p>
First do numbers 1, 2 and 4 above. Then unpack the required archives:

<tscreen><verb>
 # for i in bin fnts lib xicf; do
 #   tar -x -z --unlink -f  X332$i.tgz
 # done
</verb></tscreen>

Then unpack a server archive corresponding to your vga card.  The
server man pages, <tt>X11R6/man/man1/XF86_*</tt>, list the vga chip
sets supported by each server.  For example, if you have an ET4000
based card you will use the XF86_SVGA server:

<tscreen><verb>
 # tar -x -z --unlink -f X332SVGA.tgz
 # cd /usr/X11R6/bin; rm X; ln -s XF86_SVGA X
</verb></tscreen>

<sect1>After either Full or Minimal Install above:
<p>
Add /usr/X11R6/bin to the default path for sh in <tt>/etc/profile</tt>
and for csh in <tt>/etc/csh.login</tt> if they are not already there:

<tscreen><verb>
 # echo 'set path = ($path /usr/X11R6/bin)' >>/etc/csh.login
 # echo 'PATH=$PATH:/usr/X11R6/bin' >>/etc/profile
</verb></tscreen>

Or make sure all who use X put <tt>/usr/X11R6/bin</tt> in their
shell's ``path'' variable.

Next either reboot or invoke <tt/ldconfig/ as root to put the shared
libraries in <tt/ld.so/'s cache:

<tscreen><verb>
 # ldconfig /usr/lib /usr/local/lib /usr/X11R6/lib
</verb></tscreen>

If you had already configured <tt>X11R6/lib/X11/xinit/xinitrc</tt> or
<tt>X11R6/lib/X11/xdm/*</tt> omit the <tt/xinit-config/ or
<tt/xdm-config/ archive or unpack it separately and merge in your
customizations.

The <tt/fscl/ and <tt/f100/ archives are optional and
can be omitted if you are short on space.  The optional <tt/link/
archive allows you to reconfigure and customize a X server binary.
The optional <tt/prog/ archive is needed only for writing or compiling X
applications.  The optional <tt/pex/ archive contains pex clients and
libraries for building 3D graphics applications.

<quote>
<bf/NOTE:/ You don't need to uncompress the font files, but if you
uncompress them anyway you must run <tt/mkfontdir/ in the corresponding
font directory; otherwise your server will abort with the message
``<tt/could not open default font 'fixed'/''.
</quote>


<sect>Installing The Display Manager (xdm)
<p>
The display manager makes your PC look like an X terminal.  That is, it
presents you with a login screen that runs under X.

The easiest way to automatically start the display manager on boot is to
add a line in <tt>/etc/ttys</tt> to start it on one of the unoccupied
virtual terminals:

<tscreen><verb>
 ttyv4	"/usr/X11R6/bin/xdm -nodaemon" xterm	on secure
</verb></tscreen>

You should also make sure that <tt>/usr/X11R6/bin/X</tt> is a symbolic
link to the Xserver that matches your video card or edit the file
Xservers in <tt>/usr/X11R6/lib/X11/xdm</tt> to specify the pathname of
the X server.

The change to <tt>/etc/ttys</tt> won't take effect until you either
reboot or ``<tt/kill -HUP 1/'' to force initd to reread
<tt>/etc/ttys</tt>.  You can also test the display manager manually by
loging in as root on the console and typing ``<tt/xdm -nodaemon/''.

 
<sect>Configuring X for Your Hardware
<p>
The <tt/XF86Config/ 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.

It is strongly recommended that you use either the `XF86Setup' utility
(which requires the VGA16 server to be installed), or the `xf86config'
utility to generate an XF86Config file.

In order to protect your hardware from damage, the server no longer
will read <tt/XF86Config/ files from a user's home directory, but
requires that it be in <tt>/etc/XF86Config</tt>,
<tt>/usr/X11R6/lib/X11/XF86Config.</tt><em>hostname</em> or
<tt>/usr/X11R6/lib/X11/XF86Config</tt>.

You'll need info on your hardware:

<itemize>
<item>Your mouse type, baud rate and its <tt>/dev</tt> entry.
<item>The video card's chipset (e.g. ET4000, S3, etc).
<item>Your monitor's sync frequencies.
</itemize>

If you plan to fine tune the screen size or position on your monitor you'll
need the specs for sync frequencies from your monitor's manual.

When you run the `XF86Setup' utility, do NOT touch the mouse until
you are finished with mouse set up.
Otherwise, the VGA16 server and the mouse device driver may get
confused and you may experience mouse and/or keyboard input problems.

If you are running ``<tt/moused/'' (see the man page for <tt/moused(8)/)
in FreeBSD versions 2.2.1 or later,
you MUST specify <tt>SysMouse</tt> as the mouse protocol type 
and <tt>/dev/sysmouse</tt> as the mouse device name,
regardless of the brand and model of your mouse.

If you are NOT running ``<tt/moused/'', you need to know the interface
type of your mouse, <tt>/dev</tt> entry and the protocol type to use.

The interface type can be determined by looking at the connector 
of the mouse.
The serial mouse has a D-Sub female 9- or 25-pin connector.
The bus mouse has either a D-Sub male 9-pin connector 
or a round DIN 9-pin connector.
The PS/2 mouse is equipped with a small, round DIN 6-pin connector.
Some mice come with adapters with which the connector can 
be converted to another.  If you are to use such an adapter,
remember the connector at the very end of the mouse/adapter pair is 
what matters.

The next thing to decide is a <tt>/dev</tt> entry for the given interface.
For the bus and PS/2 mice, there is little choice: 
the bus mouse always use <tt>/dev/mse0</tt>,
and the PS/2 mouse is always at <tt>/dev/psm0</tt>.
There may be more than one serial port to which the serial
mouse can be attached.  Many people often assign the first, built-in 
serial port <tt>/dev/cuaa0</tt> to the mouse.

If you are not sure which serial device your mouse is plugged into, 
the easiest way to find out the device is to
use ``<tt/cat/'' or ``<tt/kermit/'' to look at the output of the
mouse.  Connect to it and just make sure that it generates output when
the mouse is moved or clicked:

<tscreen><verb>
 % cat < /dev/tty00
</verb></tscreen>

If you can't find the right mouse device then use ``<tt/dmesg|grep
sio/'' to get a list of serial devices that were detected upon booting:

<tscreen><verb>
 % dmesg|grep sio
 sio0 at 0x3f8-0x3ff irq 4 on isa
</verb></tscreen>

Then double check the <tt>/dev</tt> entries corresponding to these
devices.  Use the script <tt>/dev/MAKEDEV</tt> to create entries if
they don't already exist:

<tscreen><verb>
 % cd /dev
 % sh MAKEDEV tty00
</verb></tscreen>

You may want to create a symbolic link <tt>/dev/mouse</tt>
pointing to the real port to which the mouse is connected, so that you
can easily distinguish which is your ``mouse'' port later.

The next step is to guess the appropriate protocol type for the mouse.
In FreeBSD 2.2.6 or later, the X server may be able to automatically 
determine the appropriate protocol type, unless your mouse is of a
relatively old model.
Use the ``<tt/Auto/'' protocol in these versions.

In other versions of FreeBSD or if the ``<tt/Auto/'' protocol
doesn't work in 2.2.6, you have to guess a protocol type and try.

There is rule of thumb:

<enum>
<item>The bus mice always use the ``<tt>BusMouse</tt>''
protocol regardless of the brand of the mouse.
<item>The ``<tt>PS/2</tt>'' protocol should always be specified for 
the PS/2 mouse regardless of the brand of the mouse.
<quote>
<bf/NOTE:/ There are quite a few PS/2 mouse protocols listed in the man page
for <tt>XF86Config</tt>.  But, ``<tt>PS/2</tt>'' is the only PS/2 mouse 
protocol type useful in <tt>XF86Config</tt> for FreeBSD.
The other PS/2 mouse protocol types are not supported in FreeBSD.
FreeBSD version 2.2.6 and later directly support 
these protocol types in the PS/2 mouse driver <tt/psm/ and it is not
necessary to tell the X server which PS/2 mouse protocol type is to 
be used; ``<tt/Auto/'' should work, otherwise use ``<tt>PS/2</tt>''.
</quote>
<item>The ``<tt>Logitech</tt>'' protocol is for old mouse models 
from Logitech.
Modern Logitech mice use either the ``<tt>MouseMan</tt>''
or ``<tt>Microsoft</tt>'' protocol.
<item>Most 2-button serial mice support the ``<tt>Microsoft</tt>'' protocol.
<item>3-button serial mice may work with the ``<tt>MouseSystems</tt>''
protocol. If it doesn't, it may work with the ``<tt>Microsoft</tt>''
protocol although the third (middle) button won't function.
3-button serial mice may also work with the ``<tt>MouseMan</tt>''
protocol under which the third button may function as expected.
<item>3-button serial mice may have a small switch to choose between ``MS''
and ``PC'', or ``2'' and ``3''.
``MS'' or ``2'' usually mean the ``<tt>Microsoft</tt>'' protocol.
``PC'' or ``3'' will choose the ``<tt>MouseSystems</tt>'' protocol.
<item>If the serial mouse has a roller or a wheel, it may be compatible 
with the ``<tt>IntelliMouse</tt>'' protocol.
</enum>

<sect>Running X
<p>
8mb of memory is a recommended minimum for running X.  The server,
window manager, display manager and an xterm take about 8Mb of virtual
memory themselves.  Even if their resident set size is smaller, on a
8Mb system that leaves very space for other applications such as gcc
that expect a few meg free.  The R6 X servers may work with 4Mb of
memory, but in practice compilation while running X can take 5 or 10
times as long due to constant paging.

The easiest way for new users to start X windows is to type
``<tt>startx >&amp; startx.log</tt>''.  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 <em/xinit/
and <em/startx/ man pages.

 

<sect>Rebuilding Kernels for X
<p>

The GENERIC FreeBSD kernels support XFree86
without any modifications required.  You do not need to make any changes
to the GENERIC kernel or any kernel configuration which is a superset.

For a general description of BSD kernel configuration get <url
name="smm.02.config.ps.Z"
url="ftp://gatekeeper.dec.com/pub/BSD/manuals/smm.02.config.ps.Z">.
It is a ready-to-print postscript copy of the kernel configuration
chapter from the system maintainers manual.

If you do decide to reduce your kernel configuration file, do not
remove the line below (in <tt>/sys/arch/i386/conf</tt>).  It
is required for X support:

<tscreen><verb>
 options		UCONSOLE		#X Console support
</verb></tscreen>

The generic FreeBSD kernels are configured
by default with the syscons driver.  To configure your kernel similarly
it should have a line like this in <tt>/usr/src/sys/i386/conf/GENERIC</tt>:

<tscreen><verb>
 device		sc0	at isa? port "IO_KBD" tty irq 1 vector scintr
</verb></tscreen>

The number of virtual consoles can be set using the MAXCONS option:

<tscreen><verb>
 options		"MAXCONS=4"		#4 virtual consoles
</verb></tscreen>

Otherwise, the default without a line like this is 16.  You must have more
VTs than gettys as described in the end of section 3, and 4 is a reasonable
minimum.

The server supports two console drivers: syscons and pcvt.
The syscons driver is the default in FreeBSD 1.1.5 and higher.  They are
detected at runtime and no configuration of the server itself is required.

If you intend to use pcvt as the console driver, be sure to include the
following option in your kernel configuration file.

<tscreen><verb>
 options		XSERVER			#Xserver
</verb></tscreen>

The number of virtual consoles in pcvt can be set using the following
option:

<tscreen><verb>
 options		"PCVT_NSCREENS=10"	#10 virtual consoles
</verb></tscreen>

The bus mouse driver and the PS/2 mouse driver may not be included, or
may be included but disabled in your kernel.  If you intend to use
these mice, verify the following lines in the kernel configuration file:


<tscreen><verb>
 device		mse0	at isa? port 0x23c tty irq 5 vector mseintr
 device		psm0	at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr
</verb></tscreen>

The <tt/mse0/ device is for the bus mouse and the <tt/psm/ device is 
for the PS/2 mouse.  Your bus mouse interface card may allow you to 
change IRQ and the port address.  Please refer to the manual of 
the bus mouse and the manual page for <tt/mse(4)/ for details.
There is no provision to change IRQ and the port address of the
PS/2 mouse.

The XFree86 servers include support for the MIT-SHM extension.  The
GENERIC kernel does not support this, so if you want to make use of
this, you will need a kernel configured with SYSV shared memory
support.  To do this, add the following line to your kernel config
file:

<tscreen><verb>
 options		SYSVSHM			# System V shared memory
 options		SYSVSEM			# System V semaphores
 options		SYSVMSG			# System V message queues
</verb></tscreen>

If you are using a SoundBlaster 16 on IRQ 2 (9), then you need a patch for
sb16_dsp.c.  Otherwise a kernel configured with the SoundBlaster driver will
claim interrupt 9 doesn't exist and X server will lock up.

S3 cards and serial port COM 4 cannot be installed together on a
system because the I/O port addresses overlap.


<!--
<sect>Rebuilding XFree86
<p>

The server link kit allows you to build an X server using a minimum
amount of disk space.  Just unpack it, make the appropriate changes to
<tt/xf86site.def/, type ``<tt>./mkmf</tt>' and ``<tt/make/'' to link the
server.  See <htmlurl name=README.LinkKit url=LinkKit.html> for more info.

The source tree takes about 114Mb before compiling and an additional
100Mb after ``<tt/make World/''.  You should configure the
distribution by editing <tt/xf86site.def/ and <tt/site.def/ in
<tt>xc/config/cf</tt> before compiling.  By default, the config files
are set up to build shared libraries.

To compile the sources on FreeBSD 1.1 and later, edit
<tt>xc/config/cf/FreeBSD.cf</tt> to set the OS version parameters
correctly, and then type:

<tscreen><verb>
 make World
</verb></tscreen>
-->

<sect>Building X Clients
<p>

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

<bf/Note:/ Starting with XFree86 2.1 and FreeBSD 1.1, the symbol
<bf/__386BSD__/ no longer gets defined either by the compiler or via the
X config files for FreeBSD systems.  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,
<bf/__386BSD__/ for 386BSD, and <bf/__bsdi__/ for BSD/386.


<sect> Thanks
<p>
Many thanks to:
  <itemize>
<item><bf/Pace Willison/  for providing initial *BSD support.
<item><bf/Amancio Hasty/ for 386BSD kernel and S3 chipset support.
<item><bf/David Greenman, Nate Williams, Jordan Hubbard/ for FreeBSD
       kernel support.  
<item><bf/Rod Grimes/, <bf/Jordan Hubbard/ and <bf/Jack Velte/ for
       the use of Walnut Creek Cdrom's hardware. 
<item><bf/Orest Zborowski/, <bf/Simon Cooper/ and <bf/Dirk Hohndel/ for ideas from the Linux distribution.
</itemize>

<verb>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/FreeBSD.sgml,v 3.25.2.3 1998/02/26 13:59:06 dawes Exp $ 





$XConsortium: FreeBSD.sgml /main/12 1996/10/28 05:43:08 kaleb $
</verb>

</article>
