README.md 2.43 KB
Newer Older
Andreas Schmidt's avatar
Andreas Schmidt committed
1
# X-Lap: A Systems Approach for Cross-Layer Profiling and Latency Analysis for Cyber-Physical Networks
2 3 4

## How to install X-Lap?

5 6
Install the following prerequisites via pip: `numpy`, `scipy`, `pandas`, `matplotlib`, `scikit-learn`, `ruamel.yaml`.

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

9 10


11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
## 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.