# X-Lap: A Systems Approach for Cross-Layer Profiling and Latency Analysis for Cyber-Physical Networks

## How to install X-Lap?

Enter the project directory and type `python setup.py install` to install `xlap` on your system.

## How to use X-lap?

### Step 0: Define your relevant timestamps across a packet trace.
Define time- and cyclestamps:

* Where data enters the sender app.
* Where data leaves the sender app.
* Where data enters the receiver app.
* Where data leaves the receiver app.
* Define additional cyclestamps wherever appropriate.
* Define interesting durations inside xlap.yml.

### Step 1: Instrument your code and generate traces
* Define a Sender and Receiver Application (send arbitrary data around).
* Initialize the xlap facility.
* Add stamping code where-ever appropriate.
* There are different mechanisms for adding timestamps.


### Step 2: Use the provided xlap analysis tools
* Write your `xlap.yml` file as follows:

```yml
data_files:
    sender: sender.csv
    receiver: receiver.csv
cycle_reference:
    sender: StampA
    receiver: SampB
time_reference:
    sender: StampC
    receiver: StampE
stamps:
    StampA:
        Source: receiver
        Type: time
    StampB:
        Source: receiver
        Type: time
    StampC:
        Source: receiver
        Type: time
    StampD:
        Source: receiver
        Type: cycle
    StampE:
        Source: receiver
        Type: time
durations:
    DurationA:
        Start: StampA
        Stop: StampB
        Source: sender
    DurationB:
        Start: StampC
        Stop: StampD
        Source: receiver
packet_types:
    Data: 0
    Ack: 1
```

* You can run a jitter analysis via `xlap jitter`. The parameter `-e` exports the diagrams as `pdf`.

* The best way to interact with `xlap` is through a [Jupyter Python 3 Notebook](http://jupyter.org/). An example can be found in `notebook.ipynb`.

* `xlap.analyse.trace.traces()` can be used to investigate individual packet traces.


## Conventions

* Suffixes (indicate type):

  * `_T`: Timestamp (us precision)
  * `_C`: Clockstamp
  * `_D`: Duration (us precision)


* Reserved Names (including suffixes as mentioned before):

    * `Channel`
    * `Sender`
    * `SenderCycle`
    * `Receiver`
    * `ReceiverCycle`
    * `EndToEnd`


* Note that expressions with other suffixes such as `SenderQueueing_T` would be allowed.