RREEAADDMMEE ffoorr XXFFrreeee8866 33..33..11 oonn OOppeennBBSSDD

				Matthieu Herrb

			 Last modified on: 7 Oct 1997



_1_.  _W_h_a_t _a_n_d _W_h_e_r_e _i_s _X_F_r_e_e_8_6_?

XFree86 3.3.1 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 architectures.

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.2  are available in the OpenBSD 2.2 binary distribution.

XFree86 3.3.1 also builds on other OpenBSD architectures. See section _B_u_i_l_d_i_n_g
_o_n _o_t_h_e_r _a_r_c_h_i_t_e_c_t_u_r_e_s (section 9.3, page 7) for details.


_2_.  _B_u_g _R_e_p_o_r_t_s _f_o_r _T_h_i_s _D_o_c_u_m_e_n_t

Send email to _m_a_t_t_h_i_e_u_@_l_a_a_s_._f_r (Matthieu Herrb) or _X_F_r_e_e_8_6_@_X_F_r_e_e_8_6_._o_r_g if you
have comments or suggestions about this file and we'll revise it.


_3_.  _N_e_w _f_e_a_t_u_r_e_s _i_n _t_h_i_s _r_e_l_e_a_s_e

This release have been done for OpenBSD 2.2. It contains a few minor changes in
respect to the XFree86 3.3.1 distribution for OpenBSD 2.1 that can be found on
the XFree86 sites"

  1.  The servers are no longer installed setuid. You need to run xdm to use X
      safely. You can also set the setuid bit yourself, but ddoonn''tt ddoo tthhaatt
      unless you know what you are doing.

  2.  A security hole that allow to view the first words of an arbitrary file
      when the servers are setuid has been fixed.

  3.  See the Release Notes for non-OS dependent new features in XFree86 3.3.1.





README for XFree86 3.3.1 on OpenBSD					      1





README for XFree86 3.3.1 on OpenBSD					      2



_4_.  _I_n_s_t_a_l_l_i_n_g _t_h_e _B_i_n_a_r_i_e_s

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


_5_.  _C_o_n_f_i_g_u_r_i_n_g _X _f_o_r _Y_o_u_r _H_a_r_d_w_a_r_e

The XF86Config file tells the X server what kind of monitor, video card and
mouse you have.	 You _m_u_s_t create it to tell the server what specific hardware
you have.

XFree86 3.2 introduced a new, user-friendly configuration utility called
XXFF8866SSeettuupp. It has to be run as root. Refer to its documentation for details
about its use.

You'll need info on your hardware:

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

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

    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 _X_F_8_6_C_o_n_f_i_g_(_5_) manual
page.

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

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

_5_._1  _A_b_o_u_t _m_o_u_s_e _c_o_n_f_i_g_u_r_a_t_i_o_n

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 PPSS//22 pro
tocol for talking to the device in that mode.  "cooked" mode is the old Bus
Mouse translation.  By default, the driver runs in "cooked" mode.  It can be
switched using ioctls or by opening the first minor device which is /dev/psm0.

_5_._2  _O_t_h_e_r _i_n_p_u_t _d_e_v_i_c_e_s

XFree86	 supports the dynamic loading of drivers for external input devices








README for XFree86 3.3.1 on OpenBSD					      3



using the XInput extension. Currently supported devices are:

    Joystick (xf86Jstk.so)

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

    SummaSketch tablets (xf86Summa.so)

    Elographics touchscreen (xf86Elo.so)

To use a specific device, add the line

     load "_m_o_d_u_l_e"


in the MMoodduullee section of XF86Config, where _m_o_d_u_l_e is the name of the .so file
corresponding to your device.  You also need to set up a XXIInnppuutt section in
XF86Config.  Refer to the _X_F_8_6_C_o_n_f_i_g_(_5_) man page for detailed configuration
instructions.

You can then change the device used to drive the X pointer with the _x_s_e_t_
_p_o_i_n_t_e_r_(_1_) command.

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

_5_._3  _C_o_n_f_i_g_u_r_i_n_g _P_E_X _a_n_d _X_I_E _e_x_t_e_n_s_i_o_n_s

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 MMoodduullee section
of XF86Config:

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


_6_.  _I_n_s_t_a_l_l_i_n_g _X_d_m_, _t_h_e _d_i_s_p_l_a_y _m_a_n_a_g_e_r

The file xc/lib/Xdmcp/WrapHelp.c is not available in France (where the binary
distribution is built) so support for XDM-AUTHORIZATION-1 is not included here.
You'll have to get WrapHelp.c and rebuild xdm after having set HasXdmAuth in
host.def.

The file is available within the US; for details see ftp.x.org:/pub/R6/xdm-
auth/README.

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:











README for XFree86 3.3.1 on OpenBSD					      4



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

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

     cd /dev
      ./MAKEDEV ttyC5

It's also better to specify explicitly the virtual console to be used by the X
server. If you're experimenting keyboards lockup with xdm, in
/usr/X11R6/lib/X11/xdm/Xservers, replace the line:

     :0 local /usr/X11R6/bin/X


by:

     :0 local /usr/X11R6/bin/X vt06


_7_.  _R_u_n_n_i_n_g _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.

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.


_8_.  _K_e_r_n_e_l _S_u_p_p_o_r_t _f_o_r _X

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

     option XSERVER

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 now the default in OpenBSD.	It offers several vir
tual consoles and international keyboard support.

When not using XKB, the server can read the actual keymap from the keyboard








README for XFree86 3.3.1 on OpenBSD					      5



driver and use to build the X keymap. Be sure to use ``RightAlt ModeShift'' in
XF86Config to have the right AAlltt key behave as AAllttGGrr.

Syscons and codrv are not bundled with OpenBSD. They are available by anonymous
FTP from a number of sites. They are not supported by the XFree86 binary dis
tribution anymore. You can compile support for them by adding -DSYSCONS_SUPPORT
or -DCODRV_SUPPORT to XFree86ConsoleDefines in xf86site.def. See the section
_C_o_n_s_o_l_e _d_r_i_v_e_r_s (section 9.1, page 7) for details.

_8_._1  _A_p_e_r_t_u_r_e _D_r_i_v_e_r

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.

There are two ways to allow XFree86 to access linear memory:

  1.  Disable the kernel security feature by adding `option INSECURE' in the
      kernel configuration file and build a new kernel.

      In OpenBSD 2.2, you will also need to comment out the line initializing
      securelevel to 1 in /etc/rc.securelevel.

  2.  Install the aperture driver:

	1.   The first step is highly dependent from your exact operating sys
	    tem version:

		 OpenBSD 2.0

		 Use the aperture driver from /usr/lkm:

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

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

		 OpenBSD 2.1, 2.2

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


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


      WWaarrnniinngg:: if you boot another kernel than	/bsd, loadable kernel modules








README for XFree86 3.3.1 on OpenBSD					      6



      can crash your system. Always boot in single user mode when you want to
      run another kernel.


	   CCaavveeaatt:: 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 mul
	   tiples VT, only the first one will have linear memory access.
	   Use 'option INSECURE' if you need more that one X server at a
	   time.

_8_._2  _M_I_T_-_S_H_M

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

to your kernel config file. Then from /sys/arch/i386/config, type:

      # rm -f ../compile/<KERNEL-NAME>/*
      # config <KERNEL-NAME>
      # cd ../compile/<KERNEL-NAME>
      # make depend
      # make

Then install your new kernel and re-boot:

      # cp /bsd /obsd
      # cp bsd /
      # reboot


_9_.  _R_e_b_u_i_l_d_i_n_g _t_h_e _X_F_r_e_e_8_6 _D_i_s_t_r_i_b_u_t_i_o_n

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/xf86site.def
before compiling.  To compile the sources, invoke ``make World'' in the xc
directory.











README for XFree86 3.3.1 on OpenBSD					      7



_9_._1  _C_o_n_s_o_l_e _d_r_i_v_e_r_s

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

     if you're using pccons put:

	   #define XFree86ConsoleDefines -DPCCONS_SUPPORT

    if you're using pcvt put:

	   #define XFree86ConsoleDefines -DPCVT_SUPPORT

    if you're using syscons put:

	   #define XFree86ConsoleDefines -DSYSCONS_SUPPORT

    if you're running codrv put:

	   #define XFree86ConsoleDefines -DCODRV_SUPPORT


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

_9_._2  _c_o_n_s_o_l_e_._h _a_n_d _i_o_c_t_l___p_c_._h _f_i_l_e_s_:

If you want to build a server supporting codrv and you don't already have the
corresponding header file ioctl_pc.h installed in /usr/include/machine, then
install the copy that is supplied in xc/programs/Xserver/hw/xfree86/etc.  If
you run OpenBSD-current you probably want to install it in
/usr/src/sys/arch/i386/include too, so that it get reinstalled each time you
run make includes.

If you have installed the  codrv console driver, this file should be taken from
your installed version of the driver.

The console.h file for syscons isn't distributed with XFree86 anymore. You
should get it from the syscons distribution.

_9_._3  _B_u_i_l_d_i_n_g _o_n _o_t_h_e_r _a_r_c_h_i_t_e_c_t_u_r_e_s

XFree86 3.3.1 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, with patches from Kenneth Stailey.

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








README for XFree86 3.3.1 on OpenBSD					      8



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


_1_0_.  _B_u_i_l_d_i_n_g _N_e_w _X _C_l_i_e_n_t_s

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

To avoid the ``Virtual memory exhausted'' message from cc while compiling,
increase the data and stack size limits (in csh type ``limit datasize 32M'' and
``limit stacksize 16M'').


_1_1_.  _T_h_a_n_k_s

Many thanks to:

    PPaaccee WWiilllliissoonn for providing the initial port to 386BSD.

    AAmmaanncciioo HHaassttyy for fixing cursor restoration, mouse bugs and many others.

    CChhrriissttoopphh RRoobbiittsscchhkkoo for fixing com.c and thus select().

    NNaattee WWiilllliiaammss for the patchkit support for X.

    RRoodd GGrriimmeess and JJaacckk VVeellttee of Walnut Creek Cdrom for use of their machines
     in preparing the FreeBSD binary release.

     Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/OpenBSD.sgml,v 1.1.2.2 1997/08/02 13:48:14 dawes Exp $





     $XConsortium$























README for XFree86 3.3.1 on OpenBSD					      9





































































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

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.  Installing Xdm, the display manager ..................................... 3

7.  Running X ............................................................... 4

8.  Kernel Support for X .................................................... 4
    8.1 Aperture Driver ..................................................... 5
    8.2 MIT-SHM ............................................................. 6

9.  Rebuilding the XFree86 Distribution ..................................... 6
    9.1 Console drivers ..................................................... 7
    9.2 console.h and ioctl_pc.h files: ..................................... 7
    9.3 Building on other architectures ..................................... 7

10. Building New X Clients .................................................. 8

11. Thanks .................................................................. 8























				       i