Chapter 6 X & Motif Development Package

LynxOS User's Guide

X & Motif Development Package

This chapter provides an overview of the X & Motif Development Package features, X libraries and utilities, and troubleshooting X issues.

Note: The X & Motif Development Package is not included in all LynxOS packages. Only native development systems include X & Motif. For cross development systems, X & Motif can be purchased separately. Contact your LynuxWorks sales representative for more information.

Installing and Starting X

The X & Motif packages are not installed during the standard LynxOS installation. X & Motif requires a separate installation procedure. Follow the instruction provided in the LynxOS Installation Guide for detailed information.

Once X is installed, it can be configured with the configX utility. For detailed instructions, see the LynxOS Installation Guide. Once the proper display device settings are configured, start x with the startx command:

# startx

X Server Features Overview

The following is a list of features of the X & Motif Development Package:

VGA and SVGA support

Multiple display resolutions and color depth (depending on graphics adapter)

Hot-key switching between display resolutions

Support for ISA, PCI, and AGP bus graphics adapters

Server extensions like the SHAPE, MIT-SHM, Multibuffering, DEC XTRAP, XIdle, XInput Extension, and others

Scalable fonts with font server

Multiple display screen support

Touch screen support for some ELO graphics, Carroll Touchscreen, Lucas/Deeco and MicroTouch touchscreens

Dual touchscreen support

Standard X11 clients

Support for various mice, both serial and PS/2-compatible, including the Intellimouse

Example files include: .xinitrc, .xsession, .Xdefaults, and .mwmrc

X Server Technology from Metro-X

This release of the LynxOS X & Motif Development Package for x86 is based on the Metro-X Enhanced Server Set technology. This server provides the ability to dynamically load adapter modules via a loader, allowing for up-to-date support of current graphics adapters. The adapter modules are in ELF format and are operating system-independent libraries. Also, the loader architecture is easily extensible to support other formats and even other processor architectures.

Networking and the X Server

The X11 graphics system uses a client-server model. The X server is configured to the local system's graphics adapter and controls the output to the local display. The X server can also accept connections from other programs (clients). These X clients instruct the X server on what to draw on the graphics display. The program xterm (the terminal emulator) is a sample X client. These X clients can connect to the server using networking protocols such as TCP/IP, or UNIX domain sockets (on a local system).

TCP/IP is used for connections between remote client and server systems.The UNIX domain connections, are used for connections between the client and server from the same machine or system. The UNIX domain connection configured as a local connection is faster than a TCP/IP connection.

When the X server starts, it creates a TCP/IP listening socket to accept connections from X clients. It then makes a UNIX domain listening endpoint for local connections. If both connection attempts fail, the server aborts. Both listening end points can be active at the same time.

An X client connects to the X server via the local UNIX domain connection, because typically, this connection is faster. If the UNIX domain connection fails, the X client attempts to make a TCP/IP connection by calling the X server TCP/IP listening on socket 6000.

X Server Hot Key Exit

The server in the X & Motif Development Package supports a Hot Key Exit, useful for terminating the X server. The key combination is Ctrl-Alt-Backspace.

Hot Key Resolution Switching

When configuring the X & Motif Development Package, several screen resolutions can be selected for most cards. Users can change between these resolutions on the fly while running X by pressing these key combinations:

Ctrl-Alt-+ (plus) (higher resolution)

Ctrl-Alt-- (minus) (lower resolution)

Hardware Panning

The X & Motif Development Package supports hardware panning, which allows for resolutions higher than the terminal's physical resolution. Windows can extend beyond the screen's physical boundaries and can be viewed by scrolling into the extended area.

Touchscreen Support

Touchscreen controllers are simple devices that transmit absolute x and y coordinates to the serial driver when the screen is pressed. The X11 server reads these coordinates and converts them into X11 events, and treats the touch screen as a one-button mouse.

International Keyboard Support

Metro-X uses the X Keyboard extension to support various keyboards. The keyboard description contains information about the physical layout of a keyboard, the key codes of the keyboard, and the symbol information needed to map the keycodes into keysyms. Metro-X provides many predefined configurations, sorted by language and country. These configurations are selected through the configX utility. For instructions on using configX, see the LynxOS Installation Guide.

Multiheaded Servers

On x86 systems, the Matrox Productiva G100 Multi-Monitor server option provides a multiheaded X server. A single keyboard and mouse can be used to control up to sixteen screens on separate monitors. This provides the ability to run many applications on a single window. This can be useful for image-processing work.

In a multiple screen configuration there is one X process, one mouse, and one keyboard, but several screens. The cursor can be moved between the different screens. Clients connect to the different screens with the syntax
-display :0.X where X is the screen number.

X Libraries

The development system provides access to the standard X and Motif routines and functions via a link library interface. This allows the developer to port existing X and Motif code to LynxOS and to incorporate the X and Motif facilities into new or existing applications.

The Development System

The X & Motif Development Package consists of a set of link libraries, header files and utilities for the development of X and Motif applications.

Library Documentation

Information about the definition, use, and function of each library routine can be found in the X Windows documentation set provided with the product distribution.

An overview of libraries by platform is listed below.

x86 Libraries

File

Description

libX11_s.a

The shared-library version of libX11.a is called libX11_s.a.

libXt_s.a

The shared-library version of libXt.a is called libXt_s.a.

libSM.a

This is an extension of the Xt library and support for Session Management.

libSM_s.a

The shared-library version of libSM.a.

libICE.a

This is also an extension to the Xt library and provides support for communications.

libICE_s.a

The shared-library version of libICE.a.

libXext_s.a

The shared-library version of libXext.a is called libXext_s.a.

x86/PPC Libraries

x86/PPC Libraries

File

Description

libX11.a

The standard MIT X11R6 Xlib is libX11.a, and provides the lowest level interface between the X application and server. It includes routines like XOpenDisplay(), which the client uses to connect to the server. Enhancements have been made to libX11.a for increased reliability and faster local server/client connection mechanisms.

libXau.a

This is a simple Authorization Protocol for X11.

libXaw.a

This is the Athena widget set, which provides building blocks used by many X11R3 and X11R4 clients. It is rarely used by Motif applications.

libXdmcp.a

This is the XDMCP (display manager Authorization Protocol) library used by the xdm (X display manager) client. The X server has hooks to completely support this protocol.

libXext.a

This library contains extensions to the X11 Protocol. It includes the SHAPE extension, which makes the round windows used by oclock and xeyes possible. The X server is compiled with the SHAPE extension.

libXmu.a

This library contains miscellaneous routines.

libXtrap.a

This library is an input simulation library. The library provides support for the simulation and testing of keyboards, mice, and other types of input devices, and the redefinition of the operation of those input devices as well.

libXt.a

The X Toolkit, libXt.a, is a set of routines built on top of Xlib that implements the object oriented widget concept. This toolkit is the basis for both the Athena widget set and the Motif widget set. The use of a widget set provides menus and other high-level functions that allow developers to write applications more quickly.

Motif Libraries

Motif Libraries

File

Platform

Description

libXm_s.a

x86 only

The shared-library version of libXm.a.

libXm.a

x86/PPC

This is the main Motif library. It contains a collection of widgets that implement the OSF/Motif look and feel. Also included are a set of convenient functions to create and manipulate the widgets.

libMrm.a

x86/PPC

This is the Motif resource-manager library. It is used in conjunction with the interface definition language and compiler.

libUil.a

x86/PPC

This library provides support for the User Interface Language compiler.

Other Libraries

Other Libraries

File

Description

libFS.a

Font server library.

libXi.a

Provides support for the client side Xinput.

libXtst.a

This is the XTest library.

libxkbfile.a

Provides support for the XKeyboard.

libXxf86dga.a

This is provides Direct Graphics Interface support.

libXau.a

Provides support for X authentication.

libXdmcp.a

X Device Management Protocol support.

X Utilities

imake

imake is a compiler-independent build facility that is provided for the portability of X clients. It is recommended that users use the imake compiler utility when compiling programs from another source (such as public domain clients). The imake compiler should be run with the -I/usr/lib/X11/config flag as indicated in the imake portion of the man pages.

The xmkmf utility provided, calls the imake utility with the appropriate flags and can be used to generate Makefiles from Imakefiles.

uil

uil is a free-form user interface language provided as part of Motif for the designing of screens and widgets.

Troubleshooting X

Before Contacting LynuxWorks Technical Support

Before contacting LynuxWorks Technical Support for an X related problem, execute the metro-x-pr script distributed with the X distribution and supply all the information it requires. This generates a report file that contains important system information. Provide this report file to LynuxWorks Technical Support (see "Technical Support").

Similarly, for Motif-related issues, metro-motif-pr is provided with the Motif distributions.

Modifying Disk Cache Blocks

The performance of an application using the disk subsystem can be greatly affected by the size of the Disk Buffer Cache residing in kernel memory. The disk buffer cache is used to increase the performance of the operating system. The default value of the Disk Buffer Cache is configured for smaller embedded systems. X windows files tend to be large and quickly consume the disk buffer cache. It is recommended that the buffer cache be increased to at least 1024 blocks. Disk caches with a size of 2048 to 4096 blocks are common on systems that heavily use X and/or the file system. The default entry for the buffer cache is provided below.

/* number of cache memory blocks */
#define CACHEBLKS 1024

This entry from the kernel configuration file /sys/lynx.os/uparam.h must be modified to an appropriate value for the specific system configuration. See the LynxOS User's Guide for more information.

Limited Colors

Some window managers auto allocate many colors by default. With a limited color server, there may be fewer colors for applications. Reconfigure the window manager to use fewer colors. Refer to your window manager man page for more information.

Unsupported Programs

The contrib directory of the X distribution provided by x.org is neither supported nor supplied by LynuxWorks.

Some standard X clients are not supported on LynxOS because the underlying kernel or utility support does not exist. Unsupported clients include xload and xmh.

Xconsole and newconsole

The xconsole can be used to view console messages.

LynxOS also provides a facility similar to xconsole to change the console. See the man page for newconsole(1). Run newconsole in an xterm window. Root privileges are required to change the console.

Caution! If a user changes the console to the pseudo-tty associated with an xterm, that xterm and pseudo-tty must be kept active. Do not close the xterm window. Otherwise, console messages may fill up the pty queue and cause the system to lock up. To close the xterm or exit X, run newconsole to set the console to another device, /dev/atc0, for example, before exiting.

Saving Errors

The X server creates an error file Xerrors, in the /usr/lib/X11/Metro directory. In case of server problems, examine this file to help diagnose the problem.

Window Manager

The X distribution ships with two window managers: mwm (if the Motif distribution is installed), and twm. Only one window manager can run at any given time.

Real-Time Priorities and X

By default, the X server and initial clients run at the priority of the process that started them. X servers and clients do not adjust priority. Raising the priority of the server and window manager above that of other applications, shells, and X clients can improve the interaction with the window system.

If demand-paged virtual memory is active on the system, X programs should be allowed to be swapped because they use so much memory. To do this, make sure that vmstart (typically run from /bin/rc) is running at a higher priority than the priorities chosen for the X programs to swap.

Serial Printer

If both the printer and mouse are configured to use COM1 (/dev/com1), there may be abnormal behaviors if the printer is left configured. Disable the serial printer port by editing the /etc/printcap file.

Diamond Viper 550 TNT video card (x86 only)

Some graphics adapters, for example, the Diamond Viper 550 TNT, require that the SMEMS value in the LynxOS kernel be increased from the default 10 to 50 in the /sys/lynx.os/uparam.h file.

If an error returned by the server resembles the following, change and rebuild the kernel.

Fatal server error:
xf86MapVidMem: failed to smem_create
(Argument invalid/improper)

X Development Troubleshooting

SKDB (Simple Kernel Debugger) and X

While running X, SKDB (Simple Kernel Debugger) can only be run from COM2 and cannot be run from the console. Refer to the Total/db User's Guide, provided with LynxOS distribution, to configure SKDB on COM2.

X and Motif Libraries in /usr/lib

The X and Motif libraries are located in /usr/lib. Some LynxOS compiler/linker combinations do not, by default, look in /usr/lib for libraries. The Install.XM script creates symbolic links for some of these libraries into the /lib directory during the X and Motif installation procedures.

In some cases, users must set the library search path for compilers and linkers (-L for gcc, or setting LIBPATH, for example). Refer to the compiler and linker documentation for detailed instructions.

X and Threads

X and Motif have been developed in a single-threaded environment and are not considered "thread safe." A multithreaded application may use X and Motif library calls if all the calls are confined to a single thread or if all instances of the calls in the application are protected by mutexes.

/lib/cpp (x86 and PPC)

Some X build utilities depend upon the existence of the file /lib/cpp as they expect to be able to use the C Pre-Processor. LynxOS systems provide the GNU C Pre-Processor, gcc-cpp. As a result, a script file called cpp must be created in the directory /lib to provide the required bridge.

The file should contain the lines below with permissions of 755.

x86

i386-elf-lynxos/
usr/lib/gcc-lib/i386-elf-lynxos/2.95.3/cpp0 -traditional "$@"

PPC

/usr/lib/gcc-lib/ppc-elf-lynxos/2.95.3/cpp0 -traditional "$@"

The X install script Install.XM creates this file at the time of X installation.

Note: The X & Motif Development Package is not included in all LynxOS packages. Only native development systems include X & Motif. For cross development systems, X & Motif can be purchased separately. Contact your LynuxWorks sales representative for more information.

x86 Libraries
File	Description
libX11_s.a	The shared-library version of libX11.a is called libX11_s.a.
libXt_s.a	The shared-library version of libXt.a is called libXt_s.a.
libSM.a	This is an extension of the Xt library and support for Session Management.
libSM_s.a	The shared-library version of libSM.a.
libICE.a	This is also an extension to the Xt library and provides support for communications.
libICE_s.a	The shared-library version of libICE.a.
libXext_s.a	The shared-library version of libXext.a is called libXext_s.a.

x86/PPC Libraries
File	Description
libX11.a	The standard MIT X11R6 Xlib is libX11.a, and provides the lowest level interface between the X application and server. It includes routines like XOpenDisplay(), which the client uses to connect to the server. Enhancements have been made to libX11.a for increased reliability and faster local server/client connection mechanisms.
libXau.a	This is a simple Authorization Protocol for X11.
libXaw.a	This is the Athena widget set, which provides building blocks used by many X11R3 and X11R4 clients. It is rarely used by Motif applications.
libXdmcp.a	This is the XDMCP (display manager Authorization Protocol) library used by the xdm (X display manager) client. The X server has hooks to completely support this protocol.
libXext.a	This library contains extensions to the X11 Protocol. It includes the SHAPE extension, which makes the round windows used by oclock and xeyes possible. The X server is compiled with the SHAPE extension.
libXmu.a	This library contains miscellaneous routines.
libXtrap.a	This library is an input simulation library. The library provides support for the simulation and testing of keyboards, mice, and other types of input devices, and the redefinition of the operation of those input devices as well.
libXt.a	The X Toolkit, libXt.a, is a set of routines built on top of Xlib that implements the object oriented widget concept. This toolkit is the basis for both the Athena widget set and the Motif widget set. The use of a widget set provides menus and other high-level functions that allow developers to write applications more quickly.

Motif Libraries
File	Platform	Description
libXm_s.a	x86 only	The shared-library version of libXm.a.
libXm.a	x86/PPC	This is the main Motif library. It contains a collection of widgets that implement the OSF/Motif look and feel. Also included are a set of convenient functions to create and manipulate the widgets.
libMrm.a	x86/PPC	This is the Motif resource-manager library. It is used in conjunction with the interface definition language and compiler.
libUil.a	x86/PPC	This library provides support for the User Interface Language compiler.

Other Libraries
File	Description
libFS.a	Font server library.
libXi.a	Provides support for the client side Xinput.
libXtst.a	This is the XTest library.
libxkbfile.a	Provides support for the XKeyboard.
libXxf86dga.a	This is provides Direct Graphics Interface support.
libXau.a	Provides support for X authentication.
libXdmcp.a	X Device Management Protocol support.

	Caution! If a user changes the console to the pseudo-tty associated with an xterm, that xterm and pseudo-tty must be kept active. Do not close the xterm window. Otherwise, console messages may fill up the pty queue and cause the system to lock up. To close the xterm or exit X, run newconsole to set the console to another device, /dev/atc0, for example, before exiting.

LynuxWorks, Inc.
855 Branham Lane East
San Jose, CA 95138
http://www.lynuxworks.com
1.800.255.5969