SPARC Sample OWconfig File

Code Example A-1 lists a sample SPARC OWconfig file.

Code Example A-1 Sample SPARC OWconfig File

# Start SUNWxwplt # Copyright 1993 Sun Microsystems, Inc. #"@(#)OWconfig1.11 26 May 1993 SMI" # OWconfig file for OpenWindows X server Version 3.4 # # WARNING: This file is automatically generated when # the OpenWindows software package is installed. This file can be # automatically edited by other optional software packages that # are installed on the system.

Code Example A-1 Sample SPARC OWconfig File (Continued)

# ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST DURING # PACKAGE INSTALLATION, REMOVAL AND UPGRADES! # The format of this file is private to the OpenWindows # X Server and subject to change in future releases. # X Display class="XDISPLAY" name="0" coreKeyboard="IKBD" corePointer="IMOUSE"; # CG6 display adapter class="XSCREEN" name="SUNWcg6" ddxHandler="ddxSUNWcg6.so.1" ddxInitFunc="sunCG6Init"; # CG3 display adapter class="XSCREEN" name="SUNWcg3" ddxHandler="ddxSUNWcg3.so.1" ddxInitFunc="sunCG3Init"; # CG4 display adapter class="XSCREEN" name="SUNWcg4" ddxHandler="ddxSUNWcg4.so.1" ddxInitFunc="sunCG4Init"; # BW2 display adapter class="XSCREEN" name="SUNWbw2" ddxHandler="ddxSUNWbw2.so.1" ddxInitFunc="sunBW2Init"; # CG8 display adapter class="XSCREEN" name="SUNWcg8" ddxHandler="ddxSUNWcg8.so.1" ddxInitFunc="sunCG8Init"; # CG2 display adapter class="XSCREEN" name="SUNWcg2" ddxHandler="ddxSUNWcg2.so.1" ddxInitFunc="sunCG2Init"; # sun Keyboard module class="XINPUT" name="IKBD" ddxHandler="ddxSUNWkbd.so.1" ddxInitFunc="ddxSUNWkbdProc"; # sun Mouse module class="XINPUT" name="IMOUSE" ddxHandler="ddxSUNWmouse.so.1" ddxInitFunc="ddxSUNWmouseProc";

Code Example A-1 Sample SPARC OWconfig File (Continued)

# sun Dials Compatibility module class="XINPUT" name="IDIALSC" ddxHandler="ddxSUNWdialsCompat.so.1" ddxInitFunc="ddxSUNWdialsCompatProc"; # sun Dials module class="XINPUT" name="IDIALS" ddxHandler="ddxSUNWdials.so.1" ddxInitFunc="ddxSUNWdialsProc"; # sun Buttons module class="XINPUT" name="IBUTTONS" ddxHandler="ddxSUNWdials.so.1" ddxInitFunc="ddxSUNWbuttonsProc"; # Example of a dynamically loaded extension "ACMExtn" # class="XEXTENSION" name="ACMExtn" # sharedObject="ACMExtn.so.1" # initFunc="ACMExtnExtensionInit" # preLoad="NO"; # End SUNWxwplt

x86 Sample OWconfig File

Code Example A-2 lists a sample x86 OWconfig file.

Code Example A-2 Sample x86 OWconfig File

# Start SUNWxwpls # Copyright 1993 Sun Microsystems, Inc. #"@(#)OWconfig.x861.14 21 Dec 1993 SMI" # OWconfig file for OpenWindows Version 3.4 # X Display class="XDISPLAY" name="0" # Please make sure that one of the two following lines regarding the # type of mouse is always uncommented. # It is assumed that you are using a Logitech Mouseman serial mouse by # default. # # Logitech Mouseman Serial Mouse coreKeyboard="ATKBD" corePointer="MOUSEMAN-S"

Code Example A-2 Sample x86 OWconfig File

# Logitech Bus Mouse # coreKeyboard="ATKBD" corePointer="LOGI-B" dev0="/dev/fb" listOfScreens="my8514"; # Sample XSCREENCONFIG class class="XSCREENCONFIG" name="my8514" device="8514" pmifile="/usr/openwin/etc/vesa/8514/ati.pmi" res="1024x768"; # Standard VGA display adapter, 640x480 and 16 colors. class="XSCREEN" name="vga4" ddxHandler="ddxSUNWvga4.so.1" ddxInitFunc="vga4Init"; # Standard VGA display adapter, 800x600 and 16 colors. # Panning within a 640x480 window class="XSCREEN" name="vga4" ddxHandler="ddxSUNWvga4.so.1" ddxInitFunc="vga4Init"; # 8514 display adapter class="XSCREEN" name="8514" ddxHandler="ddxSUNW8514.so.1" ddxInitFunc="i8514Init"; # Super VGA display adapter, 1024x768 and 256 colors. class="XSCREEN" name="vga8" ddxHandler="ddxSUNWvga8.so.1" ddxInitFunc="vga8Init"; # PC Keyboard module class="XINPUT" name="ATKBD" ddxHandler="ddxSUNWatkbd.so.1" ddxInitFunc="ATKbdProc" layout="1" type="101"; # Mouseman module class="XINPUT" name="MOUSEMAN-S" ddxHandler="ddxSUNWx86mouse.so.1" ddxInitFunc="ddxSUNWmouseProc" buttons="3" strmod="vuidm4p" dev="/dev/tty00";

Code Example A-2 Sample x86 OWconfig File

# Logitech serial module #class="XINPUT" name="LOGI-S" # ddxHandler="ddxSUNWx86mouse.so.1" # ddxInitFunc="ddxSUNWmouseProc" # buttons="3" # strmod="vuidm5p" # dev="/dev/tty00"; # Logitech bus module class="XINPUT" name="LOGI-B" ddxHandler="ddxSUNWx86mouse.so.1" ddxInitFunc="ddxSUNWmouseProc" buttons="3" strmod="vuidm5p" dev="/dev/logi"; # 3 button Kdmouse bus module #class="XINPUT" name="KDMOUSE-B" # ddxHandler="ddxSUNWx86mouse.so.1" # ddxInitFunc="ddxSUNWmouseProc" # buttons="3" # strmod="vuid3ps2" # dev="/dev/kdmouse"; # Microsoft serial module #class="XINPUT" name="MS-S" # ddxHandler="ddxSUNWx86mouse.so.1" # ddxInitFunc="ddxSUNWmouseProc" # buttons="3" # strmod="vuidm3p" # dev="/dev/tty00"; # Microsoft bus module #class="XINPUT" name="MS-B" # ddxHandler="ddxSUNWx86mouse.so.1" # ddxInitFunc="ddxSUNWmouseProc" # buttons="3" # trmod="vuidm5p" # dev="/dev/msm"; # End SUNWxwpls

File Format Definition

The OWconfig file is composed of a number of resource entries, described by a collection of lines similar to a kernel device driver's .conf file (see driver.conf(4)). A resource is typically a device, such as a frame buffer or a keyboard. Each resource entry consists of a number of "attribute=value" pairs, separated by white space (including spaces, tabs, and new line characters) and terminated by a semicolon (;) character. Any characters following a "#" through the end of the line are treated as a comment and disregarded.

#Sample OWconfig entry class="class name" name="name" [property-name=value ...];

The quotes around the value strings are required only if the string contains delimiters (such as white space or ";" (semicolon)). The back slash character "\" is used as an escape character. For example, \" could be used to include the " character as part of a string value. The parsing routines strip the quotes surrounding string values and pass just the string to the underlying software. The parsing software treats all values as strings; the interpretation of the string value is up to you.

Each resource entry in the file completely defines an instance of a class. For each resource class, there is a set of attributes pertaining to that class. Values for the class and name attributes are required in every resource entry. The class attribute defines the class of the resource. It can be one of the following:

• XDISPLAY
• XSCREENCONFIG
• XSCREEN
• XINPUT
• XEXTENSION

The name attribute identifies the particular resource through a string unique to the class (such as SUNWcg6, IKBD, MIT-SHM). Each class might define additional mandatory attributes specific to that class. Each class is discussed in greater detail starting on page 268.

To avoid name space collisions between multiple vendors, it is strongly recommended (as in driver.conf(4)) that the name attribute for vendor-specific classes begin with a vendor-unique string. A reasonably compact and unique choice is the vendor over-the-counter stock symbol. With other classes, such as XEXTENSION, name space collisions can be avoided by registering extension names with the Xregistry (maintained by the MIT X Consortium).

File and Module Search Paths

By default, OpenWindows is installed in /usr/openwin. The directory /usr/openwin/server/etc contains the default OWconfig file that is distributed with the OpenWindows software. Similarly, the directory /usr/openwin/server/modules will contain the DDX handler modules, Xinput modules and extension modules that are distributed as part of the X Windows package. These constitute components that are distributed and maintained by Sun.

In addition to this, DDX support utility libraries, such as cfb, mfb, mi, mpg and server private libraries such as font, typescaler, and dga are located in the directory /usr/openwin/server/lib.

Since /usr/openwin can be an NFS-mounted installation that is shared by multiple machines on the network, you need a machine-specific configuration directory to describe the local system configuration. You must create this machine-specific directory path in your installation scripts since it is not created by default nor required. The file that describes the local configuration is the OWconfig file. The server searches for the OWconfig file in

/etc/openwin/server/etc.

SPARC: It is optional to have an OWconfig file in /etc/openwin/server/etc because by default, /usr/openwin/server/etc contains the default OWconfig file.

x86: It is not optional to have an OWconfig file in /etc/openwin/server/etc; the kdmconfig utility always creates the file in /etc/openwin/server/etc. Your installation script can edit the /etc/openwin/server/etc/OWconfig file.

The OWconfig search path is:

/etc/openwin/server/etc:/usr/openwin/server/etc

Dynamically loaded modules (XInput, extensions, or DDX handlers) can be located in /etc/openwin/server/modules. The search path for loadable modules is:

/etc/openwin/server/modules:/usr/openwin/server/modules

If an OWconfig file is present in both locations, both files are read, and the server merges these files into a single database. If there are conflicting entries in both files (when an entry has the same values for the "class" and "name" attributes in both files), the server merges both entries on a per-attribute basis. That is, the entry from /etc/openwin/server/etc will take precedence over the entry from the file in /usr/openwin/server/etc. If there are duplicate entries within the same file (when an entry has the same values for the "class" and "name" attributes in the same file), then the last entry for either of these attributes is used.

See Appendix B, "Packaging and Installation Hints" for more details.

The XDISPLAY Class

An XDISPLAY is a collection of graphics output and input devices that the X server manages. It is a collection of Screens, Core Keyboard and Core Pointer.

# XDISPLAY class="XDISPLAY" name="0" coreKeyboard="IKBD" corePointer="IMOUSE" listOfScreens="myGX:my2ndHead,left";

The attributes coreKeyboard and corePointer select devices of class XINPUT as the core keyboard and pointer respectively.

listOfScreens is an optional attribute that is new to this release:

[name[:name[,left|right|top|bottom]]]

If this attribute is not present, the graphics adapter selection defaults to /dev/fb. The value of listOfScreens is a colon-separated list of names of objects of class XSCREENCONFIG. The names can be modified by geometry specifiers (left, right, top or bottom). The semantics of these specifiers are equivalent to the command-line modifiers by the same name. See the Xsun(1) man page.

The Screens specified in listOfScreens are added in order. In the above example, the server recognizes myGX as Screen 0 and my2ndHead as Screen 1.

---

x86 - If the display adapter is not associated with the kernel driver (for vga4, vga8 and 8514) the listOfScreens attribute must exist. The kdmconfig utility will create a listOfScreens attribute and value in the XDISPLAY class entry.

---

The XSCREENCONFIG Class

An XSCREENCONFIG instantiates an object of class XSCREEN and abstracts the per-instance configuration information.

#XSCREENCONFIG class="XSCREENCONFIG" name="my8514" device="/dev/fb0" # SPARC example device="8514" # x86 example dpix="90" dpiy="90" defclass="PseudoColor" defdepth="8" grayvis="NO" res="1024x768" # x86 example pmifile="/usr/openwin/etc/vesa/i8514/ati.pmi";# x86 example

The name attribute is referenced in the listOfScreens of the XDISPLAY class. The value of the name attribute is not important; however, the actual names generated should be unique within an instance of the OWconfig file. It is up to you, the IHV, to generate a meaningful name (my8514 is an x86 example). The OWconfig file specification and the X server do not attach any meaningful semantic to the actual value of this name.

The device attribute is equivalent to the -dev command-line option as specified for Xsun.

The dpix, dpiy, defclass, defdepth, and grayvis attributes are optional and are equivalent to the -dev command-line option as specified for Xsun(1).

The value of the device attribute depends on whether a kernel graphics device driver is associated with the display adapter or frame buffer. If a driver exists (as is always the case on SPARC), the device attribute value is the device special filename associated with the driver (for example, /dev/fb0). If a driver does not exist (as can happen with several x86 graphics adapters), the device attribute value is a descriptive name of the graphics adapter (for example, 8514), and corresponds directly to the name of an object of class XSCREEN.

The XSCREEN Class

An XSCREEN is a graphics display adapter, or frame buffer.

# XSCREEN class="XSCREEN" name="SUNWcg6" ddxHandler="ddxSUNWcg6.so.1" ddxInitFunc="sunCG6Init";

The value of the name attribute depends on whether a kernel graphics device driver is associated with the display adapter or frame buffer. If the kernel driver exists, it is probed with the VIS_GETIDENTIFIER ioctl to determine the name of the object of class XSCREEN that is loaded by the server. For more information on drivers, see Writing Device Drivers.

x86: The name attribute is a descriptive name of the graphics adapter and corresponds directly to the value of the device attribute in an object of class XSCREENCONFIG.

The ddxHandler follows the naming convention ddx<organization><device>.so.<majorVersion>. The initialization function is the single symbolic entry point into the DDX handler. To avoid namespace collisions, it is recommended that IHV's follow a coding practice of prefixing the InitFunc name with an <organization><device> prefix as well. It is further recommended that all symbols internal to the DDX handler, and symbols in support libraries linked to the DDX handler (if any), be similarly prefixed to minimize namespace collisions.

The XINPUT Class

The XINPUT class is for X Input Extension modules and X input core Keyboard and Pointer modules.

SPARC Sample XINPUT Class

# sun Keyboard module class="XINPUT" name="IKBD" ddxHandler="ddxSUNWkbd.so.1" ddxInitFunc="ddxSUNWKbdProc"; # sun Mouse module class="XINPUT" name="IMOUSE" ddxHandler="ddxSUNWmouse.so.1" ddxInitFunc="ddxSUNWmouseProc";

x86 Sample XINPUT Class

# 3-button Kdmouse bus module class="XINPUT" name="KDMOUSE-S" ddxHandler="ddxSUNWx86mouse.so.1" ddxInitFunc="ddxSUNWmouseProc" buttons="3" strmod="vuid3ps2" dev="/dev/kdmouse";

XINPUT modules follow the naming convention:

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

Devices of class XINPUT are selected as the coreKeyboard or corePointer devices by setting the attributes in the XDISPLAY class to the appropriate value. See "The XDISPLAY Class" on page 268.

The XEXTENSION Class

The XEXTENSION class is for X Extension modules that are dynamically loaded by the server.

# XEXTENSION named ACMExtn class="XEXTENSION" name="ACMExtn" sharedObject="ACMExtn.so.1" initFunc="ACMExtnExtensionInit" preLoad="NO";

In this case, the extension name should be registered in the Xregistry (maintained by the MIT X Consortium) to avoid name space collisions. The value of the preLoad attribute can be YES or NO depending on whether you want the server to load this extension at startup (YES), or when XQueryExtension is called (NO). Either way, XListExtensions lists all statically linked extensions in the server and dynamically loadable extensions with an entry in the OWconfig file. XListExtensions simply lists extensions; it does not cause the extensions to be dynamically loaded.

OWconfig Access Method

The OWconfig Access Method standardizes access to and manipulation of an OpenWindows configuration (OWconfig) database file. If your DDX handler requires configuration information, use this method to access that information specific to your device. Note that not all DDX handlers require configuration information.

OWconfig Database

An OWconfig database is a hierarchical list of name/value pairs. The meaning of a particular name/value pair depends upon its position in the hierarchy, as well as the application's interpretation of its value. More concretely:

• An OWconfig database is a list of "classes"; each "class" has a name.
• A "class" is a list of "instances"; each "instance" has a name.
• An "instance" is a list of "attributes"; each "attribute" has a name and a value.

As an example, a typical OWconfig database file contains a declaration of an instance of class "XDISPLAY" whose name is "0" (for screen 0). This instance of the "XDISPLAY" class may contain definitions for attributes such as "coreKeyboard" and "corePointer." The OWconfig file may contain several declarations of instances of class "XDISPLAY."

The access method does not enforce class/instance/attribute naming conventions, nor does it check values of attributes.

OWconfig API

The C language definition of the OWconfig Access Method API may be found in the include file /usr/openwin/include/X11/Sunowconfig.h.

OWconfigGetClassNames

char ** OWconfigGetClassNames(char *class)

Purpose	All users of this function should call OWconfigFreeClassNames to free the list and the strings to which it points.
Returns	(char **) to list of class instance names, or NULL if class did not exist. The end of the list is indicated by a NULL pointer.
ArgumentsOWconfigFreeClassNames	class: name of class for which to name all instances.
void
Purpose	Frees results of OWconfigGetClassNames.
Arguments	list: NULL terminated list of strings to free.

OWconfigGetAttribute

char * OWconfigGetAttribute(char *class, char *name, char *attribute)

Returns	(char *) to value of attribute or NULL if attribute could not be found. The string returned by this function can be freed using OWconfigFreeAttribute.
Arguments	class: name of class to which named attribute belongs

name: name of instance of class to which named attribute belongs

attribute: name of sought attribute

OWconfigFreeAttribute

void OWconfigFreeAttribute(char *attribute)

Purpose	Frees string returned by OWconfigGetAttribute.
ArgumentsOWconfigGetInstance	attribute: string, allocated by OWconfigGetAttribute, to be freed.
OWconfigAttributePtr
Purpose	Use this function to free the memory allocated to the information returned by OWconfigGetInstance.
Arguments	class: name of class from which to list attributes

name: name of instance of class from which to list attributes

numberInAttr: receives number of attributes in returned list

Returns....OWconfigAttributePtr or NULL.

OWconfigFreeInstance

void OWconfigFreeInstance(OWconfigAttributePtr attr, int numberInAttr)

Frees a list created by OWconfigGetInstance.

Arguments..attr: list of attributes to free

numberInAttr: number of attributes in list

Packaging

The API components of the access method are in the following files:

• /usr/openwin/lib/libowconfig.so.1
• /usr/openwin/lib/libowconfig.so
• /usr/openwin/include/X11/Sunowconfig.h

Typical Usage

If you want to retrieve configuration information for your device from the OWconfig database you will need to use, at a minimum, the OWconfigGetAttribute and OWconfigFreeAttribute functions. Note that not all DDX handlers require configuration information.

By the time your DDX handler's initialization function is called, the server has loaded into memory a copy of the OWconfig database. The functions in "OWconfig API" on page 273 are provided as a read-only access method to this database.

There are two types of configuration information that you may want to access:

• attributes documented in the DDK manual

To access these attributes use the documented class and name values as part of an appropriate OWconfig function call.

• attributes added to an OWconfig file as part of your installation process (configuration information specific to your device)

  To access these attributes you must first know how to access the OWconfig attribute that belongs to your device. The following code illustrates how to get this information:

int ddxACMEProc(DevicePtr pAcme, int what) { char *tmp; ... switch(what) { case DEVICE_INIT: ... /* The following illustrates how to get configuration */ /* information belonging to this device (ddx) driver ,which */ /* in this case belongs to the XINPUT class, and which */ /* contains an attribute called dev. */ tmp = OWconfigGetAttribute("XINPUT", ((DeviceIntPtr)pAcme)->devEntry->tag, "dev"); ...

The tag value is the key to locating information belonging to a particular device driver.