---------------------------------------------------------------------
iPAQ Simulator (ipaqsim)
Sep 09, 2004
---------------------------------------------------------------------

This is a full machine simulation for iPAQ device. The CPU simulation 
code is based on Skyeye (www.skyeye.org) project. However, all the code
is re-written in C++ and much more organized. Important peripherals are
added: Flash, microcontroller, sleeve, wireless PC card, etc... to enable
the boot of Familiar Linux (familiar.handhelds.org).

HOW TO BUILD
1. Download "ipaqsim.tar.gz" and unpack the tar ball.
2. "cd ipaqsim"
3. Edit "Makefile". Mostly, you need to make two settings:
	1) SLiRP or TUN/TAP?
	   This is the virtual network emulation. SLiRP is like a proxy. It
	   re-sends the TCP/IP request for you. It can be used without root
	   access. And it has buildin router/DHCP/DNS. You already get 
	   Internet access after you bring up the simulator. The code is
	   from QEMU project (http://fabrice.bellard.free.fr/qemu/).
	   TUN/TAP is the standard way to simulate network. It simulates a
	   point-to-point network. Special setup on the host machine is 
	   needed.
	   a) add following line using "visudo" as root:
	      username	ALL=	NOPASSWD:	/sbin/ifconfig
	   b) Install tun/tap driver on your machine, and you should see 
	      /dev/net/tun. Change the access right so that "username"
		  can have RW access to the device.
	   In your guest OS (which is Familiar Linux on iPAQ simulator),
	   you need to use "ifconfig eth0 192.168.0.2" to set static IP.
	   Then you have a private network with the other side on your
	   host machine (IP: 192.168.0.1). You can change the host side
	   IP by editing "tapifup.sh". To access outside Internet, you
	   need to setup IP forwarding on the host machine (forward 
	   from "tun0" to "eth0").
	   In general, use SLiRP is much easier. Set "SLIRP = y" in
	   "Makefile" to enable it. If it is "n", TUN/TAP is used.
	2) libreadline and libhistory
	   You can choose not to use it by setting "READLINE = n". The
	   libraries are all in the "readline" package. If your distribution
	   already got the development files, you should see 
	   "/usr/include/readline/". Otherwise, download the package
	   from GNU website and install it somewhere. Then edit the
	   "Makefile" to set the READLINE_LIBDIR and READLINE_INCDIR.
4. "make all"
5. You also need a terminal emulator to connect to the simulated serial
   port on ipaqsim. It is actually a TCP port (11103). So you basically
   can use "telnet host_machine 11103". For better usage, you need 
   "gcomm". Download it from "http://gcomm.sourceforge.net/".

HOW TO RUN
1. The program is not complete yet. Use "debug" mode for now.
2. Run "ipaqsim -d"
3. Use "telnet host_machine 11103" or
   run "gcomm" and set "Connection Type" to "net". Input "Host ID"
   (host_machine) and "Port ID"(11103) then click "Connect".
4. Then you enter the debugger interface. Pretty much like gdb. Some
   batch commands in ".simdbgrc" is executed automatically. Type
   "help" to see the command help.
5. Under "sim_dbg>" type "run".
6. Find the "telnet" window or "gcomm" window (the command line window
   not the GUI window). You will see the bootldr command line interface.
7. Type "boot" in bootldr. Wait at least 5 minutes for booting.
6. When you see the "Familiar login:", you can login (use root and "rootme"
   as the password).
7. Be patient for some commands, the simulator is slow. For example, if
   you fail the login, it takes quite long time to show next login.
8. You can connect to the Internet if you simulation host connects to.
   If you use slirp, you may have problems to ping outside IPs. You can
   try to ssh to your simulation host.

SPECIAL FEATURES

Checkpoints
	Currently the simulator is pretty slow (20x slower than real hardware).
Checkpoints can be used to enable fast recovery from the previous running
state (like Windows' hibernation). To save a checkpoint, use "Ctrl+C" to
interrupt the simulation and get back to "sim_dbg>" command line. Use
"savecp checkpoint_name" to save the CP. Later, you can use 
"loadcp checkpoint_name" to load the CP. And "run" to continue the
simulation. The OS will be exactly in the same state as when you save
the CP. 
	There are some special issues for network. Since we don't save
state in SLiRP, you need to do something to reset the network. In guest
OS, run

"ifconfig eth0 down"
"ifconfig eth0 up"
"route add default gw 10.0.2.2"

Then the network will be OK. It is similar when you use TUN/TAP. 

---------------------------------------
Ye Wen
wenye@cs.ucsb.edu

Mayhem Lab
Computer Science Department
University of California, Santa Barbara