README for Solaris XFree86 Video Drivers and Porting Kit (Source Edition)

February 8, 2002

1. What is the Source Edition of Solaris XFree86 Video Drivers and Porting Kit?

The Source Edition of the Solaris XFree86 Video Drivers and Porting Kit provides the MODIFIED and AUGMENTED XFree86 source code from which the packages SUNWxf86r and SUNWxf86u are built. These packages are included in the Binary Edition of Solaris XFree86 Video Drivers and Porting Kit.

The Source Edition of the Solaris XFree86 Video Drivers and Porting Kit is based on the freely redistributable open-source implementation of the X Window System published by The XFree86 Project, Inc. See http://www.xfree86.org for details.

The Source Edition of the Porting Kit is intended primarily for Independent Hardware Vendors (IHVs) and other developers who want to enhance or create additional video-device driver support for Solaris x86 Platform Edition, fix bugs in XFree86 video drivers and library modules, or redistribute the Porting Kit with additional features.

The MODIFIED and AUGMENTED XFree86 source code is based on version 4.2.0 of XFree86.

2. How does the the Porting Kit work?

1. The DDX Modules in the Solaris X Window System

   When the Solaris X Window System server (Xsun) starts, the server dynamically loads device-dependent (ddx) modules for mouse, keyboard, and display. The syntax of a typical ddx module name in the Solaris operating environment is ddxSUNWdriver.so.1, where driver represents the name of a particular driver. The ddx module names to load are specified in the configuration file /etc/openwin/server/etc/OWconfig.

   After loading, each ddx module is initialized and then works with Xsun according to a defined ddx interface.

   When looking for ddx modules to load, Xsun searches first in the directory /etc/openwin/server/modules, and then searches in the directory /usr/openwin/server/modules. The ddx modules are also refered to as video drivers.

2. The "Wrapper" DDX Module, XFree86 Driver Links and XFree86 Drivers

   The Porting Kit provides a common XFree86 interface ddx module known as the "wrapper" module, ddxSFWxf86.so.1, and one XFree86 driver link to the wrapper module for every XFree86 driver that exists. XFree86 driver links are named ddxSFWxf86.driver.so.1 (where driver represents the particular name of a driver). The wrapper module and all XFree86 driver links are located in /etc/openwin/server/modules.

   When a system is configured to use an XFree86 driver, the configuration file uses the name ddxSFWxf86driver.so.1 in its ddxHandler field. driver represents the name of the driver that you select on the Video Device Screen of kdmconfig. During the initialization process, when Xsun loads the display ddx module ddxSFWdriver.so.1, the wrapper module ddxSFWxf86.so.1 is the one that is actually loaded. The wrapper module in turn loads common XFree86 library modules in /usr/X11R6/lib/modules, and then loads the XFree86 driver driver_drv.o, based on the driver information that is extracted from the name of the XFree86 driver link ddxSFWxf86.driver.so.1. driver_drv.o is a XFree86 driver that is compiled from the unmodified XFree86 source, and installed in /usr/X11R6/lib/modules/drivers.

3. Runtime Environment

   The runtime environment for XFree86 drivers is defined as object files that resolve external function calls and variable references from the wrapper module and XFree86 drivers during runtime. The runtime environment consists of:

   • Library modules, which are provided in the package SUNWxf86u and installed in /usr/X11R6/lib/modules.

     The wrapper module and XFree86 drivers both load these modules.

   • XFree86 functions that are defined in the following object files and libraries:

     xfree86/common/xf86Init.o
     xfree86/common/xf86IniExt.o
     xfree86/common/libxf86.a
     xfree86/parser/libxf86config.a
     xfree86/os-support/libxf86_os.a
     xfree86/loader/libloader.a
     xfree86/common/libxf86.a
     xfree86/os-support/libxf86_os.a
     

     These object files and libraries are originally built into the XFree86 X Window System server, but are now part of the wrapper module. Having the wrapper module provide a runtime environment that is otherwise provided by the XFree86 X Window System server is a key to the Porting Kit.

     In addition to these object files and libraries, the wrapper also includes new functions in the dix and mi layers that only exist in XFree86 source code.

4. Compatibility Issues

   Compatibility problems arose due to the introduction of new fields and the different ordering of fields in some important server header files in XFree86 source code. The problem was solved in two locations:

   • Appending new fields to Solaris header files and recompiling the Solaris X Window System server (Xsun) with the modified header files. The recompiled Xsun is delivered in the Solaris 8 patch, 108653-30, in Solaris 8 Update 5 and later Updates, and in the Solaris 9 Beta release of the Solaris operating environment.

   • Re-ordering the fields in XFree86 server header files so that they match the order in Solaris header files.

5. Source Code Modification and Augmentation

   Sun Microsystems has modified the XFree86 source code by:

   • Resolving compatibility problems between Solaris operating environment and XFree86 systems. Most of these changes are made in files under Xserver/include, Xserver/mi, and Xserver/dix.

   • Excluding the portions of builds that are irrelevant to building XFree86 drivers and their runtime environment. Most of these changes appear in Imakefiles and files in config/cf.

   • Redirecting configuration parsing to using the Solaris configuration file OWconfig if the XFree86 configuration file XF86Config does not exist, or if it does exist but lacks sufficient information. These changes appear in files in Xserver/hw/xfree86/parser.

   • Removing XFree86 source code that deals with input devices, since we use the existing Solaris ddx modules to handles these devices. These changes appear in some files in Xserver/hw/xfree86/common.

   XFree86 Driver source code files remain unchanged - this is one of the goals of the porting kit: to avoid work on vendor dependent hardware code.

   Source is augmented by creating some files in the new directory Xserver/hw/xfree86/drivers/sunxf86. The new files in that directory are used to build the wrapper module, create XFree86 related configuration files (xqa files and the additional adapters.idb file), install documentation, and build the packages.

6. Configuration Issues

   There are two configuration issues in using XFree86 drivers:

   First, the configuration file OWconfig for the Solaris operating environment replaces the XFree86 configuration file XF86Config. But you can use XF86Config as a supplement to specify XFree86-specific configuration information.

   Second, config/probe modules x86Config.so.1 and x86Probe.so.1, which kdmconfig loads, are enhanced so that:

   • A user can select XFree86 drivers on the Video Device Selection screen with kdmconfig.
   • XFree86 drivers can be auto-detected and configured during probing.

   Special versions of xqa files (which are referenced as XFree86 xqa files below) enable users to select XFree86 drivers in kdmconfig. XFree86 xqa files differ from xqa files that are used in Solaris operating environment in that they are created one for each XFree86 driver, and each contains a text string xf86.driver.ddx in the Module field. The prefix xf86 identifies the file as an XFree86 xqa file, and causes the text string to be converted to XFree86 driver link format (ddxSFWxf86.driver.so.1) in x86Config.so.1.

   To ease maintenance, XFree86 xqa files are generated with tool xqagen.sh from a description table xqadatafile. They are generated in xfree86/drivers/sunxf86/boards/xf86, and installed in /usr/X11R6/etc/devdata/SUNWaccel/boards/xf86 during pkgadd. A link from the alternate path that begins /etc/openwin is also created for reference.

   kdmconfig uses probing to identify graphics and input devices for creating the OWconfig configuration file. OWconfig lists driver modules that load for each identified device. In the Solaris operating environment x86 Platform Edition, the file /usr/openwin/etc/devdata/iddbdir/adapters.idb is used to probe graphics devices. adapters.idb contains stanzas, each of which contains a list of items that characterizes a graphics device. The list of items includes an xqa file that identifies driver and modes information for the graphics device. The probing function searches the stanzas for one that best matches the installed graphics device. When the probing function finds a match, the probing function uses the xqa file that is listed in the stanza to retrieve driver and other information. You can extend this method to configure XFree86 drivers by listing XFree86 xqa files in stanzas.

   Because you should not modify the original adapters.idb file that Sun includes with the Solaris operating environment x86 Platform Edition, you can now include an alternative adapters.idb file in /etc/openwin/etc/devdata/iddbdir. In this additional adapters.idb file, you can specify stanzas that contain references to XFree86 xqa files. You can also specify stanzas that contain references to both XFree86 xqa files and stanzas that contain references to xqa files for the Solaris operating environment.

   /etc/openwin/etc/devdata/iddbdir/adapters.idb takes precedence over /usr/openwin/etc/devdata/iddbdir/adapters.idb. The module x86Config.so.1 now searches for xqa files and the module x86Probe.so.1 now searches adapters.idb from paths starting at /etc/openwin first, in additional to the regular search paths starting at /usr/openwin.

   If you are using Solaris 8, or Solaris 8 Update 1 through Update 4, you need to install Solaris patches 109401-10 to take advantage of these changes.

   Note: You can download the latest version of these patches from SunSolve.

   If you are using Solaris 8 Update 5 or a later version or later releases (Solaris 9) of the Solaris operating environment, these changes are already incorporated into the operating environment.

3. How to add new drivers or add support for new chips in existing drivers?

Follow these steps to add new chip support to an existing driver drv:

1. Modify the driver code in xfree86/drivers/drv.

2. In xfree86/common/xf86PciInfo.h, add the new chip ID.

3. In xfree86/drivers/drv, run  make all.

   The command builds the new driver in xfree86/drivers/drv.

4. Is your test machine the same as your build machine?

   • If no, go to the next step.

   • If yes, in xfree86/drivers/drv, run  make install.

     The command installs the new driver for testing.

5. For release, update the VERSION field in xfree86/drivers/sunxf86/packages/SUNWxf86u/pkginfo.

6. In xfree86/drivers/sunxf86/packages, run  make SUNWxf86u.

   The command builds the new package in xfree86/drivers/sunxf86/pkgarchive.

Follow these steps to add new driver drv:

1. Create a new directory xfree86/drivers/drv.

2. Add the new driver in xfree86/drivers/Imakefile.

3. In xfree86/drivers, run  make Makefile.

   The command creates a Makefile that "descend builds" to the new driver drv.

4. In xfree86/drivers/drv, add the new code that you want.

5. In xfree86/common/xf86PciInfo.h, add new chip IDs that are supported by the new driver.

6. In xfree86/drivers/drv, run  make all.

   The command builds the new driver in xfree86/drivers/drv.

7. Is your test machine the same as your build machine?

   • If no, go to the next step.

   • If yes, in xfree86/drivers/drv, run  make install.

     The command installs the new driver for testing.

8. Create a new xqa file for the new driver in xfree86/drivers/sunxf86/boards/xf86, add an entry for the new driver in xqadatafile, and run  make all.

9. Is your test machine the same as your build machine?

   • If no, go to the next step.
   • If yes, run  make install.

     The command installs the new xqa file.

10. For release, update VERSION in xfree86/drivers/sunxf86/packages/SUNWxf86u/pkginfo, add an entry for the new driver to xfree86/drivers/sunxf86/packages/SUNWxf86u/prototype, and then run  make SUNWxf86u in xfree86/drivers/sunxf86/packages.

    The command builds the new package in xfree86/drivers/sunxf86/pkgarchive.

4. How to auto-detect and configure with XFree86 video devices during probing ?

As discussed in the previous section, the modified probing module reads adapters.idb files in both the /usr/openwin/etc/devdata/iddbdir and /etc/openwin/etc/devdata/iddbdir directories.

The search algorithm that is used by the probing module works as follows:

1. When the probing module reads adapters.idb, it processes the stanzas sequentially and when all items that are listed in the stanza match the properties of these items for the installed video device, that stanza is selected.

   If more than one stanza matches, the stanza that contains the greater number of matching items is selected. If two stanzas match exactly, the stanza that is found first is selected.

2. If /etc/openwin/etc/devdata/iddbdir/adapters.idb exists, the probing module searches the file in /etc/openwin/etc/devdata/iddbdir/adapters.idb first.

   If the probing module finds one or more matching stanzas in /etc/openwin/etc/devdata/iddbdir/adapters.idb, the probing module terminates searching.

   If the probing module doesn't find a matching stanza in /etc/openwin/etc/devdata/iddbdir/adapters.idb, the probing module then searches /usr/openwin/etc/devdata/iddbdir/adapters.idb.

The porting kit does not provide /etc/openwin/etc/devdata/iddbdir/adapters.idb. You must create this file yourself. But the porting kit does provide a sample file in /usr/X11R6/etc/devdata/iddbdir/adapters.idb, in which stanzas that are used to configure the XFree86 ati driver are commented out. The first stanza contains three items, the second contains two. The xqa file listed in both stanzas, xf86/ati.xqa, is to be referenced in /etc/openwin/etc/devdata/SUNWaccel/boards, which itself is a link to /usr/openwin/etc/devdata/SUNWaccel/boards.

When you create your version of adapters.idb, you need to decide whether you want to prompt with XFree86 drivers or drivers for the Solaris operating environment. For example, if you use the stanzas in the sample file adapters.idb, you consequently prompt with the XFree86 ati driver for ATI RAGE128 and ATI MACH64 cards, but you will prompt with the ati driver provided with the Solaris operating environment for other ATI cards.

Note: If you need to redistribute your version of adapters.idb, deliver this file in the package SUNWxf86r by creating a new prototype file for it.

To create matching items in a stanza, you need first to plug in the graphics card, run prtconf -pv on the system, and get the information from these fields of the output:

video-adapter-type:
vendor-id:
vesa-oem-product:
vesa-oem-revision:
vesa-oem-string:
vesa-oem-vendor:

Then you need to specify some of above entries in adapters.idb with the format:

property=pos1:pos2:"string"

where property represents any of the preceding fields. The value of property is extracted from string between positions pos1 and pos2.

For example, here is the stanza for a Matrox graphics card:

Type=adapter
File="matrox/mga-milt4.xqa"
	video-adapter-type=0:4:"svga"
	vesa-oem-vendor=0:6:"Matrox"
	vesa-oem-product=0:7:"MISTRAL"
	video-memory-size=0x400000
Enddevice

5. How to do a build ?

The source is created from modification and augmentation of a portion of version 4.2.0 of XFree86.

Source code is delivered in the package SUNWxf86s, and will be installed at location /opt/xf86/X420. You need a total of 122 Mbytes to store the source code, and a total of 165 Mbytes for the build area.

To build the Source Edition of the Porting Kit:

1. Ensure that you have access to:

   • Solaris 8 x86 Platform Edition or Solaris 8 x86 Platform Edition Update 1 through Update 5, or Solaris 9 x86 Platform Edition

   • gcc compiler (the gcc compiler that is provided on the Solaris Companion CD (2.95.2) is the recommended version to use)

2. In the directory xc, run  make World.

   The command builds the entire source tree including the two binary packages, SUNWxf86r and SUNWxf86u. The packages will be located in xfree86/drivers/sunxf86/pkgarchive and may be installed from there.

   Because the object files and libraries are part of the runtime environment, and are now built into the wrapper module, any changes you make to them should trigger a rebuild and a redelivery of the wrapper module.

   Special targets localall and localinstall are created in xfree86/drivers/sunxf86/Imakefile to facilitate the development process. Running  make localall or  make localinstall does builds without descending to the subdirectories.

Back to Top