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.