LayGO for Linux

LayGO for Linux has been tested with Linux release 2.0.36 (Red Hat version 5.2), Linux releases 2.2.14 and 2.2.16 (Red Hat version 6.2) and Linux release 2.4.7 (Red Hat version 7.2).

Installing the Distribution Files

The LayGO distribution files are shipped in RPM format as laygosdk-3.10-1.i386.rpm. Copy the RPM file to a temporary directory, become root and enter:

# rpm -iv laygosdk-3.10-1.i386.rpm

The default installation is /opt/laygo-3.10, however you can install the distribution in a directory other than /opt using the --prefix <directory> option to rpm. As part of the installation, a symbolic link will be created from /usr/laygo to the installation directory.

To remove the package, enter:

# rpm -e laygosdk

The LayGO documentation files are also shipped in RPM format in laygodoc-3.10-1.i386.rpm. Follow the steps shown above and install package laygodoc.

Driver Modules

laygolnxz.o is a dynamically loadable Linux driver module which provides LayGO communication services to Linux applications. (The z in laygolnxz.o is replaced by a single hexadecimal digit 0-f depending on the type of hardware the driver uses.) laygolnxz.o is accessed exclusively through the shared object

Before the driver can be used by an application, it must be installed and loaded into the kernel. A symbolic link must also be created in /dev through which it can be opened. The LayGO drv directory contains a driver installation script. Use this script to install, load and link the driver. (Note: You must be root to run this script.)

To install laygolnxz.o, change to the drv directory and run with the argument install:

# install

This will both copy laygolnxz.o to the /lib/modules hierarchy and add the necessary driver parameters to the /etc/conf.modules file as an options laygolnxz entry. The parameters will be retrieved from this file the driver is loaded. (If you are going to assign a fixed driver identifier, you should do so before executing the install command. See the Linux Device Driver Identifiers section below for details.)

To load laygolnxz.o, run with the argument load:

# load

Once the driver loads, run the script with the argument link. This will create a character special device in the /dev directory through which can access the driver:

# link

The driver is now ready to be used by the LayGO protocol stack.

To remove the entry in the /dev directory, run the script with the argument unlink:

# unlink

To unload the driver, run the same script with the argument unload:

# unload

Finally, to uninstall the module, run the script with the argument uninstall:

# uninstall

This will both remove the module file from the /lib/modules hierarchy and remove the options laygolnx6 entry from the /etc/conf.modules file.

Using laygolnxz.o requires that the proper communication board be installed. A second device driver called laygolnx6.o is also provided. laygolnx6.o is a hardware emulation driver implemented as a character device. When used in place of laygolnxz.o, laygolnx6.o emulates a communication board in software. When laygolnx6.o is configured for internal loopback mode, data written on a line is looped back on the same line. Otherwise, lines 0 and 1 are connected so that signals and data output on one line are received on the other. Since laygolnx6.o emulates the communication hardware in software, it can be used without any communication board installed.

To install laygolnx6.o, become root and run the installation script located in the LayGO drv directory as shown above.

Both the emulation driver and the actual hardware driver can be installed at the same time.

Linux Device Driver Identifiers

Each installed device in a Linux system requires a unique device identifier. This is normally a number in the range of 1-127. The identifier is used to create the entry in the /dev directory which the LayGO protocol stack uses to access the driver. By default, the LayGO driver module uses dynamic allocation of device identifiers, that is, it allows the system to assign it a device identifier at the time it is installed. The assigned identifier is written into the system's /proc/devices file. The link command in the installation script extracts the assigned identifier from /proc/devices to create the required /dev device entry.

Using dynamic allocation of device identifiers, the actual identifier assigned may change each time the driver module is loaded. This means that the /dev device entry would need to be changed as well.

As an alternative, you can manually assign a fixed device identifier. Dynamic allocation selects the highest unassigned idenitifier starting with 127. Identifiers for system drivers are assigned starting with 1. Unload the LayGO driver, then check the /proc/devices file on your system to see which identifiers have been used. For instance:

# cat /proc/devices
Character devices:
 1 mem
 2 pty
 3 ttyp
 4 ttyp
 5 cua
 7 vcs
10 misc

Block devices:
 1 ramdisk
 2 fd
 3 ide0
 9 md

Select an unused identifier from the middle of the range of character devices. In this case, you might select 64. Now edit the installation script and change line 17 from:




Save the change, then install, load and link the driver.

Loading the Driver at Boot Time

You can configure your Linux system to load LayGO driver modules at boot time, so they are immediately available to user programs. The simplest way to do this is to invoke the script from your /etc/rc.d/rc.local file. For instance, to load the emulation driver at startup, you would put the following lines in your rc.local file:

/usr/laygo/drv/ load
/usr/laygo/drv/ link

This assumes that the driver has already been installed in the /lib/modules hierarchy. This only needs to be done once. You do not need to reinstall the driver each time the system boots.

Stack Configuration

In order for the stack to locate the correct driver(s) during stack initialization, a system stack configuration is required. The file stackz.cfg contains a system stack configuration for the laygolnxz.o driver. Applications should load this file by calling lgo_ConfigureStack() prior to initializing the stack. If no system stack configuration is loaded, the emulation driver is loaded by default.

Hardware Configuration

Each LayGO device driver must be configured at runtime using an SDLC hardware configuration. The default configuration for laygolnxz.o is included in the stackz.cfg file mentioned above.

PCI communications boards are self-configuring. Hardware parameters are read from the boards themselves so no changes to the stackz.cfg file should be required.

Non-PCI communications boards must be configured manually. This may require that you edit stackz.cfg to enter the IRQ, IO base address and dual-ported RAM address you have selected. Check the /proc/interrupts file for free IRQs and the /proc/ioports file for free IO base address ranges. (There is no central registry of dual-ported RAM addresses.) Make sure that the values set by jumpers on the board are entered into the SDLC hardware configuration in stackz.cfg using the LayGO edcfg utility located in the LayGO bin directory.

Shared Objects

All LayGO API functions are exported by 2 shared objects: is accessed internally by these objects. contains the X.25 call setup data encoding and decoding functions from call.h, and the X.25 diagnostic and cause code conversion functions from diag.h. contains the device library functions from device.h.

C Language prototypes for all functions are found in the .h files in the LayGO inc directory.

The shared objects are located in the LayGO lib/linux directory. You may want to add /usr/laygo/lib/linux to your LD_LIBRARY_PATH environment variable or copy all the .so files in /usr/laygo/lib/linux to /usr/lib. If you chose to copy the files, be sure to include the -d argument to cp:

# cp -d /usr/laygo/lib/linix/* /usr/lib

This will copy the symbolic links in /usr/laygo/lib as symbolic links. The links are used by ld to assure that the proper version of each shared object is used for each executable which requires it.