	     x86sem : testing of x86 sequential semantics
	     ********************************************

The x86sem tool tests the x86 sequential semantics formalised in HOL
against a processor implementation.

The tool generates random x86 instructions, and for each instruction
it builds a valid assembler program that dumps the state of the
machine (including registers, flags, stack and memory) immediately
before and after the instruction being tested.  These informations are
then passed to the HOL infrastructure, which automatically attempts to
prove that the semantics of the instruction transforms the initial
state into the final state.

Installation
************

- x86sem requires ocaml (http://caml.inria.fr) and nasm
  (http://nasm.sourceforge.net).  It runs on 32 bits x86 processors
  (it has been tested on a Pentium 4 running Linux).

- download the HOL x86 infrastructure from 
  
  http://www.cl.cam.ac.uk/~pes20/weakmemory/tarball-spec-public.tar.gz
  
  untar it, and compile it by invoking make.

- download x86sem from

  http://www.cl.cam.ac.uk/~pes20/weakmemory/x86sem.tar.gz

  untar it, and compile it by invoking make.  This will generate the
  "x86sem" executable.

- Holmake must be in the PATH.

Usage
*****

Invoking ./x86sem generates one random test and verifies the HOL
semantics against this test:

- if the semantics succesfully mimics the processor, the test is
  written into the "report_ok.txt" file;

- otherwise the test is written into the "report_fail.txt" file.

After each test, x86sem also updates the "report_stat.bin" file, which
contains statistics about the instructions being tested.

x86sem accepts the following options:

 -x86_dir <string> : specify the directory of the HOL x86 infrastructure 
                     (defaults to "../tarball-spec-public/");

 -repeat <int> : generate and verify <int> tests;

 -report <string> : use <string> as prefix for the report files;

 -dump_stats : display the statistics (can be combined with -report).

For each instruction the statistics display the number of tests which
succeded and failed, for instance

  MOV r/m32 r32     36   1

means that MOV from a register to memory or register was tested 37
times, and 36 tests succeded and 1 failed (in this case the user can
then investigate the failure by looking at the report_fail.txt file).
The statistics also summarise how many times each kind of argument has
been tested.

License
*******

The files asm_io.inc, asm_io.asm, cdecl.h, driver.c have been written
by Dr Paul Carter (http://www.drpaulcarter.com) as part of his free PC
assembly tutorial.

All the other files are licensed as below.

      x86 Multiprocessor Machine Code Semantics: x86sem
				   

Susmit Sarkar (1), Peter Sewell (1), Francesco Zappa Nardelli (2),
Scott Owens (1), Thomas Braibant (2), Magnus Myreen (1), 
Jade Alglave (2)        

 (1) Computer Laboratory, University of Cambridge   
 (2) Moscova project, INRIA Paris-Rocquencourt          

  Copyright 2007-2008  

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions 
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in 
   the documentation and/or other materials provided with the
   distribution.
3. The names of the authors may not be used to endorse or promote
   products derived from this software without specific prior 
   written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS 
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY 
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.