README for XFree86 3.3 on OpenBSD Rich Murphey, David Dawes, Marc Wandschneider, Mark Weaver, Matthieu Herrb Last modified on: 5 Jun 1997 1. What and Where is XFree86? XFree86 3.3 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.1 are available from: ftp://ftp.XFree86.org/pub/XFree86/current/binaries/ A list of mirror sites is provided by ftp://ftp.XFree86.org/pub/XFree86/MIRRORS Other OpenBSD versions: These binaries are not compatible with earlier OpenBSD versions. If you're still running OpenBSD 1.2 or 2.0, you should think about upgrading to a newer version of OpenBSD first. If you don't upgrade, you'll have to build XFree86 from the sources. XFree86 3.3 should compile cleanly under earlier versions of OpenBSD, although this has not been tested. XFree86 3.3 also builds on OpenBSD/sparc. See the section ``Building on sparc'' for details. The client side of XFree86 also builds on OpenBSD/alpha. XFree86 has also been built on OpenBSD/mips. It has been tested on an Acer Mips system with a S3/928 board. Contact Per Fogelstrom (pefo@OpenBSD.org) 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 1. There is now a separate config file for OpenBSD. 2. See the Release Notes for non-OS dependent new features in XFree86 3.3. 4. Installing the Binaries Refer to section 4 of the Release Notes for detailed installation instructions. 4.1. Installing Xdm, the display manager 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 xf86site.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 by disabling the console getty and adding the following code to /etc/rc.local: if [ -x /usr/X11R6/bin/xdm ]; then echo -n ' xdm'; /usr/X11R6/bin/xdm fi To disable the console getty, change ``on'' to ``off'' in the console entry in /etc/ttys: ttyC0 "/usr/libexec/getty Pc" pc off secure 5. Configuring X for Your Hardware The 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 hardware you have. XFree86 3.2 introduced a new, user-friendly configuration utility called XF86Setup. It has to be run as root. Refer to its documentation 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. 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. 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. The "cooked" mode is the old BusMouse 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. 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) 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 XIn- put 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 xsetpointer(1) command. For joystick support, you'll need to install 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 manager 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 customize 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. 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 pccons driver is the most widely tested and is the console driver contained in the OpenBSD binary distribution's kernels. The pcvt console driver is also bundled with OpenBSD. 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: device pc0 at isa? port 0x60 irq 1 to device vt0 at isa? port 0x60 irq 1 in your kernel config file, and rebuild and install your kernel. When not using XKB, the server can read the actual keymap from the keyboard driver and use to build the X keymap. Be sure to use ``RightAlt ModeShift'' in XF86Config to have the right Alt key behave as AltGr. 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 distribution anymore. You can compile support for them by adding -DSYSCONS_SUPPORT or -DCODRV_SUPPORT to XFree86ConsoleDefines in xf86site.def. See the section ``Console drivers'' for details. 7.1. Aperture Driver By default OpenBSD includes the BSD 4.4 kernel security model that disables access to the /dev/mem device when in multi-user 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 accelerated servers can take advantage of it, but do not require it. 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. 2. Install the aperture driver: a. The first step is highly dependent from your exact operating system version: o OpenBSD 2.0 Add the following lines to the end of /etc/rc.local: KERNDIR=/usr/lkm if [ -f ${KERNDIR}/ap.o ]; then rm -f ${KERNDIR}/ap modload -o ${KERNDIR}/ap -e ap -p ${KERNDIR}/apinstall ${KERNDIR}/ap.o fi o OpenBSD 2.1 Uncomment the lines loading the aperture driver from /etc/rc.securelevel b. 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. 7.2. 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 option SYSVMSG option SYSVSEM option SYSVSHM to your kernel config file. Then from /sys/arch/i386/config, type: # rm -f ../compile//* # config # cd ../compile/ # make depend # make Then install your new kernel and re-boot: # mv /bsd /obsd # cp bsd / # reboot 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 distribution. 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. 8.1. Console drivers XFree86 3.3 has a configuration option to select the console drivers to use in xf86site.def: o if you're using pccons put: #define XFree86ConsoleDefines -DPCCONS_SUPPORT o if you're using pcvt put: #define XFree86ConsoleDefines -DPCVT_SUPPORT o if you're using syscons put: #define XFree86ConsoleDefines -DSYSCONS_SUPPORT o if you're running codrv put: #define XFree86ConsoleDefines -DCODRV_SUPPORT If you don't define XFree86ConsoleDefines in xf86site.def the pccons and pcvt drivers will be supported. 8.2. console.h and ioctl_pc.h files: 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. You probably want to install it in /usr/src/sys/arch/i386/include too, so that it gets 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. 8.3. Support for shared libs By default XFree86 3.3 builds for OpenBSD with shared library support. If you don't want shared libraries add the following line to xf86site.def: #define BuildBsdSharedLibs NO 8.4. Building on Sparc XFree86 3.3 also compiles on OpenBSD/sparc. The Sun server patches from Dennis Ferguson and Matthew Green have been integrated in xc/programs/Xserver/hw/sun. Small modifications to xf86site.def are needed: o Set all variables defining the servers to build to NO. (The variables controlling the Sun servers to build Xsun24Server, XsunServer and XsunMonoServer are defined at the end of OpenBSD.cf.) o Set ServerToInstall to the sun server of your choice. (Xsun or XsunMono). o Look at other applicable options in the INSTALL document. Problems with this port should be reported to the tech@OpenBSD.org mailing list or directly to me matthieu@laas.fr rather than to the xfree86 mailing list. 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 Makefiles, check the configuration if necessary and type ``make''. Whenever you install additional man pages you should update whatis.db by running ``makewhatis /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''). Note: When porting clients to *BSD systems, make use of the symbol 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: #if (BSD >= 199103) To ensure that this symbol is correctly defined, include in the source that requires it. Note that the symbol CSRG_BASED is defined for *BSD systems in XFree86 3.1.1 and later. This should be used to protect the inclusion of . For code that really is specific to a particular i386 BSD port, use __FreeBSD__ for FreeBSD, __NetBSD__ for NetBSD, __OpenBSD__ for OpenBSD, __386BSD__ for 386BSD, and __bsdi__ for BSD/386. Another note: If you get the message: ld.so: undefined symbol _XtCvtStringToFont at run-time, you've stumbled on a semantic weakness of the OpenBSD dynamic linker. Applications that use libXmu also need libXt. If the client uses a standard Imakefile, this dependency will probably by included in the Makefile automagically -- you'll not see the problem. Otherwise, just add ``-lXt'' to your library list in the Imakefile or Makefile and relink. 10. Thanks Many thanks to: o Pace Willison for providing the initial port to 386BSD. o Amancio Hasty for fixing cursor restoration, mouse bugs and many others. o Christoph Robitschko for fixing com.c and thus select(). o Nate Williams for the patchkit support for X. o Rod Grimes and Jack Velte of Walnut Creek Cdrom for use of their machines in preparing the FreeBSD binary release.