freebsd/sys/i386/ibcs2

What it is
==========

This is a project that Sean Eric Fagan (sef@kithrup.com) started, and
Soren Schmidt (sos@login.dknet.dk, author of syscons) picked up.  It allows
SYSVr3.2 i386 binaries (iBCS2 compatible) to run under FreeBSD-2.0.
We haven't been able to do an exhaustive test, of course, but we are able 
to run at least the following programs:

	ISC 2.2 	sh, vi, dd, date, wc, chmod, etc. 
			
	SCO 3.2v2 	runs most (coff) utils on a chroot'ed filesystem
			Informix-2.10, gcc, bash, tcsh ....

	SCO 3.2v4 	sh, gzip, GNU make, tcsh

Some of those, for both ISC and SCO, used the shared libraries that are 
available for those systems.  Currently, the only way to run them, is to 
get a copy of the shared libraries in question (e.g. /shlib/libc_s).
There might be a way to generate them from a package available for Linux, 
but we haven't had the time or energy to do it ourself, and the last call
for volunteers resulted in nothing.  If someone else wants to volunteer, 
we would be grateful.


How to get it into the system
=============================

There are two ways of getting iBCS2 support into the system. One is to use
Loadable Kernel Modules (LKM) to put it into the kernel at run-time. This
demands a kernel compiled with:

	options "COMPAT_IBCS2"

This puts in the nessesary hooks to let the iBCS2 support do its thing.
One loads the iBCS2 support by using the command 'ibcs2' (in /usr/bin).
You can use 'modstat' to see the loaded modules.

Another way is to compile it into the kernel. This is accomplished using:

	options "COMPAT_IBCS2"
	options "IBCS2"

in the kernel config file.


Where's what
============

The ibcs2 package consists of quite a few files located in ./sys/i386/ibcs2.
Here is a brief description of them:

ibcs2.h:	Basic header file defines iBCS2 types etc.

ibcs2_dummy.c:	Stubs to system calls not yet supported, or not feasible
		to emulate.

ibcs2_ioctl.c:	Probably the single-most complicated part of it, this deals 
		with translating as many ioctl calls as possible between 
		BSD and iBCS2.

ibcs2_misc.c:	This has all of the wrapping routines that were thought 
		"easy" (at least initially) or that didn't fit anywhere else.

ibcs2_file.c:	Functions that deals with file I/O, such as getdents and read
		which are more complex than one should expect.

ibcs2_signal.c:	This deals with the signal cruft, including both system 
		calls and signal translation.  

ibcs2_stats.c:  This has all of the filesystem statistic wrappers 
		(stat, fstat, statfs, etc.).

ibcs2_sysent.c:	This has the system call table for iBCS2 programs, and is 
		NOT generated automatically.

ibcs2_ipc.c:	Stubs for the iBCS2 ipc calls (shm, msg, sem).

ibcs2_isc.c:	This deals with the ISC specific system call (cisc()).

ibcs2_sysi86.c:	This deals with the i86 specific system call (sysi86()).

ibcs2_xenix.c:	This deals with the Xenix specific system call (cxenix()).
		(This also has some of SCO's POSIX-conformant functions.)

imgact_coff.c:  This is the functions that alllows the kernel to load 
		COFF programs. It also deals with shared library loading.

There also exist two files (ibcs2_socksys.[ch]) which contains a proto
implementation of the SYSVr3 socket system, donated by Mostyn Lewis 
(mostyn@mrl.com). It has not been tested much but is included as a basis
for network support, which is nessesary to run X and the likes.


What's Next
===========

Much needs to be done yet, mainly the socksys emulation should be looked
at to get socket support going.  There currently also is no ipc support.
The sem & msg functions should map fairly easy to the BSD ones, but our
current BSD shm implementation is not even close to SYSV behavior, if it 
works at all. 
We currently have loaders or "image_activators" for other binary formats,
but none of them is really usefull yet (xout, elf).
Also most of the wrappers for the extra syscalls used by SYSVr4 has been
done, but not much testing yet because of lacks in the elf loader (but it
will run a statically linked SYSVr4 shell).

All the wrappers should be tested one by one using every aspect of use 
by the iBCS2 system.  The tests we have done so far is to run small 
testprograms to check a limited set of the emulation.  When this proved 
that the basics was functional, we tried with what iBCS2 programs where 
at hand.  This is by no means an exhaustive test or to say that the 
emulation is errorfree, only a statement of overall functionality of 
the emulator. 

Surely much work can be done here, but we are both kind of lazy, and did 
the whole thing just for the fun of it, and mainly as a "can it be done"
project. 

	Soren Schmidt 		(sos@login.dknet.dk)
	Sean Eric Fagan 	(sef@kithrup.com)