README Enea LINX for Linux See RELEASE_NOTES for the current LINX version! 1. Introduction 2. Description and Main Features 3. Licenses 4. Documentation 5. Contacts 6. Build Instructions 7. Example: Start using LINX 8. Trademarks 1. Introduction Enea LINX is an open technology for distributed system interprocess communication which is platform and interconnect independent, scales well to large systems with any topology, but that still has the performance needed for high traffic bearing components of the system. It is based on a well known transparent message passing method that have been used for many years in OSE family of real time operating systems. LINX for Linux is the Linux implementation of the Enea LINX, and includes the LINX kernel modules, the user-space LINX API library and tools for configuring and supervising inter-node communication using LINX. 2. Description and Main Features The LINX kernel module implements the LINX protocol which has two layers - the RLNH protocol and the Connection Manager protocol. The RLNH protocol corresponds to the session layer in the OSI model and implements IPC functions including methods to look up endpoints by name and to supervise them to get asynchronous notifications if they disappear. The Connection Manager layer corresponds to the transport layer in the OSI model and implements reliable in order transmission of arbitrarily sized messages over any media. LINX is accessed from user land through a new address family AF_LINX and standard BSD sockets. The LINX API library implements the Enea LINX message passing API. The API is based on Enea's well know OSE distributed messaging API and contains a full set of functions for sending and receiving messages, lookup endpoints, request notification when endpoints disappears. Although it is possible to write LINX application using only the socket interface published by the kernel module the powerful abstractions provided by the LINX API makes applications much easier to write and maintain. LINX contains tools to create and destroy connections to other hosts and a daemon that can be used to automatically establish connections to a group of LINX hosts in a network. Linxcfg creates and destroys connections to other hosts. Linxstat displays information about LINX-connections and programs using LINX in a format similar to netstat. Linxdisc is a daemon which can discover other LINX nodes in a network and automatically establish LINX connections. The LINX release contains two example programs, a benchmark application that can be used to test performance of LINX and a simple application demonstrating many features of LINX messaging API. 3. Licenses The LINX for Linux source code is released under a dual BSD / GPL licence. * The LINX kernel module is OS-specific, released under GPL for Linux. * The LINX generic protocol layer is released under a BSD licence. * The LINX library is released under BSD licence. See the file COPYING for the GPL licence. 4. Documentation * README This file * RELEASE_NOTES Version information, supported platform and known limitations. * Changelog Change history. * index.html Index to reach all documentation. * UsersGuide_LINX_for_Linux.html Description and getting started information. * MAN-pages Reference documentation of the LINX protocol, the LINX API, and the LINX tools. In order to read these man-pages use the command: MANPATH=/path/to/linx/doc man The MAN pages are also available, converted to HTML and PDF. * README README-files in each example directory. 5. Contacts www.enea.com linx@enea.com 6. Build Instructions See the User's Guide for instructions. In short, to build LINX self hosted, go to the top LINX directory and do make. $ cd /path/to/linx $ make For cross compiling, fist set a few environment variables or update config.mk and set the PATH to include your cross development toolkit: * ARCH - target architecture, e.g. ppc * CROSS_COMPILE - cross tools prefix, e.g. powerpc-linux- * KERNEL - kernel source tree This creates the kernel modules linx.ko, linx_eth_cm.ko, and linx_tcp_cm.ko (located in /path/to/linx/net/linx/), as well as tool binaries located in the /path/to/linx/bin directory. To create the example programs in the example/bin directory, use: $ cd /path/to/linx $ make example. 6.1 Kernel bug workarounds In order to workaround specific kernel bugs, a set of defines are available to patch the LINX code. The workarounds are enabled by defining build time variables. * LINX_KERNEL_WORKAROUND_1 Vanilla kernels earlier than 2.6.12 have a bug in the rwsemaphore handling. The problem is that irqs are not enabled and disabled correctly when using the rwsem interface. When LINX_KERNEL_WORKAROUND_1 is defined, extra irq handling is added. Many distributions, such as Red hat, Centos etc. have patches that fix this problem. $ make LINX_KERNEL_WORKAROUND_1=yes 7. Example: Start using LINX See the User's Guide how to start using LINX. Below is a very short summary how to install, build and start using LINX on two Linux hosts; HostA and HostB. Note that to be able to build the LINX kernel module, headers matching the running kernel must be installed. On HostA untar the LINX archive in some suitable place: $ tar xzf linx-ver.tar.gz Go to the linx directory, build LINX kernel module, LINX API lib and tools: $ cd /path/to/linx $ make $ export PATH=${PATH}:/path/to/linx/bin Load the LINX kernel module into your kernel. Note that you need root permission to install the kernel module. $ sudo insmod net/linx/linx.ko Insert the Ethernet CM: $ sudo insmod net/linx/linx_eth_cm.ko Create a connection to the remote system B $ mkethcon -i eth0 -m 0b:0b:0b:0b:0b:0b econ_b $ mklink -c ethcm/econ_b elink_b Do the same on host B, unpack, build, and install kernel module. Finally create a connection to A: $ mkethcon -i eth0 -m 0a:0a:0a:0a:0a:0a econ_a $ mklink -c ethcm/econ_a elink_a Now applications can send messages over the link. To use the TCP CM, insert the corresponding CM kernel module: $ sudo insmod net/linx/linx_tcp_cm.ko Notice that many CMs can coexist at the same time. On host A create a connection to the remote host: $ mktcpcon -i 192.168.1.B tcon_b $ mklink -c tcpcm/tcon_b tlink_b Do the same on host B: $ mktcpcon -i 192.168.1.A tcon_a $ mklink -c tcpcm/tcon_a tlink_a The applications can use the link. The current available links can be seen with the linxstat command: $ linxstat 8. Trademarks LINX, OSE, OSEck are registered trademarks of Enea Software AB. Linux is a registered trademark of Linus Torvalds. PowerPC is a registered trademark of IBM Corporation. i386 is a registered trademark of Intel Corporation. All other trademarks, trade names or copyrights used in files in the LINX distribution are the property of their respective owners and are used for identification purposes only.