                       iBCS Emulation for Linux


The Intel Binary Compatibility Specification, or iBCS, specifies the
interfaces between application programs and the surrounding operating
system environment for i386 based systems. There are however several
flavours of iBCS in use - SVR4, SVR3 plus several vendor specific
extensions to SVR3 which are slightly different and incompatible. The
iBCS emulator for Linux supports all flavours known so far.


SUPPORTED BINARY FORMATS

	* ELF
	* COFF
	* XOUT (Xenix 386 only)


SUPPORTED OS EMULATIONS

	* SVR4 (Unixware, USL, Dell etc.)
	* SVR3 generic
	* SCO (SVR3 with extensions for symlinks and long filenames)
	* Wyse V/386 (SVR3 with extensions for symlinks)
	* Xenix V/386 (386 small model binaries only)

Unrecognised binaries will default to the SVR4 personality for ELF or
the SVR3 personality for COFF binaries. If there are non-standard
extensions which require handling a new personality will need creating
in the emulator.


SUPPORTED SUBSYSTEM EMULATIONS

	* SYSV IPC

	* /dev/socksys socket interface as used by the Lachman STREAMS
	  based networking implementation.

	* Wyse V/386 system call socket interface.

	* /dev/spx STREAMS device for connections to local X server 0 *only*.


LIMITATIONS

Unix variants with non-standard extensions which are not SVr4, SCO or Wyse
will not be recognised and may fail unexpectedly. A new personality would
need to be built.

The recognition of SCO and Wyse binaries is dependent on comment strings
embedded in the binary at compile time. If these strings are missing or
not as expected the binary will not be recognised correctly and may
fail unexpectedly. It is also possible that binaries from other systems
may be misrecognised although given the strings used this should be
unlikely.

Support for x.out format binaries is very new. Only Xenix 386 small
model binaries are supported. Some Xenix functions are unimplemented,
in particular Xenix semaphores.

The SCO support for connections to a local X server only extends to :0.0.
If necessary you can connect to other servers by forcing the connection via
the TCP/IP loopback interface. This is done by specifying the DISPLAY
environment variable as localhost:0.0.

SVr4 local connections are made using the same named pipes that linux
uses.  SVr4 networking should be working if you use the libnsl.so and
libsocket.so shared libraries that come with the libc_s package.

There is no support for TLI networking. If anyone can think of a good
reason why TLI is necessary it *may* be possible to do something...

There is no STREAMS support. Programs that rely on STREAMS features and
functionality will not work.

Programs, applications or packages which require modules or device drivers
to be linked in to the kernel will not work. Linux is *not* based on SYSV
code and does not have SYSV internals. The driver would need rewriting for
use under Linux.


MAILING LIST

The mail list for this project is located at:  linux-activists@joker.cs.hut.fi.
Please send all messages to this location. Either include in the header
or as the first line of the message the following:

X-Mn-Key: IBCS2


INSTALLATION

1. Extract the archive (you have already done this of course). If you
   intend to link the emulator directly to the kernel image you must
   place this tree under /usr/src/linux/ibcs (or whereever you keep
   your kernel sources). If you intend to build the loadable module
   version of the emulator (recommended) it doesn't matter where you
   put this source. To load the loadable module version of the emulator
   you will need the "insmod" program from the modutils archive
   available on all major Linux archive sites.

2. Apply the kernel patches if you are using a 1.0 kernel (read them
   first - the patch file is annotated). Not patches are required for
   kernels 1.1.15 and later. If you are using an earlier 1.1 kernel
   you should upgrade it. The 1.1 series is a development kernel and
   liable to frequent bug fixes. Non-current releases of 1.1 will *not*
   be supported!

	# patch -d /usr/src/linux -p1 < Patches/kernel-1.0.pat

   If you have the emulator source extracted in /usr/src/linux/ibcs you
   will get a failed patch for emulate.c. Ignore this. This is only
   required for the emulate.c that comes with the kernel originally and
   then creates the hooks for the loadable module to attach to. The sources
   supplied with the emulator do not need this patch.

3. Make the kernel. If you have answered 'y' to the iBCS support question
   during the 'make config' for the kernel the iBCS emulator will be linked
   to the kernel. If you answered 'n' then the kernel will be built with
   hooks for the iBCS loadable module to attach itself and the iBCS loadable
   module will be created in the ibcs directory. It is recommended that you
   get the modutils tools and use the loadable module rather than linking
   to the kernel.

   Note that the 1.1.15 and later kernels have no support for a linked in
   iBCS emulator - you can only build the loadable module version and
   load it with 'insmod'.

   Instructions on how to make the kernel are included in the README file
   in the Linux kernel source directory.

4. Install the kernel. Use either LILO or a separate diskette.

5. The interfaces to some subsystems occur at the device layer and thus
   you need to create some device files in order to use them:

	* /dev/socksys - interface for SVr3 STREAMS based TCP/IP applications

	  # mknod /dev/socksys c 30 0

	* /dev/X0R - server side of SVR3 local X interface
	  (see comments in Doc/Local-X)

	  # ln -s /dev/null /dev/X0R

	* /dev/spx - client side of SVR3 local X interface
	  (see comments in Doc/Local-X)

	  # mknod /dev/spx c 30 1

6. Boot the new version of the kernel.

7. If you are using the loadable module version of the iBCS emulator
   load it using 'insmod iBCS'.

8. Run the SVr4, SCO or iBCS2 programs. Pay attention to the COMPAT
   file, the HINTS file and any patches that may be in PROD.Patches.
   Just because they are commercial doesn't make them perfect :-(.


UTILITIES

The emulator has the ability to trace the events which it processes. The
program to enable the tracing function is contained in the Tools directory.

To make the trace utility, go to the Tools directory and do a make.

Run 'trace' with no arguments to get a list of capabilities. Full tracing
is enabled using 'trace all'. This is extremely verbose - you probably
want to kill syslogd and use 'tail -f' to dump /proc/kmsg directly to
a file as quickly as possible if you enable this.

If you have no intention of ever using the trace facilities (and will
never complain that something doesn't work) you can remove the IBCS_TRACE
option and recompile the emulator without the tracing facilities. This
makes the emulator about a third smaller but ensures that there is no
way for you to find out if program failures are directly due to faults
in the emulator.


LIBRARIES

The shared libraries are on the list of ToDo. The libc file is being
developed by Eric Youndale and Al Longyear. At the present time, the
only way that you can use applications which use a SCO shared library
is to include the shared library from your iBCS system on Linux. It is
your responsibility to check whether your license allows you to do
this whether directly or via NFS.

For SVr4 binaries, precompiled libraries build from this library
should be available that will work for many applications.

The SCO shared libraries should be stored in the directory /shlib. This
may be a symlink elsewhere.

The libraries are:

	* libc_s   - standard C runtime library
	* libnsl_s - network services library
	* libx11_s - X windows library

Additional libraries may be available on your system. They may be called
SCOlibc_s or some similar name. Those libraries will not be available for
Linux. They are specific to the SCO system. The three libraries listed
above are the only ones which are specified in iBCS specification.

SCO has the following shared libraries:

	* libc_s	- standard C runtime library
	* libnsl_s	- SCO version of network services
	* libnsl_s.att	- AT&T version of network services
	* libsc_s	- console functions???
	* protlib_s	- SCO specific security functions
	* libX11R5_s	- X windows libraries
	* libXR4sco_s
	* libXtXm1.2_s
	* libXtXm114_s
	* libXtXm_s

On SVr4 machines, the shared libraries tend to be stored in /usr/lib,
and are called libc.so.1, libsocket.so, and libnsl.so.  You can use
environment variables to specify alternate locations for these files.
The SVr4 versions of these libraries must be built on a SVr4 machine
since the GNU linker and assembler do not support ELF shared
libraries.  The SVr4 X11 libraries are not part of this package, but
precompiled libraries for X11 can be obtained from the binary sites
for XFree86.

The source for the libc_s library is in the development directory on
tsx-11.mit.edu. Join the IBCS2 mailing list if you wish to work on
unreleased development code.


BUG HUNTING

If you find a program which produces warnings about unsupported syscalls
or ioctls please look at available header files and/or man pages and
try and identify what should be happening. If we know what the program
expects to happen we can emulate it.

If you find a program which runs but crashes at some point then try and
reproduce the problem. Once you can crash it at will you can generate
a trace of the relevant section. Run the program and bring it to a point
a little before it crashes then enable tracing in the emulator and dump
the trace to a file by running (on a different VT or xterm):

	# killall syslogd syslogk klogd
	# dmesg -c > /dev/null
	# tail -f /proc/kmsg > /tmp/log &
	# .../ibcs/Tools/trace all

Then do whatever it is that causes the crash, disable the emulator tracing
and kill the tail:

	# .../ibcs/Tools/trace off
	# killall tail

and examine the log.

If you can fix the problem do so and post the fix to the IBCS2 mailing
list, otherwise post the *relevant* details you have - parts of the log
file, ioctl details, syscall details etc. Remember, it's better to post
too little initially and then post further details when asked than it
is to post too much and annoy people who may be able to help!


LIMITATIONS

Until the COFF network services shared library is implemented, the
network programs probably will not work with COFF binaries that are
linked to the shared libraries. There is some network code in the
emulator.  This allows the Wyse iBCS system to work with the
network. If you wish to try other systems, then please do so. A lot of
work has been done in the network area as far as the emulator is
concerned. Please let us know about the results.

SVr4 binaries tap into the Wyse TCP/IP code, and should be completely
functional WRT the network.

Until the COFF X library is implemented, COFF X windows applications
_probably_will_ _not_work_ on this system. Mike Jagdis has reported
that he can get the X version of WordPerfect to work on his system. It
does not use shared libraries. There is hope. :-)

For SVr4, you can obtain the X11 shared libraries from the binary
distribution sites of XFree86.


LOCAL X CONNECTIONS

The local X interface is simplistic. It assumes only one local X server
exists and assumes that the pathname of the Unix domain socket for
local connections is always /tmp/.X11-unix/X0.

  The SCO code opens both /dev/X0R and /dev/spx, writes a single byte
to /dev/X0R, reads a message from /dev/X0R with getmsg then writes this
message to /dev/spx with putmsg and closes /dev/X0R. This establishes
the /dev/spx file descriptor as a connection to the X server listening
on /dev/X0R.

  We ignore all activity on the /dev/X0R device (hence it is a link to
/dev/null), getmsg and putmsg are stubbed so don't do anything and opens
on the /dev/spx simply replace the open inode with a socket connected
to the X server's Unix domain socket.

  At some point in the future we will implement a simple minded /dev/X*
driver that returns some form of id via the getmsg which can then be
passed to /dev/spx with putmsg and which will allow /dev/spx to connect
to the relevant X server. This will only happen if someone actually
*needs* multiple local X servers...
 

REFERENCES

The Intel Binary Compatibility Specification, version 2 is described in
the "McGraw Hill book".

	Intel Binary Compatibility Specification
		McGraw-Hill, Inc.
		1221 Avenue of the Americas
		New York, NY 10020
		ISBN 0-07-031219-2

Vendor specific extensions were determined through a combination of
header files, man pages, manuals and the behaviour of existing programs.
To the best of my knowledge no developer of the iBCS emulator has ever
had access to controlled Unix source - never mind used it as a reference.
To be honest it probably wouldn't have helped...
