How the Server Interfaces With the Loadable DDX Handler

The server interfaces with the loadable DDX handler in the following manner.

1. The module containing the device's DDX handler is installed in the modules directory--the default directory is /usr/openwin/server/modules. Since the /usr/openwin path could be an NFS mount point, a parallel directory structure can be created on the local machine under /etc/openwin/server/modules. The DDX handler modules that are distributed with the standard OpenWindows packages are always installed in /usr/openwin/server/modules. DDX handlers supplied by Independent Hardware Vendors (IHVs) can be installed in either the machine local path (preferred, if the installation will not be shared between different machines), or under the default path /usr/openwin. (See Appendix B, "Packaging and Installation Hints" for more details).

The server searches for DDX handlers using the following path:

  /etc/openwin/server/modules:/usr/openwin/server/modules.
  This search path cannot be altered by the end user.

---

Note - For debugging purposes, create symbolic links from /etc/openwin to point to your development environment where you want to debug your code. You will need to edit the /etc/openwin/server/etc/OWconfig file to load/configure your DDX handler. Use /etc/openwin because it is intended to be local to the target machine (your development environment); do not use /usr/openwin because it is intended to be shared by many machines.

---

2. The devices that are added as Screens are specified with the -dev command-line option to openwin. For example:

example% openwin -dev /dev/cgsix0 -dev /dev/cgthree0 left

---

For SPARC systems - If no devices are specified on the command line, the server defaults to opening the /dev/fb device. This is a symbolic link to the appropriate driver entry in /dev/fbs, created when the system is booted with boot -r. See the openwin (1) man page for more information.

---

---

For x86 systems - If no devices are specified on the command line, the server defaults to values specified in the OWconfig file. The argument specified with the -dev command line option is the name of a supported display (such as 8514, v256, or vga4). This name is matched against the name attribute specified in a resource line. See Appendix A, "The OWconfig File" for more details.

---

3. The server reads a configuration file (OWconfig) to determine the filename of the dynamically loadable DDX handler. This file is searched using the search path /etc/openwin/server/etc:/usr/openwin/server/etc. If the configuration file is found in both locations, the server constructs a database combining the two files. This search path cannot be altered by the end user.

For debugging purposes only, an alternate directory in which the OWconfig file can be found can be specified by setting the environment variable OW_CONFIG_PATH before running the server. This environment variable is not documented in any end-user documentation and should not be recommended to end users.

example% setenv OW_CONFIG_PATH /home/joe

(See Appendix A, "The OWconfig File" for more information on the OWconfig file).

4. The server loads the appropriate DDX handler module and calls ddxInitFunc. The ddxInitFunc initializes the device and data structures so that the server can run. The ddxInitFunc has the same specification as the scrInitProc defined in the MIT document, Definition of the Porting Layer for the X v11 Sample Server.

The Initialization Function

Each graphics adapter's DDX handler defines an initialization function that is called at server restart. This function initializes the device and the Screen data structure associated with it.

Bool xxxInit(int index, ScreenPtr pScreen, int argc, char **argv);

---

For SPARC systems - For a sample implementation of the ddxInitFunc and a complete sample implementation of a minimal DDX handler for a simple-memory frame buffer, see the sample cg3 DDX handler online in

ddk_2.6/xserver/server/ddx/solaris/sparc/cg3.

---

---

For x86 systems - For a sample implementation of the ddxInitFunc and a complete sample implementation of an equivalent DDX handler for a simple 256 color VGA display adapter, see the sample v256 DDX handler online in ddk_2.6/xserver/server/ddx/solaris/i386/displays/v256.

---

Device Self-Identification

As noted in Step 2 on page 10, devices added as X screens are specified by using the openwin command line and the -dev option. The server opens each device specified with -dev in its InitOutput routine, in turn. (If no devices are specified, the default device is /dev/fb). It then issues an ioctl (VIS_GETIDENTIFIER) to the device driver. The device driver for the graphics device is expected to implement this ioctl to identify the device uniquely. The ioctl returns a unique string name. The server looks up this string name in the OWconfig file under the class XSCREEN. The DDX handler filename specified in this entry is then dynamically loaded by the server, and the ddxInitFunc symbol specified in the entry is called by the DIX routine AddScreen. For a complete specification of the device identification ioctl, see Writing Device Drivers.

---

For x86 systems - This release does not automatically self-identify the various video card adapters supported. The video cards are not able to specify the card type and supported resolutions and features on most Intel architecture machines. Default video adapter types, initialization and resolution information is stored in the OWconfig file for Intel machines. This information is created during installation with input from the user. The default video display selection is also determined during installation and stored in the OWconfig file.

---

DDX Versioning

A versioning scheme is required to ensure that the server and the DDX handler it dynamically loads are compatible. The OpenWindows server component of the Device Developer's Kit (DDK) contains the header files and documentation that define the DDX interface (consisting of data structures and functions) between the server and the dynamically loaded DDX handlers. This component is used to build a DDX handler and has a version number, referred

to as the DDK version number. The DDK version number is available as a manifest constant in the header file sun.h that every DDX handler must include. The following are the important defines from the sun.h header file:

/* * Server Device Developer's Kit (DDK) Version number */ #define DDK_MAJOR_VERSION 1 #define DDK_MINOR_VERSION 2 typedef struct { CARD16 majorVersion; CARD16 minorVersion; } sunDDKVersionRec, *sunDDKVersionPtr; sunDDKVersionPtr sunGetDDKVersion(void);

Each release of OpenWindows is accompanied by a release of the DDK that was used to build the server. This DDK is used by IHVs to build DDX handlers that are compatible with the OpenWindows server in that release. IHVs supplying DDX handlers must follow these versioning rules:

• The DDK majorVersion used to build the DDX handler is stamped in the filename of the handler, such as, ddxSUNWcg6.so.1. The convention used in naming DDX handlers is:

ddx<organization><device>.so.<majorVersion>

• The server is also stamped internally with the DDK version number used to build the server. The server never dynamically loads a module with a majorVersion greater than its own. For example, a server built with a DDK version 1.0 will never load a DDX handler built with a DDK version 2.0.
• The server dynamically loads a DDX handler with a DDK majorVersion less than its own DDK majorVersion, only if the server has explicitly decided to emulate that lesser majorVersion interface. Every time a new version of OpenWindows and a new version of the server DDK are released, this DDK document specifies which, if any, DDK majorVersions are emulated by the server.

---

Note - For this release of the server DDK, no prior versions are emulated.

---

• The server dynamically loads a module that has the same DDK majorVersion as itself. If the DDX module depends on functionality that was added in a particular minorVersion of the DDK, it is up to you to check for the existence of that functionality, by checking the server's DDK version number.

  A DDX module can provide its own workaround if the functionality does not exist, or it can fail with an appropriate error message indicating the server version number it requires.

  The functionality differences between minorVersion releases of the DDK will be documented in future releases of this manual. A DDX handler module can check the server's DDK version number by calling the sun library function sunGetDDKVersion.

#include "sun.h" sunDDKVersionRec serverVersion = sunGetDDKVersion(); if (serverVersion->majorVersion == 1 && serverVersion->minorVersion < 5) { .... } else { ....