`sreplay' README -- instructions for building and introduction to the project.
Copyright (C) 2005-2007  Amos Waterland.
See the end for copying conditions.

Please send `sreplay' bug reports and patches to <apw@rossby.metr.ou.edu>.

COMPILING
=========

Note that only i386 and ppc64 Linux are working at the moment.  You
should just have to do:

 ./configure
 make

Note that the build machinery shares many features with the Linux
kernel make system.  For example, to output the build to a different
directory, do:

 make O=foo

The default make output is pretty-printed.  To see the raw commands, use:

 make V=1

To see the dependency that caused the rebuild of each object, use:

 make V=2

The make system is non-recursive and highly parallel, so -j works well.

The configure script generates a file called .config, which is
included by the main Makefile.  You can override any variable set in
the Makefile by adding it to your .config.  For example, if by default
you want to cross-compile to ppc64, with build output going
to a different directory, with no debug symbols and high optimization,
put this in your .config:

 ARCH=ppc64
 CROSS_COMPILE=powerpc64-linux-
 O=build
 G=
 Z=-O3

As expected, `make clean' removes everything but the .config, and 
`make mrproper' also removes the .config.

CROSS-COMPILING
===============

The build machinery has an inferface similar to Linux's.  So to
cross-compile for ppc64:

 make ARCH=ppc64 CROSS_COMPILE=powerpc64-linux-

COMMON PROBLEMS
===============

On some broken distributions you may get link errors that look like:

 linux/read.c:46: undefined reference to `__stack_chk_fail'

To work around this, do the following:

 echo "CFLAGS += -fno-stack-protector" >> .config 

INTRODUCTION
============

One can think of sreplay as a virtual application.  It is a
freestanding program that has just enough logic to get itself running
and then parse and replay a trace of system calls.

A freestanding program is one that does not rely on code provided by
the compiler runtime library or the system C library.  Operating
system kernels, hypervisors and bootloaders are freestanding for
obvious reasons, but sreplay is so because the code provided by libc
makes system calls before handing control to main.  Because our goal
is to make sreplay execute only those system calls provided in a
trace, it must be freestanding.  For similar reasons, the trace is
accepted as a literal command line argument, because opening a file
would involve one or more system calls.  The alternative is to embed
the trace as a seperate ELF section in the sreplay binary, similar to
Linux's zImage format, but we have chosen to pursue the simplicity of
the argv approach for now.

To summarize, the following two invocations are equivalent from a
system call perspective:

 $ true; true
 $ sreplay $(strace true 2>&1)

PORTING
=======

To port sreplay to a new architecture, you must supply a start.S that
provides the logic to set up an initial stack frame and other things
necessary to branch to main.  You must also supply a stub.h which
provides a macro that expands to the assembly necessary to make a
system call.

NOTES
=====

A more accurate application replay would execute the trace of
instructions gathered by single-stepping the original application.
Our approach is close enough for most purposes, but it definitely
exhibits different behavior -- it is not cpu-bound at all, and it's
page fault pattern is vastly different from any real application.

The file descriptor returned by open is different depending on whether
we are running under a debugger or not.

To print the list of unique system calls in your traces, use:

 awk -F'(' '/.*\(/ {print $1}' *.strace | sort | uniq

ROADMAP
=======

The current parser is hand-written and probably has all sorts of bugs.
Replace it with one generated by re2c or another lexer generator that
does not assume libc.

LIBC
====

Important files from the GNU C Library that help explain sreplay are:

libc/sysdeps/unix/sysv/linux/i386/syscall.S
libc/sysdeps/unix/sysv/linux/i386/sysdep.h
libc/sysdeps/unix/sysv/linux/i386/mmap.S
libc/sysdeps/unix/sysv/linux/powerpc/powerpc64/sysdep.h
libc/sysdeps/powerpc/powerpc64/sysdep.h
libc/sysdeps/powerpc/powerpc64/elf/start.S

LINUX
=====

Important files from the Linux kernel that help explain sreplay are:

arch/i386/kernel/sys_i386.c

RELATED WORK
============

[1] Gamut (Generic Application eMUlaTor) is an application for selectively
    utilizing parts of a single machine or networked servers.

    http://www.cs.duke.edu/~justin/cod/README.gamut-0.7.0

----------------------------------------------------------------------
Copyright information:

Copyright (C) 2005-2007 Amos Waterland

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.
