modifying api for version 1.2

README.md

@@ -1,2 +1,5 @@
-# Titan
-Titan: A high precision virtual time system based on binary instrumentation
+# Kronos
+Kronos: A high precision virtual time system based on instruction counting
+
+TODO: An update involing instruction counting based on Intel-PIN-TOOL is under development and
+would be included in version 1.3

docs/installation.rst

@@ -13,6 +13,8 @@ Kronos has been tested on Ubuntu 16.04.5 LTS. It uses a modified linux kernel v4
 
   Virtualization Settings required for virtual machine in VMware.
 
+Python version 3.6 or higher should be the default on your system.
+
 Installing Kronos
 ^^^^^^^^^^^^^^^^^
 
@@ -104,7 +106,7 @@ Inorder to use Kronos, it must be loaded after each VM/machine reboot. It can be
 
   cd ~/Kronos
   sudo make load
-<<<<<<< HEAD
+
 
 Patching Kronos kernel after an update
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -113,13 +115,3 @@ If a previously installed Kronos kernel needs to be updated with new changes in
 
   cd ~/Kronos && git pull origin master
   sudo make patch_kernel # Follow same installation steps when prompted in menuconfig
-=======
-
-Patching Kronos Kernel
-^^^^^^^^^^^^^^^^^^^^^^
-
-To patch an already installed Kronos kernel with the latest changes in git repository, perform the following operations::
-
-  cd ~/Kronos && git pull origin master
-  sudo make patch_kernel  # Follow the same installation steps when kernel menuconfig appears
->>>>>>> d4cf3ce64327113f73a7d3008092c50ed757ed4c

docs/kronos_api.rst

@@ -3,6 +3,7 @@ Kronos API
 
 
 In this section we briefly describe python and C APIs provided for invoking Kronos specific functions. These API calls need to be invoked by the central orchestrator script.
+It assumes the default python version is 3.6 or higher.
 
 Kronos Python API
 ^^^^^^^^^^^^^^^^^
@@ -14,40 +15,35 @@ The initialization process also installs a python module called kronos_functions
 Initializing Kronos
 -------------------
 
-To initialize Kronos the **initializeExp(1)** API call must be made::
+To initialize Kronos the **initializeExp(num_expected_tracers)** API call must be made. It takes in as input the number of tracers that will be launched subsequently::
 
-	if kf.initializeExp(1) < 0 :
-		print "Kronos initialization failed ! Make sure you are running\
-		    the dilated kernel and kronos module is loaded !"
+	if kf.initializeExp(num_expected_tracers) < 0 :
+		print ("Kronos initialization failed ! Make sure you are running the dilated kernel and kronos module is loaded !")
 		sys.exit(0)
 
 Synchronize and Freeze
 ----------------------
 
-The Synchronize and Freeze API takes in as input the number of launched tracers. It can be invoked as **synchronizeAndFreeze(num_tracers)**. For example::
+The Synchronize and Freeze API can be invoked::
 
-	while kf.synchronizeAndFreeze(num_tracers) <= 0:
-		print "Kronos >> Synchronize and Freeze failed. Retrying in 1 sec"
+	while kf.synchronizeAndFreeze() <= 0:
+		print ("Kronos >> Synchronize and Freeze failed. Retrying in 1 sec")
 		time.sleep(1)
 
-Start Experiment
-----------------
-
-Start Experiment can be triggered with the **startExp()** API call::
-
-	kf.startExp()
-
 Progress for specifed number of rounds
 --------------------------------------
 
-To run the experiment for a specified number of rounds the **progress_n_rounds(num_rounds)** API call is used::
+To run the experiment for a specified number of rounds the **progressBy(duration_ns, num_rounds)** API call is used::
 
-	num_finised_rounds = 0
+	num_finished_rounds = 0
         step_size = 100
-        while num_finised_rounds <= args.num_progress_rounds:
-            kf.progress_n_rounds(step_size)
-            num_finised_rounds += step_size
-            print "Ran %d rounds ..." %(num_finised_rounds)
+        while num_finised_rounds <= 10000:
+            kf.progressBy(1000000, step_size)
+            num_finished_rounds += step_size
+            print ("Ran %d rounds ..." %(num_finished_rounds))
+
+In this example the experiment is run in bursts of 100 rounds before returning control to the orchestrator script. During
+each round, virtual time advances by 1000000 ns or 1ms.
 
 
 Stop Experiment
@@ -64,15 +60,21 @@ An almost identical set of API calls are provided in C as well. An orchestrator
 
 	#include "Kronos_functions.h"
 
-The function prototypes of all the relevant API calls are given below::
+	The function prototypes of all the relevant API calls are given below::
+
+	//! Initializes a EXP_CBE experiment with specified number of expected tracers
+	int initializeExp(int num_expected_tracers);
+
+	//! Synchronizes and Freezes all started tracers
+	int synchronizeAndFreeze(void);
+
+	//! Initiates Stoppage of the experiment
+	int stopExp(void);
+
+	//! Instructs the experiment to be run for the specific number of rounds 
+	//  where each round signals advancement of virtual time by the specified duration in nanoseconds
+	int progressBy(s64 duration, int num_rounds);
 
-	int initializeExp(int exp_type);
-	int startExp();
-	int synchronizeAndFreeze(int n_expected_tracers);
-	int progress_n_rounds(int n_rounds);
-	int stopExp();
-	
-.. note:: initializeExp takes an integer exp_type argument which must be set to 1. It is currently just a place holder but future upgrades are planned.
 
 The orchestrator script must be linked with the kronos api library with **-lkronosapi** linker option at compile time. This library gets included in the system path when Kronos is first installed.
 

docs/quickstart.rst

@@ -7,11 +7,11 @@ Commands/processes which need to be dilated can be added with arguments to the `
 
 The example can be started as follows::
 
-	python example_kronos_experiment.py --cmds_to_run_file=$HOME/Kronos/examples/cmds_to_run_file.txt \
-					    --run_in_one_tracer=False \
-					    --rel_cpu_speed=1.0 \
-					    --num_insns_per_round=1000000 \
-					    --num_progress_rounds=1000
+	python example_vt_experiment.py --cmds_to_run_file=$HOME/Kronos/examples/cmds_to_run_file.txt \
+					--run_in_one_tracer=False \
+					--rel_cpu_speed=1.0 \
+					--num_insns_per_round=1000000 \
+					--num_progress_rounds=1000
 
 .. note:: The run_in_one_tracer argument specifies if all commands in the cmd file need to launched under just one tracer. If specified to False, a new tracer is launched for each command.
 

docs/tracers.rst

@@ -4,21 +4,21 @@ Tracers
 Tracers are helper binaries that ship with Kronos installation. They are added to the system path and can be invoked with the following arguments::
 
 	tracer [-f <Path to file containg commands to dilate> or -c <Command to dilate with args> ] \
-		-r <Relative CPU Speed> -n <Num insns per round>
+		-r <Relative CPU Speed> [-i <Optional Tracer-ID> ]
 
 A brief description of each option is given below:
 
 * **-r** : Relative CPU speed is equivalent to a time dilation factor or (TDF). It represents the number of instructions that need to be executed for 1ns of virtual time.
 
-* **-n** : Specifies the number of instructions to execute in one round. When divided by the relative cpu speed, the resultant quantity denotes amount of time the experiment would advance in one-round. If num instructions to run in one round is 1000000 and relative cpu speed is 2, then for each round, the experiment's clock would advance by 500000 ns or 500us. This quantity is called **timestep size.** 
+* **-i** : Represents an optional ID assigned to a tracer. If absent the ID will be auto assigned. Note: Either ignore this for all tracers or specify a unique value (starting from 1) for each tracer. Do not partially assign values form some tracers. 
 
 * **-f** : Specifies a path to file containg commands to dilate. If more than one dilated process needs to be monitored by this tracer, then the commands to dilate are put in a file and passed as an argument. 
 
 * **-c** : Specifies a single command which needs to be dilated. Both **-f** and **-c** cannot be used simultaneously.
 
 For example, a tracer which wants to dilate the bash command **ls -al** can be launched as follows::
 
-	tracer -c "ls -al" -r 1.0 -n 1000000
+	tracer -c "/bin/ls -al" -r 1.0
  
 A tracer will launch all dilated processes and register itself with Kronos. It will then wait for trigger commands from Kronos. At the start of each round, Kronos would send a trigger to each registered tracer instructing it to run one round.
 

docs/tracked_bugs.rst

@@ -6,7 +6,7 @@ The Kronos virtual system currenly some limitations which are currently tracked
 
 .. _here: https://github.com/Vignesh2208/Kronos/blob/master/TODO
 
-* Kronos is unable to trace/control bash/shell scripts. So if an application/process started under the control of Kronos tries to run shell/bash scripts, then Kronos would be unable to control that process or its children and their behaviour is undefined. This is because the underlying linux ptrace subsystem used by Kronos is designed for compiled programs and not shell scripts.
+* Kronos currently does not dilate the tcp stack and its associated timers inside the Kernel.
 
 * Further, if a Kronos experiment is abnormally stopped/cancelled without a clean stop, then the next Kronos experiment cannot be run without a system reboot. This issue is being currently worked on.
 

docs/virtual_experiment.rst

@@ -13,8 +13,6 @@ In any Kronos controlled execution, a central orchestrator script is written by
 
 * **Synchronize and Freeze**: After all **tracers** have been launched, the next stage involves waiting for all of them to finish initialization. An API call is provided for this purpose. After the completing of this stage, all dilated processes have been added to Kronos's control and their execution and clock has been frozen.
 
-* **Start Experiment**: This stage tells Kronos that the experiment is ready to start. It triggers some internal book-keeping tasks. An API call is provided for this purpose.
-
 * **Experiment Progress**: This stage involves progressing/running the experiment. The experiment proceeds in rounds. During each round, all dilated processes are advanced by a timestep. At the end of each round, the clocks of all dilated processes are synchronized to the same value and all dilated processes are frozen. APIs are provided to specify number of rounds to run.
 
 * **Stop Experiment**: The final stage involves invoking a Stop Experiment API call after the desired number of rounds have been run. This cleans up all allocated resources and stops all tracers.

examples/example_app_vt_experiment.py

@@ -1,3 +1,6 @@
+# APP-VT is an experimental feature which is not fully developed yet. It would use Intel-PIN-TOOL
+# Stay tuned for more updates
+
 import sys
 import os
 import time

examples/example_exp_cs_vt_experiment.py

@@ -10,14 +10,14 @@
 EXP_CBE = 1
 EXP_CS = 2
 
-def start_new_dilated_process(tracer_id, timeline_id, cmd_to_run, log_file_fd,
+def start_new_dilated_process(timeline_id, cmd_to_run, log_file_fd,
     exp_type):
 
     newpid = os.fork()
     if newpid == 0:
         os.dup2(log_file_fd, sys.stdout.fileno())
         os.dup2(log_file_fd, sys.stderr.fileno())
-        args = ["tracer", "-t", str(timeline_id), "-i", str(tracer_id),
+        args = ["tracer", "-t", str(timeline_id),
                 "-c", cmd_to_run]
         os.execvp(args[0], args)
     else:
@@ -109,7 +109,7 @@ def main():
 
     for i in range(0, num_tracers):
         logging.info("Starting tracer: %d", i + 1)
-        start_new_dilated_process(i + 1, i % num_timelines,
+        start_new_dilated_process(i % num_timelines,
                                   cmds_to_run[i], log_fds[i], args.exp_type)
     input('Press any key to continue !')
 

examples/example_vt_experiment.py

@@ -6,12 +6,12 @@
 import argparse
 
 
-def start_new_dilated_process(tracer_id, cmd_to_run, rel_cpu_speed, log_file_fd):
+def start_new_dilated_process(cmd_to_run, rel_cpu_speed, log_file_fd):
     newpid = os.fork()
     if newpid == 0:
         os.dup2(log_file_fd, sys.stdout.fileno())
         os.dup2(log_file_fd, sys.stderr.fileno())
-        args = ["tracer", "-c", cmd_to_run, "-r", str(rel_cpu_speed), "-i", str(tracer_id)]
+        args = ["tracer", "-c", cmd_to_run, "-r", str(rel_cpu_speed)]
         os.execvp(args[0], args)
     else:
         return newpid
@@ -21,7 +21,7 @@ def start_all_cmds_in_one_tracer(cmds_to_run_file_path, rel_cpu_speed, log_file_
     if newpid == 0:
         os.dup2(log_file_fd, sys.stdout.fileno())
         os.dup2(log_file_fd, sys.stderr.fileno())
-        args = ["tracer", "-f", cmds_to_run_file_path, "-r", str(rel_cpu_speed), "-i", "1"]
+        args = ["tracer", "-f", cmds_to_run_file_path, "-r", str(rel_cpu_speed)]
         os.execvp(args[0], args)
     else:
         return newpid
@@ -92,7 +92,7 @@ def main():
     else:
         for i in range(0, len(cmds_to_run)):
             print ("Starting tracer for cmd: %s" %(cmds_to_run[i]))
-            start_new_dilated_process(i + 1, cmds_to_run[i], args.rel_cpu_speed, log_fds[i])
+            start_new_dilated_process(cmds_to_run[i], args.rel_cpu_speed, log_fds[i])
 
     print ("Synchronizing anf freezing tracers ...")
     while kf.synchronizeAndFreeze() <= 0:

kronos.code-workspace

@@ -0,0 +1,7 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	]
+}

scripts/x64_synchronizer.c

@@ -1,8 +1,10 @@
 #include <time.h>
+#include <unistd.h>
+
 int main(int argc, char *argv[])
 {
     while(1) {
-        usleep(1000000);		
+        //usleep(1000000);		
     }
     return 0;
 }