Ace doc

README.md

@@ -14,7 +14,7 @@ CrashMonkey combined with Ace, provides an automated testing framework for file
 
 CrashMonkey and Ace can be used out of the box on any Linux filesystem that implements POSIX API. Our tools have been tested to work with ext2, ext3, ext4, xfs, F2FS, and btrfs, across Linux kernel versions - 3.12, 3.13, 3.16, 4.1, 4.4, 4.15, and 4.16.
 
----
+
 ## Setup ##
 
 Here is a checklist of dependencies to get CrashMonkey and Ace up and running on your system.
@@ -37,7 +37,7 @@ Here is a checklist of dependencies to get CrashMonkey and Ace up and running on
 
   `mkdir /mnt/snapshot`
 
----
+
 ## Push-button testing for seq-1 workloads ##
 
 This repository contains a pre-generated suite of 328 seq-1 workloads (workloads with 1 file-system operation) [here](code/tests/seq1/). Once you have [set up](#setup) CrashMonkey on your machine (or VM), you can simply run :
@@ -161,14 +161,14 @@ BlockSize : 4096
 #HardLinks: 1
 ```
 
----
+
 ## Demo ##
 All these steps have been assembled for you in the script [here](demo.sh). The link to the demo video is [here](). Try out the demo by running `./demo.sh btrfs`
 
----
+
 ## Research that uses our tools ##
 1. *Barrier-Enabled IO Stack for Flash Storage*. Youjip Won, Hanyang University; Jaemin Jung, Texas A&M University; Gyeongyeol Choi, Joontaek Oh, and Seongbae Son, Hanyang University; Jooyoung Hwang and Sangyeun Cho, Samsung Electronics. Proceedings of the 16th USENIX Conference on File and Storage Technologies (FAST 18). [Link](https://www.usenix.org/conference/fast18/presentation/won)
 
----
+
 ## Contact Info ##
 Please contact us at [email protected] with any questions. Drop us a note if you are using or plan to use CrashMonkey or Ace to test your file system.

documentation/Ace.md

@@ -1 +1,66 @@
-# Automatic Crash Explorer (Ace)#
+# Automatic Crash Explorer (Ace) #
+
+### Overview ###
+Ace is a bounded, and exhaustive workload generator for POSIX file systems. A workload is simply a sequence of file-system operations. Ace comprises of two main components
+
+1. **High-level workload generator** : This is responsible for exhaustively generating workloads within the defined bounds. The generated workloads are represented in a high-level language which resembles the one below.
+```
+mkdir B 0777
+open Bfoo O_RDWR|O_CREAT 0777
+fsync Bfoo
+checkpoint 1
+close Bfoo
+```
+
+2. **CrashMonkey adapter** : Workloads represented in the high-level language have to be converted to a [format](workload.md) that CrashMonkey understands. This is taken care of by the adapter. For example, the above workload is converted to the run method of CrashMonkey as follows.
+
+```c++
+virtual int run( int checkpoint ) override {
+
+    test_path = mnt_dir_ ;
+    A_path =  mnt_dir_ + "/A";
+    AC_path =  mnt_dir_ + "/A/C";
+    B_path =  mnt_dir_ + "/B";
+    Afoo_path =  mnt_dir_ + "/A/foo";
+    Abar_path =  mnt_dir_ + "/A/bar";
+    Bfoo_path =  mnt_dir_ + "/B/foo";
+    Bbar_path =  mnt_dir_ + "/B/bar";
+    ACfoo_path =  mnt_dir_ + "/A/C/foo";
+    ACbar_path =  mnt_dir_ + "/A/C/bar";
+
+    int local_checkpoint = 0 ;
+
+    if ( mkdir(B_path.c_str() , 0777) < 0){
+    return errno;
+    }
+
+    int fd_Bfoo = cm_->CmOpen(Bfoo_path.c_str() , O_RDWR|O_CREAT , 0777);
+    if ( fd_Bfoo < 0 ) {
+    cm_->CmClose( fd_Bfoo);
+    return errno;
+    }
+
+    if ( cm_->CmFsync( fd_Bfoo) < 0){
+    return errno;
+    }
+
+    if ( cm_->CmCheckpoint() < 0){
+    return -1;
+    }
+    local_checkpoint += 1;
+    if (local_checkpoint == checkpoint) {
+    return 1;
+    }
+
+    if ( cm_->CmClose ( fd_Bfoo) < 0){
+    return errno;
+    }
+
+    return 0;
+}
+```
+
+---
+### Bounds used by Ace ###
+
+Ace currently generates workloads of sequence length 1, 2, and 3. We say a workload has sequence length 'x' if it has 'x' core file-system operations in it.