############### Pre-requisites for installing qemutrace ###############
1) Build system (make, autoconf, gcc)
2) udis86: Disassembler library for x86 and x86-64
3) zlib: Compression library

############### Terminology ###############

1) native system: the system on which you are executing qemutrace.
2) guest system: the system that you are emulating using qemutrace.

############### Contents of the repository ###############

This project contain two versions of qemutrace. Both these versions are patches applied to the 1.1.50 version of the original Qemu. 
1) 1.1.50_32bit: This is stored in the '1.1.50_32bit' directory. 
                 It can only collect traces for 32-bit systems with x86 instruction set.
				 This version of qemu has been tested with the Linux operating system and the Xen hypervisor.

2) 1.1.50_64bit: This is stored in the '1.1.50_64bit' directory. 
                 It can collect traces for 64-bit systems with x86_64 instruction set. 
			     This version of qemu has been tested with three operating systems: Linux, FreeBSD, and OpenBSD.

3) 2.8.0_64bit: This is stored in the '2.8.0_64bit' directory. These modifications are added on top of v2.8.0 tag in the QEmu main repo.
                It can collect traces for 64-bit systems with x86_64 instruction set. 
			    This version of qemu has been tested with three operating systems: Linux, FreeBSD, and OpenBSD.
			    This version also provides support for SVM instructions.

############### Building qemutrace ###############

Below-mentioned procedures have been tested on a 64-bit system running Ubuntu 12.04.

1) 1.1.50_32bit: Below-mentioned commands will create a qemu executable at the location '1.1.50_32bit/i386-softmmu/qemu-system-i386'.
     $ cd 1.1.50_32bit
     $ ./configure --target-list=i386-softmmu
     $ make

2) 1.1.50_64bit: Below-mentioned commands will create a qemu executable at the location '1.1.50_64bit/x86_64-softmmu/qemu-system-x86_64'.
     $ cd 1.1.50_64bit
     $ ./configure --target-list=x86_64-softmmu
     $ make

3) 2.8.0_64bit: Below-mentioned commands will create a qemu executable at the location '2.8.0_64bit/x86_64-softmmu/qemu-system-x86_64'.
     $ cd 2.8.0_64bit
     $ ./configure --target-list=x86_64-softmmu --disable-werror
     $ make

############### Command ###############

<qemu-executable> -smp NUM_CORES -m RAM_SIZE -icount shift=0 -q_trace mode=file,file=BASENAME_OF_TRACE_FILES,pat=[y/n] -ST NUM_INSN -hda PATH_OF_DISK_IMAGE --monitor stdio

1) <qemu-executable>: Check the step on building qemutrace.
2) NUM_CORES: Number of cores in the guest system (has no relation to the number of cores on the native system).
3) RAM_SIZE: Size of the main memory (Give 2G for 2GB main memory).
4) icount: Enable virtual instruction counter. The virtual cpu will execute one instruction every 1 ns of virtual time.
5) mode: Set this to file if you want to collect traces in plain text files.  
6) file: Set this to the basename of the trace files. 
         If you are emulating a 4-core guest and you set 'file' to /home/prathmesh/traces/apache, qemutrace will create 4 trace files.
         /home/prathmesh/traces/apache_0 will store the trace file for core 0
         /home/prathmesh/traces/apache_1 will store the trace file for core 1 and so on.
7) pat: Physical Address Translation
8) ST: This option specifies the total number of instructions for which the trace should be collected. 
       Set this option to -1 if you wish to stop the trace collection in some other way.
9) --monitor stdio: This option gives the user a command terminal using which he/she can interact with the qemu executable at run time.


############### Collecting traces ###############

Trace collection is a time consuming operation that slows down the execution of the guest system. 
Hence, we have configured qemutrace to start collecting traces only when instructed to. 
Our strategy for collecting traces is: boot the system, perform user login, go to the benchmark directory, start benchmark.
Trace collection can be done in two ways: 
1) command line terminal: In this method, the user monitors the output of the guest system and issues commands for starting and 
     stopping the trace collection at the appropriate time.
     $ qqq_start_trace
     $ qqq_stop_trace
   'qqq_start_trace' option is used to start the tracing.
   'qqq_end_trace' option is used to end the tracing.
2) software interrupts: In this method, the user inserts special instructions in the benchmark itself to start and stop the trace collection.
     a) When a software interrupt instruction for interrupt ID '100' is executed on the guest, qemutrace consumes the 
        interrupt instruction without processing it to the guest system, and STARTS collecting traces.  
     b) Similarly when a software interrupt instruction for interrupt ID '101' is executed on the guest, qemutrace consumes the 
        interrupt instruction without processing it to the guest system, and STOPS collecting traces. 
	 Add this line to your program just before it starts region of interest (ROI) execution: asm ("int $100");
	 Add this line to your program just after it completes ROI execution: asm ("int $101");

############### Comments/Suggestions ###############

1) A 1 billion instruction trace will typically require around 100 GB disk space. You can compress this trace using gzip to save 
   the same files in 1/10 th the disk space.

############### Future plans  ###############

We intend to extend the qemutrace tool in the following ways in future: 
1) Extend the qemutrace functionality to ARM instruction set. This should be a 2 week work.

If you are interested in any of these projects or if you have any good suggestion for qemutrace, kindly do not hesitate to contact us.
