ibcs/HOWTO

$Id: HOWTO,v 1.2 1994/02/28 09:15:25 mike Exp $
$Source: /nfs4/sophia/home/mjagdis/src/ibcs.cvs/ibcs/Attic/HOWTO,v $

LICENSE (well, sort of . . . .)

This is development level code. It is assumed that you received this code
in good faith and that you will honor the trust placed in you by the
developers. Specifically, please do no reveal the location to the development
code to usenet (newsgroups). If you wish to respond to a message requesting
this data, the best solution is to invite them to join the mail list and give
them short instructions on how to do that.

Do not post problems anywhere except the mailing list. Problems about this code
will not be answered if they are received by any other means.

By using this code, you understand and agree that the code has flaws. Programs
which you run under this code should not be __trusted__ to operate properly.
This code has been known to crash the kernel, lock it up, and otherwise 
require a general reset of the computer; resulting in the loss of all work
in progress in other screen groups. (We won't assume responsibility if you
trash your disk because the emulator crashes. Backups are a good thing.)

When the code is ready for release, it will be folded into the released
kernel. At that time, everyone who gets Linux's kernel will get this code.
It will not be a separate piece of software.

If you find this to be un-acceptable then you should wait for the general
release.



MAILING LIST

Since you had previously joined the mailing list to find the location of the
development code, this is only documented for the sake of being complete.

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

[This list _was_ called IBSC2. The list has been renamed.]



CODE LOCATION

Since you obtained this file, you probably know the code location. However,
to be complete, let me state it here as well:

The project code is kept in the directory 
/pub/linux/ALPHA/ibcs2/private/.devel on the system tsx-11.mit.edu.

This directory is "world-writable". This means that you can use ftp to "put"
as well as "get". Files up-loaded to this directory must be made readable. If
you wish to contribute something to the group, then please put the file on
tsx-11 and send a message to either Eric Youndale (eric@tantalus.nrl.navy.mil)
or Drew Sullivan and they will make them readable to the world. After that,
it is a good idea to announce the up-load to the mail list.



GENERAL

This directory contains the iBCS emulator. The iBCS emulator, or Intel
Binary Compatibility Specification, will allow programs written for other
iBCS systems such as SCO and [sic.] Coherent to work under Linux.

This code is under development. (The last three changes were one day
apart. Not even Linus updated code so quickly. :-) If you use the code then
you must accept the fact that it is subject to major revision.

You are welcome to run the code. We do need testers. However, to be a good
tester, you should be like the pilot of a test aircraft. That is you need
to keep good notes as to what you did; your configuration; and what the
results you received. Please try to reduce this as much as possible. (A
memory dump of your SCO Oracle database run is of not much use without the
ability to re-create situation. Try to isolate the problem to as small of
a test case as possible.)

Please see the ToDo list included with the package. It will change over
time as functionality is added and new requirements are determined. We can
use any help that your talents may be employed.

Any change to the iBCS emulator must be sent to Drew Sullivan
<drew@lethe.north.net>. He will coordinate the changes and update the master
copy of the code. You may post the diff patches to the mail list or send it
directly to Drew via Email. Either way, Drew will receive a copy. Please do
not post the article to the list _and_ cc Drew as he will receive two
copies.



INSTALLATION

1. You should tar extract this file into the directory /linux/ibcs. If
you have done this to a separate directory then please move the directory
to /linux/ibcs. This file should then be called /linux/ibcs/HOWTO.


2. Create a symbolic link in /usr/include

ln -s /linux/ibcs /usr/include/ibcs


3. Apply the patches to the kernel (if any supplied).

patch -p0 < kernel.patch

The patches included are for the original ALPHA-pl15h (or later) kernel. If
you have a patched kernel for some other reason, then they will not apply
cleanly. You may either obtain an "un-patched" kernel from nic.funet.fi or
correct the patches by hand. Hopefully, they will not be major.

4. 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.

Instructions on how to make the kernel are included in the /linux/README
file.

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

6. Boot that 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 SCO or iBCS2 programs.



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 enter the command:

cc -N -o trace -fomit-frame-pointer trace.c

To use the program, enter the command:

trace 1     to enable the trace function or
trace 0     to disable the trace function.

The result code from the program is the previous setting of the trace event.
This is probably of no use to anyone who is not writing a script, but that
is the meaning of the result code if you are curious.



LIBRARIES

The shared libraries are on the list of ToDo. The libc file is being
developed by Eric Youndale and me. At the present time, the only way that
you can use applications which use a shared library is to include the
shared library from your iBCS system on Linux.

The shared libraries are stored in the directory

/shlib

The libraries are:

libc_s   - standard C runtime library.
libns_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. It is probably not much of
concern as the three libraries listed above are the only ones which are
specified in iBCS specification.

The source for the libc_s library is in the development directory on
tsx-11.mit.edu. Instructions on building the library are in that package.
At this time, the library will build but the test programs which I am using
do not run. So, until I can get the programs run run correctly, stick with
the SCO (or whatever) library that you have.


LIMITATIONS

Until the network services shared library is implemented, the network
programs probably will not work. 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.

Until the X library is implemented, 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. :-)



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

(When I purchased the book around August '93, it cost $40US.)


AUTHOR

Please direct all flames, love letters, comments, corrections, etc. to this
"document" to Al Longyear (longyear@sii.com). [I am the "I" and "me".]

--
Al Longyear              longyear@netcom.com           longyear@sii.com