

Sparc x-kernel Simulator
------------------------

This file is the README file for the Sun4 version of the
xkernel simulator.  It contains a list of changed files,
information on configuration and execution of the simulator,
and a description of known simulator problems.

There are two alternatives for using this version of the
simulator. First, this tar file provides a standalone
version of the xkernel system for the Sparc.  It can be run 
without any changes or additional files from the full 3.1 
distribution version of the xkernel.  It currently has enough 
of the protocols to run eth, ip, and udp.  If you intend to stay
in this new directory, you should be able to bring additional
protocols over from an existing 3.1 /usr/xkernel/protocols area
without modification.

Alternatively, the files in this directory can be merged 
back into an existing /usr/xkernel directory (without too much
trouble).  If this approach is taken, then the changed files outlined
in the "Files provided ..." section below need to be replaced
in an existing 3.1 xkernel directory.  

In what follows, the path /usr/xkernel is used to mean either
this distribution in standalone /usr/xkernel.sparc, or the
merged version in /usr/xkernel.


Files provided with the Sparc x-kernel Simulator
------------------------------------------------

This tar file contains all of the xkernel code necessary to run the
xkernel simulator on a Sun4.  It also has enough of the protocol
code to support ethernet, ip, and udp communication.  Although the
libraries are supplied for completeness, there are no significant
differences between library files across architectures.  There
have been several important changes required to support the sparcs.
If you are going to merge this code back into an existing /usr/xkernel
directory, you need to update the following:

/usr/xkernel/sunos:

	This directory is the sparc version of original simul directory.
All files in this directory are needed for the sparc simulator.


/usr/xkernel/share:

	In the share directory, changes have been made to the 
event manager. The changes involve the file:

	event.c

	minor declaration changes in:
		system.h
		nmessage.h
		upi.h

/usr/xkernel/protocols:

	In the protocols directory, the following two files were altered
to support the new internet versions of the rom files:
	
	ip.c
	sim_ether_i.h
	arp.c
	sim_ether.c
	unixudp.c


Configuring the Sparc x-kernel Simulator
----------------------------------------

The following is an abbreviated description of how to configure
an xkernel simulator for the Sparc.  A more complete description
can be found in the xkernel manual (version 3.1).  The following
configuration process will result in a version of the xkernel
which runs a simple client/server UDP timing test.

1. Put the /usr/xkernel/bin (or /usr/xkernel.sparc/bin) directory 
	into your path - before other bin directories.

2. Create a working directory to hold your kernel: 

	cd /usr/xkernel; mkdir yap

3. cd yap

4. To configure a simulated Sparc xkernel, copy the Makefile from 
	/usr/xkernel/sunos into your configuration directory:

	cp ../sunos/Makefile .


5. Create directories for object code (will generate error messages
	if run more than once):

	make setup

6. Create a file named graph.comp to specify the desired protocols
	to be configured into your kernel. To run the sample udp protocol
	copy the file ../sunos/graph.comp into the current directory.

	cp ../sunos/graph.comp .

   The following two steps must be repeated if graph.comp is later
	modified.

7. Generate protocol initialization code:

	make compose

8. Establish Makefile dependencies:

	make depend

9. To run the sample udp protocol, copy the file ../usertest/timeudp.c
	into the User directory:

	cp ../usertest/timeudp.c User/user.c

10. Make the final xkernel executable:

	make


Running the Sparc x-kernel Simulator
------------------------------------

As as result of configuring a kernel, a file named xkernel should exist
in your current directory (/usr/xkernel/yap).  While in this directory,
create a sub-directory for each host you want to simulate.  To run
the udp test type:

	mkdir server
	mkdir client

In each of these directories, create a file called rom. The format for
rom files has changed slightly from previous releases of the xkernel. In
this version it is now possible to use the simulator across the internet.
Two sample rom files for the udp test are provided in ../usertest/server
and ../usertest/client.

The following are example rom files that might be contained in client
and server respectively.

client:
	eth  3098  0  0
	arp  127.12.69.1  192.12.69.5   3098
	arp  127.12.69.2  192.12.69.62  3099

server:
	eth  3099  0  0
	arp  127.12.69.2  192.12.69.62  3099
	arp  127.12.69.1  192.12.69.5   3098

The first line in each file must be an entry for the simulated ethernet
driver.  It contains the UDP port number on which this simulated host will
receive network packets.  2 zeros MUST follow this port number.
The second and third lines are used to initialize ARP's address mapping 
table.  The second line gives the simulated IP address for THIS simulated
host, while the third line gives the address for the other host.  For a
given host's entry, the four fields are:

	"arp" <simulated IP addr> <actual host IP addr> <UDP port>

This allows you to use any actual host on the internet as one of the
simulators.  Previous versions of the simulator were restricted to the 
local network.  You must edit the rom files so that they reflect
the actual network IP address of your hosts.

Each simulated host runs as a separate Unix process. It is convenient if 
this process is started from a different window, i.e. one window per
simulated host.  For each simulated host, cd to the sub-directory that
contains that host's rom file.

In the case of the udp timing test, on the server execute the following:

	cd server
	../xkernel -s

On the client execute the following:
	
	cd client
	../xkernel -c127.12.69.2            (provide server sim address)


To stop a simulated host, type DELETE or CTRL-C.


Known Problems with the Sparc x-kernel Simulator
------------------------------------------------

One feature of the Sparc simulator is that it is currently compiled
with Sun's cc compiler.  This is done to avoid problems which arise
when structures are passed by value between gcc and cc compiled
functions. We will be looking into removing this restriction in the
near future.

There is one known problem with the Sparc version of the xkernel
simulator.  Under certain circumstances, it is possible that a process
which executes a delay will never wake up.  Because the event 
manager also uses this primitive, it is possible that a registered
event will never be triggered.  The current belief is that this is
due to a dropped SIGALRM in lwp_sleep.  This too is being investigated.

