ChorusOS 4.0.1 Simulator for the Solaris Operating Environment (SPARC Platform Edition) User's Guide

Running the ChorusOS 4.0.1 Simulator

This chapter describes how to configure and run the ChorusOS 4.0.1 simulator. It begins by describing what IP addresses must be chosen to access the simulator from your host, then presents a series of steps to get you quickly up and running, before going into further detail about each step.

If you have not created a simulator system image, please refer to the "Building the ChorusOS Simulator" section in the ChorusOS 4.0.1 Simulator for the Solaris Operating Environment (SPARC Platform Edition) Target Family Guide for details.

Planning Your Configuration

The following IP addresses must be selected to allow hosts to access one or more ChorusOS simulators:

A ChorusOS sub-network IP address for the ChorusOS sub-network which groups simulators running on the same host. Routing is achieved through comparisons with a netmask which must be selected according to IP routing rules. Contact your system administrator for help with selection if you are unsure.
A Solaris Ethernet pseudo-driver IP address. This address must belong to the ChorusOS sub-network and is used by simulators to access their supporting host.
A ChorusOS simulator instance IP address for each simulator in the ChorusOS sub-network that will run on your Solaris host. This address is used to access simulators from their supporting host and remote hosts. It is configured in the site configuration file, site_number.conf. See the site_number.conf(4CC) man page for more information.

An example configuration of a Solaris host with a IP address of 1.11.7.1 follows. Each simulator, in addition to the Solaris Ethernet pseudo-driver, is on a class A network, with a netmask of 0xff000000.

ChorusOS sub-network IP address: 2.0.0.0.
Solaris pseudo-driver IP address: 2.1.1.1.
ChorusOS simulator instance IP address: in the range 2.1.1.2 to 2.254.254.254.

These settings will be used in the next section.

Note -

If you run your simulator on the same machine as your host and do not communicate with other machines on your network then the same ChorusOS sub-network IP address can be used again by other hosts and simulators. It does not need to be declared to the rest of the network, a non-trivial task involving your system administrator.

See "Accessing the Simulator from Remote Hosts" for more information.

Getting Started Quickly

Follow the procedure below to get quickly up and running with one or more simulators on a single host. References to later sections provide links to further information about each step.

Create a file called site_number.conf in the /usr/local/chorus/simu_admin directory with the following lines:
```
   1    hostname    2052    2.1.1.2
2    hostname    2053    2.1.1.3
```
hostname is the name of your Solaris host.

See "Enabling Dynamic Configuration" for more information.

Create a file called simudrv.conf also in the /usr/local/chorus/simu_admin directory with the following line:
```
   2.1.1.1    hostname
```
hostname is the name of your Solaris host.

See "Configuring the Solaris Ethernet Pseudo-driver" for more information.

Within the sysadm.ini file in the build_dir/conf directory:
- Find the comment # Using ifconfig then add the following line on the next line:
```
   ifconfig ifeth0 TAG.TGT.IPA.TAG netmask 0xff000000 broadcast 2.255.255.255
```
  See "Configuring the Simulator IP Address" for more information.
- Add the following line on the line after:
```
   route add default 2.1.1.1
```
  See "Configuring the Gateway for the Simulator" for more information.
- Find the line rarp ifeth0 then comment out the rarp command by adding a hash to the beginning of the line:
```
   #rarp ifeth0
```

If you wish to communicate with your simulator remotely from another machine, configure IP forwarding by entering the following command on your Solaris host with super-user privileges:
# ndd -set /dev/ip ip_forwarding 1
See "Configuring IP Forwarding for Your Host" for more information.

Change to the Solaris Ethernet pseudo-driver sub-directory:
$ cd install_dir/tools/host/simu_drv
Launch the Solaris pseudo-driver by entering the following command on your Solaris host with super-user privileges:
# sh simudrv start
See "Running the Solaris Ethernet Pseudo-driver" for more information.

Change to your build directory and build a simulator system image:
$ make chorus

Start the simulator using the loader command:
$ loader chorus.RAM 1
See "Booting the Simulator System Image" for more information.

You can run a second simulator with the following command:
$ loader chorus.RAM 2
You can run additional simulators by adding entries to site_number.conf and using the loader command to start each simulator.

Test that the simulator can be reached from the supporting Solaris host with the ping command:
$ ping 2.1.1.2
You should receive the message 2.1.1.2 is alive.

Test that the supporting Solaris host can be reached from the simulator with the ping command:
$ rsh 2.1.1.2 ping 2.1.1.1
If you receive the message 2.1.1.1 is alive, you can start developing applications on the simulator as you would on a physical target.

Enabling Dynamic Configuration

The ChorusOS 4.0.1 Simulator for the Solaris Operating Environment (SPARC Platform Edition) architecture makes it possible to run multiple instances of the same system image. This requires a dynamic configuration at load time, which makes use of the UDP port for remote IPC communication and IP addresses for Ethernet communication.

To enable dynamic configuration, a site configuration file is required to identify each simulator. By default, this file must be named site_number.conf and placed in the /usr/local/chorus/simu_admin directory. You can override the default pathname by setting the CHORUS_SITE_NUMBER_FILE environment variable before launching the ChorusOS Simulator.

Each simulator must be assigned an instance number at boot time, which acts as an index to entries in the site configuration file, each of which defines:

The hostname of the host system on which the simulator instance runs.
The UDP port number used by the simulator instance for remote IPC.
The IP address assigned to the simulator instance.

Here is the format of each entry:

instance_number  hostname  UDP_port  IP_address

Where:

instance_number is a number between 1 and 254 used to reference an instance of the simulator.
hostname is the name of your Solaris host.
UDP_port is a UDP port number used for the remote IPC mechanism.
IP_address is an IP address that will be used for simulator configuration.

Here is an example site configuration file:

#
#   Site configuration file
#
1    server1    2052        2.1.1.2
2    server2    2053        2.1.1.3

A valid IP address is mandatory. This address is used to access the simulator from the supporting Solaris host and remote Solaris hosts.

Configuring the Solaris Ethernet Pseudo-driver

Create the file simudrv.conf in the /usr/local/chorus/simu_admin directory. This file must contain the IP address that will be attributed to the Ethernet pseudo-driver, and the name of the host on which your simulator is running. For example:

2.1.1.1        jericho

Running the Solaris Ethernet Pseudo-driver

Change to the Solaris Ethernet pseudo-driver sub-directory:

$ cd install_dir/tools/host/simu_drv

Launch the Solaris pseudo-driver with super-user privileges:

# sh simudrv start

Use the ifconfig command to ensure the driver is running correctly:

$ ifconfig -a

The output should include:

...

simu0: flags=863<UP,BROADCAST,NOTRAILERS,RUNNING,MULTICAST> mtu 1500
     inet 2.1.1.1 netmask 0xff000000 broadcast 2.255.255.255
         ether 20:20:0:0:1:0

...

This output will not be exactly as listed. It will vary depending on the configuration.

Configuring the Simulator IP Address

The simulator IP address is set with the ifconfig command which assigns an address to a network interface.

Add the following line to your sysadm.ini file in the build_dir/conf directory:

ifconfig ifeth0 TAG.TGT.IPA.TAG netmask netmask broadcast broadcast

netmask is the netmask corresponding to the ChorusOS sub-network, and broadcast is the broadcast address corresponding to the ChorusOS sub-network.

Comment out or remove the rarp command as the ifconfig command replaces it.

Here is an example of the ifconfig command:

ifconfig ifeth0 TAG.TGT.IPA.TAG netmask 0xff000000 broadcast 2.255.255.255

When you boot your system image with the loader command, the TAG.TGT.IPA.TAG IP tag is replaced by the IP address you registered in the site configuration file.

Every reference to the IP tag in the sysadm.ini file is replaced. This allows you to build one ChorusOS system image for every simulator running on the same host instead of having a different system image for each IP address.

You can also specify the IP address directly instead of using the IP tag, but this option offers less flexibility.

Note -

Remember to rebuild your system image after modifying sysadm.ini.

Configuring the Gateway for the Simulator

A gateway is a device that enables data to flow between different networks. The gateway is configured using the following command on your simulator:

$ rsh simu_address route add default host_address

simu_address is the IP address of your simulator instance. host_address is the IP address of your Solaris host in the ChorusOS simulator sub-network, which is also the IP address of the Ethernet pseudo-driver.

Here is an example:

$ rsh 2.1.1.2 route add default 2.1.1.1

The route command can also be included in your sysadm.ini file, as well as executed on the local console.

Note -

Simulators can only access their supporting host through the IP address of the Ethernet pseudo-driver. They cannot access their supporting host through its standard IP address.

The mount command must be run as follows:

$ rsh simu_address mount host_address:/pathname /

Here is an example:

$ rsh 2.1.1.2 mount 2.1.1.1:/build_dir/root /

See the ChorusOS 4.0 File System Administration Guide for more information about mounting file systems through NFS.

Configuring IP Forwarding for Your Host

A host supporting one or more ChorusOS simulators must be configured to allow IP packets to be forwarded to simulators on the ChorusOS pseudo-network. The forwarding option allows your host to forward any IP packet coming from its Ethernet controller to the Ethernet pseudo-driver. This is required if you want remote machines to access ChorusOS simulators, as well as allowing ChorusOS simulators to access remote machines.

To activate the forwarding option at boot time, create an empty file called /etc/gateway. After you reboot, forwarding will be activated automatically.

If you do not wish to either activate the forwarding option at boot time, or reboot your host, enter the following command with super-user privileges:

# ndd -set /dev/ip ip_forwarding 1

Booting the Simulator System Image

When the configuration file has been created, boot the simulator with the loader command.

Make sure your PATH has been set correctly to include the directory install_dir/tools/host/bin.

Start the simulator by loading it into memory with the loader command:

$ loader chorus.RAM instance_number

Where instance_number is the number of the simulator you have configured in the site configuration file.

The following messages are displayed on the standard output:

   Loading chorus.RAM at 0x40000000 (1073741824)
IP address : 1 tag occurence(s) patched
ChorusOS is booting ...
Reading site configuration file ...

ChorusOS r4.0.1 for Unix - Solaris/Sparc
Copyright (c) 1999 Sun Microsystems, Inc. All rights reserved.
 
Kernel modules : CORE SCHED_FIFO SEM MIPC IPC_L MEM_FLM KDB FAULT_KDB TICK MON ENV
ETIMER LOG LAPSAFE VTIMER MUTEX EVENT UI DATE PERF TIMEOUT LAPBIND DKI 
MEM: memory device 'sys_bank' vaddr 0x40180000 size 0x148000
/UnixClock: clock -- resolution = 1000 nano-seconds
/UnixClock: simulator:solaris-timer driver started

/sigio/pseudoEther: sun:pseudo-ether driver started
/sigio: simulator:solaris-sigio driver started

/unixrtc: unixrtc-(rtc) driver started
TICK: warning -- timer device assigned to the system-tick not found
TICK: timer[0] (UnixClock) device is used for the system-tick
IOM: SOFTINTR DISABLED (-31). Using an Interrupt thread
IOM Init cluster space from: 0x400ad000 to: 0x400ed800 [129 items of size: 2048]
IOM Init io-buf pool from: 0x400ed890 to: 0x400eddb0 [8 items of size: 164]
IOM Init raw io-buffer pool from: 0x400eddb0 to: 0x400ef230 [32 items of size: 164]
Copyright (c) 1992-1998 FreeBSD Inc.
Copyright (c) 1982, 1986, 1989, 1991, 1993
        The Regents of the University of California.  All rights reserved.

max disk buffer space = 0x10000
/rd: sun:ram--disk driver started
C_INIT: started
C_INIT: /image/sys_bank mounted on /dev/bd01
C_INIT: found /image/sys_bank/sysadm.ini
C_INIT: executing start-up file /image/sys_bank/sysadm.ini
iomMakeDevHandler name = ifeth
bpf: ifeth0 attached
IOM: ifnet ifeth0 bound to device /sigio/pseudoEther
iomMakeDevHandler name = lo
bpf: lo0 attached
iomMakeDevHandler name = bpf
iomMakeDevHandler name = bpf
add net default: gateway 2.1.1.1
ifeth0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
        inet 2.1.1.2 netmask 0xff000000 broadcast 2.255.255.255
        ether 20:20:00:00:00:0c 
lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
        inet 127.0.0.1 netmask 0xff000000 
C_INIT: rshd started

Note -

If you have more than one simulator running under the same instance number, the following error occurs:

/sigio/pseudoEther: error -- /dev/simu1 ioctl(ETHER_SET) failed (22)

The solution is to stop every instance of the simulator and run it again.

Accessing the Simulator From Your Host

Test that the simulator can be reached:
$ ping simu_address simu_address is alive
Where simu_address is the IP address you configured for this simulator.

A message indicating that the simulator is working is displayed.

Use the share command to check that your build directory is available for mounting by remote hosts:
$ share - /build_dir rw ""
If your build directory is not shared, see "How to Mount and Unmount File Systems" in ChorusOS 4.0 File System Administration Guide for information on how to do this.

Create a root file system for your simulator in the build directory where you build system images:
$ make root ...

Attach the root file system of the simulator instance to your build directory:
$ rsh 2.1.1.2 mount 2.1.1.1:/build_dir/root / 2.1.1.1:/build_dir/root on / (nfs)
The following error will occur if the build directory cannot be accessed due to the lack of access permission:
```
   can't access /build_dir/root: Permission denied
```
To investigate this problem, check that the file system is mounted for access by everyone:
# share - /export/home rw=local "Local Disk"
Here, the file system is only available to members of the netgroup called local. To make the directory available from any machine, type the following command:
# share /export/home # share - /export/home rw ""

Issue the ls command to check that the simulator can be accessed from your machine:

$ rsh 2.1.1.2 arun ls /
started aid = 2
Makefile        dev             image           tmp
bin             etc             lib

Accessing the Simulator from Remote Hosts

If forwarding is configured, any ChorusOS simulator located on your host can be reached remotely from any another machine supporting an IP stack. As ChorusOS simulators are only accessible through their supporting host, the IP routing protocol of the remote host must be configured to use the supporting host as a gateway for access.

Figure 2-1 shows the IP addresses of a configuration with two hosts, A and B, each running three simulators.

Figure 2-1 IP Configuration With Two Hosts

On each host, routing is configured using the following command with super-user privileges:

# route add -net sub-network hostname

sub-network is the ChorusOS IP address of the sub-network, and hostname is the name or IP address of your host running the ChorusOS simulator.

For example, to access simulators on Host A from any other host, type the following command on the other host with super-user privileges:

# route add -net 2 1.11.7.1

Note -

Since the netmask has the value 0xff000000, the last three numbers of the IP sub-network address are ignored and the sub-network parameter can be shortened to 2.

Similarly, to access simulators on Host B from any other host, type the following command on the other host with super-user privileges:

# route add -net 3 1.11.7.2

Please consult your Solaris System Administration Collection for your specific configuration.