Laplace: Getting Started

The following steps should allow you to get the basic components of Laplace downloaded, installed, and running. Laplace is a flexible tool, and so this page will not cover all of the uses that we have developed for it so far. However, it should be enough to get the machine simulator producing a kernel trace and raw reference trace.

1. Download the whole machine tarball, which contains both a plain Bochs x86 simulator and a Laplace-modified Bochs x86 simulator, pre-built to run under Linux. It also contains configuration files and a disk file so that Bochs will run immediately. The disk file contains a pre-installed Slackware Linux installation using a Laplace-modified Linux 2.2.21 kernel.
2. Unpack the tarball and switch into the laplace-0.8-whole-machine/ directory.
3. Set the LAPLACE_TRACE_DATA_ADDRESS environment variable:

   setenv LAPLACE_TRACE_DATA_ADDRESS c020ab40

   This value is specific to the Laplace-modified Linux kernel. If you make changes to the kernel, you will need to change this value to match the location at which the trace_data structure is loaded. When you compile your new version of the kernel, just look at the System.map file produced by the kernel compilation, and search for the symbol trace_data.
4. Although it is not required, we recommend that you make named pipes to catch the output of the machine simulator, like so:

   mkfifo reference-trace kernel-trace

   These pipes can be consumed by a compression utility such as gzip. Better yet, you can download, compile, and use one of the reference handlers found on the downloads page. Some are made just to handle just the reference trace, while others handle both the reference and kernel traces. These utilities are designed perform useful transformations and compression on the traces depending on your intended use for them.
5. Run the simulator:

   ./bochs-laplace -nocontrolpanel

   This command will bring up the Laplace-modified Bochs x86 machine simulator. Note that bochs-basic, a non-modified version of the simulator is also provided as a fail-safe. Also note that if you are not running Laplace on a Linux/x86 host system, then you will need to download Bochs and the Laplace-Bochs patch from the downloads page and compile them for your platform.
6. Boot the kernel by selecting the Laplace-kernel at the bootloader menu. Note that a basic, unmodified, kernel is also provided as a fail-safe.
7. After a few minutes, the system should boot (likely with errors about the networking configuration). You can then login as root using the password ``laplace''. Of course, if you put this simulated machine on the network, that password should be changed!
8. Activate reference tracing by clicking on the Config icon in the upper-right-hand corner of the Bochs window. That will pause the simulation and provide a text menu in the window used to launch Bochs. At that menu, select 11 and, when asked if you want to enable tracing, enter yes. Then select 12 to resume the simulator.
9. After letting the simulator collect references for however long you like, you can deactivate reference tracing. Follow the same steps as above, only answering no at the appropriate prompt so that tracing is disabled. Note that this action closes the reference-trace pipe. Any utility that is consuming the contents of that pipe will reach an end-of-file.
10. Halt the system by using the halt command at the command prompt. When the simulated system is ready, click the Power icon to shut down the system. It is important to halt the simulator so that the kernel-trace file is properly completed and its contents flushed out.

If these steps work, then you can boot and modify the simulated system however you wish. Bochs is capable of networking through a simulated NE2000 card. The file bochsrc.txt contains the configuration information for the simulated machine, including that network card. Note that if you run more than one instance of Bochs and network those simulated machines, you must pick separate MAC addresses for each simulated NE2000 card! You will also need to modify the network configuration within the running Bochs system so that it will operate on your network.

Once you've configured the system as you choose, you can use the reference handlers to reduce and compress the output from tracing. The results from the reference handlers can then be used with the merge utility (again, available on the downloads page), which can reconstruct the state of the system from the traces, reconciling shared memory mappings, file use, and per-task (that is, kernel thread) referencing information.