Skip to content

Commit 5d337a6

Browse files
mgrosvenormgrosvenor
authored
Merge pull request #1 from exablaze-oss/add_docs
Updated project to use mkdocs and github pages
2 parents 624a3f9 + 6344f24 commit 5d337a6

19 files changed

+526
-1
lines changed

‎Exact_Capture_Documentation.pdf

-217 KB
Binary file not shown.

‎Makefile

+6
Original file line numberDiff line numberDiff line change
@@ -43,5 +43,11 @@ install: all
4343
uninstall:
4444
rm -f $(foreach file,$(BIN),$(PREFIX)/bin/$(file))
4545

46+
.PHONY: docs
47+
docs:
48+
$(MAKE) -C docs/
49+
4650
clean:
4751
rm -rf bin/*
52+
$(MAKE) -C docs/ clean
53+

‎README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ The system is fully open source and designed for performance as well as ease of
66
It can be used with any ExaNIC network card, and is optimised for use with ExaDisk high speed flash drives.
77
The system can be deployed on any suitably powerful server system.
88

9-
For full documentation, please see Exact_Capture_Documentation.pdf
9+
Full online documentation is available [here](https://code.exablaze.com/exact-capture/)
10+
1011

1112

‎docs/.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#ignore the generated site
2+
site
3+

‎docs/Makefile

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
all: docs
2+
.PHONY all:
3+
4+
test:
5+
mkdocs serve
6+
7+
publish:
8+
mkdocs gh-deploy
9+
10+
docs:
11+
mkdocs build --clean
12+
13+
clean:
14+
rm -rf site
15+

‎docs/mkdocs.yml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
site_name: Exact Capture Documentation
2+
site_url: http://exact-capture.io
3+
theme:
4+
name: readthedocs
5+
highlightjs: true
6+
7+
docs_dir: src
8+
9+
nav:
10+
- Introduction: index.md
11+
- Installation: install.md
12+
- Quick Start: quick.md
13+
- Server Requirements: server.md
14+
- Configuration Guide: config.md
15+
- Output Format (expcap): expcap.md
16+
- Internal Architecture: arch.md
17+
- Tools & Utlities: utils.md
18+
- Version History: versions.md
19+
20+
markdown_extensions:
21+
- markdown.extensions.admonition
22+
23+
plugins:
24+
- search

‎docs/src/arch.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
The Exact Capture software system comprises 4 major internal components:
2+
3+
1. One or more “hot” threads - to read packets from the ExaNIC(s) into memory
4+
2. One or more “cold” threads - to write packets from memory to disk(s)
5+
3. One or more shared memory queues - to connect the hot and cold threads to each other
6+
4. One management thread - responsible for control and statistics collection / reporting
7+
8+
These basic architectural components are illustrated below, with the addition of the ExaNIC and ExaDisk resources.
9+
The head of each column highlights the performance limiting resource for that component:
10+
11+
![Exact Capture Architecture](img/exact-capture-arch.png)
12+
13+
_This page was last updated on ._

‎docs/src/config.md

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
2+
The Exact Capture application supports a number of configuration options in both short and long form.
3+
For example:
4+
```
5+
$ exact-capture -i exanic0:0 --log-report-int 10 ....
6+
```
7+
8+
A [quick start](quick.md) guide is available for getting started.
9+
The following table lists all commands available:
10+
11+
<table>
12+
<tr>
13+
<th>Short</th>
14+
<th>Long</th>
15+
<th>Default</th>
16+
<th>Description</th>
17+
</tr>
18+
<tr>
19+
<td>i</td>
20+
<td>input</td>
21+
<td><em>(required)</em></td>
22+
<td>
23+
The ExaNIC interface(s) to capture on
24+
</td>
25+
</tr>
26+
<tr>
27+
<td>o</td>
28+
<td>output</td>
29+
<td><em>(required)</em></td>
30+
<td>
31+
The destination directory and filename stub to output to.
32+
Filenames will be output in the following format /output/dir/base_xx.expcap.
33+
Where xx is a unique file index.
34+
For details on the expcap format please see the Exact Capture Output Format (expcap) section later in this document.
35+
</td>
36+
</tr>
37+
<tr>
38+
<td>c</td>
39+
<td><a name="cpus">cpus</a></td>
40+
<td><em>(required)</em></td>
41+
<td>
42+
The list of CPUs to assign threads to for management, listening and writing threads.
43+
This is specified in the the following format, <code>m:ls,ls,ls:ws,ws,ws</code>.
44+
Where m is the core number for management, and ls/ws are comma separated lists of listener and writer CPU core numbers.
45+
For example <code>--cpus=5:2,3:7,6,1</code> would configure Exact Capture to run the management thread on CPU 5, with two NIC listener threads on on CPUs 2 and 3 respectively, and three (or more) disk writer threads on cores 1,6 &amp; 7 respectively.
46+
</br></br>
47+
<strong>Note:</strong> the number of listener CPUs must be exactly equal to the number of ExaNIC <code>--interfaces</code> in use.
48+
Furthermore listener threads cannot share CPUs with management or writer threads.
49+
If there are fewer writer threads than <code>--outputs</code>, writer threads will be reused.
50+
</td>
51+
<tr>
52+
<td>s</td>
53+
<td>snaplen</td>
54+
<td>2048B</td>
55+
<td>
56+
In some cases it is not necessary / useful to capture the entire packet.
57+
Set the snap length to determine the maximum size of packet that can be captured.
58+
This value cannot be 0 or less.
59+
</td>
60+
</tr>
61+
<tr>
62+
<td>m</td>
63+
<td>maxfile</td>
64+
<td>0 <em>(unlimited)</em></td>
65+
<td>
66+
High rate capture can produce very large file sizes.
67+
To reduce the file sizes, Exact Capture can cap the file size to a maximum, and will start a new file each time it is reached.
68+
A value of 0 or less puts no limit on the output file size.
69+
</td>
70+
</tr>
71+
<tr>
72+
<td>l</td>
73+
<td>logfile</td>
74+
<td><em>(none)</em></td>
75+
<td>
76+
Exact capture can optionally write log messages to a log file specified.
77+
</td>
78+
</tr>
79+
<tr>
80+
<td>t</td>
81+
<td>log-report-int</td>
82+
<td>1.0</td>
83+
<td>
84+
This sets the statistics calculation and logging interval in seconds.
85+
</td>
86+
</tr>
87+
<tr>
88+
<td>v</td>
89+
<td>verbose</td>
90+
<td><em>(flag)</em></td>
91+
<td>
92+
Enabling verbose mode will produce 2 output log lines every log interval (see above).
93+
These log lines will include summary statistics of the performance of all listener threads and all writer threads.
94+
</td>
95+
</tr>
96+
<tr>
97+
<td>V</td>
98+
<td>more-verbose</td>
99+
<td><em>(flag)</em></td>
100+
<td>
101+
Enabling more verbose mode will produce 1 output log line for every listener and writer thread.
102+
Each log line will include per-thread statistics counters/statistics.
103+
This can be combined with <code>--verbose</code> mode above.
104+
</td>
105+
</tr>
106+
<tr>
107+
<td>d</td>
108+
<td>debug-logging</td>
109+
<td><em>(flag)</em></td>
110+
<td>
111+
Debug logging mode enables display of the full file path, process ID and thread ID in each output log line.
112+
This is useful to track where a given log message originated.
113+
</td>
114+
</tr>
115+
<tr>
116+
<td>T</td>
117+
<td>no-log-ts</td>
118+
<td><em>(flag)</em></td>
119+
<td>
120+
By default, logs include a timestamp.
121+
This can make the output overly verbose.
122+
Use this flag to disable timestamps.
123+
</td>
124+
</tr>
125+
<tr>
126+
<td>w</td>
127+
<td>no-warn-overflow</td>
128+
<td><em>(flag)</em></td>
129+
<td>
130+
Software overflows will produce a warning.
131+
This may be problematic if the system is underperforming and these happen often.
132+
The flag disables these warnings.
133+
</td>
134+
</tr>
135+
<tr>
136+
<td>n</td>
137+
<td>no-spin</td>
138+
<td><em>(flag)</em></td>
139+
<td>
140+
By default Exact Capture outputs a progress “spinner” to the console.
141+
This flag disables it.
142+
</td>
143+
</tr>
144+
<tr>
145+
<td>n</td>
146+
<td>no-spin</td>
147+
<td><em>(flag)</em></td>
148+
<td>
149+
Exact Capture supports several performance testing modes.
150+
These can be used to give a sense of the best possible performance that you can expect from your system configuration.
151+
The modes are as follows:
152+
<ol>
153+
<li> No performance testing </li>
154+
<li>
155+
Replace all ExaNIC interfaces with a dummy interface.
156+
ExaNICs are no longer a performance limitation.
157+
This tests the maximum possible receive rate that your system can achieve for 64B frames.
158+
<strong>Note that 10GbE line-rate with 64B frames is about 7Gb/s (due to Ethernet interfame gap overheads).</strong>
159+
</li>
160+
<li>
161+
Replace the internal memory queue with a dummy interface on both sides.
162+
This tests the maximum performance possible when when system memory is not the bottleneck.
163+
This is also a good test of disk writing speed (for minimum sized packets).
164+
</li>
165+
<li>
166+
Replace the ExaDisk interface with a dummy.
167+
This tests the performance through the system when disk writing speed is not a limitation.
168+
This may be helpful to debug cases where your disks are not configured/performing correctly.
169+
</li>
170+
<li>
171+
Replace both the ExaNIC and the internal memory ring with dummies.
172+
Can be used to measure the absolute best performance possible when NICs and memory are not the limitations.
173+
Can also help to find interference bugs between ExaNICs and ExaDisks sharing limited PCIe bandwidth.
174+
</li>
175+
<li>
176+
Replace the ExaNIC and ExaDisk with dummies.
177+
This is useful for testing the maximum achievable application throughput, including through system memory, but excluding reading from and writing to real hardware.
178+
</li>
179+
<li>
180+
Replace the memory queues and ExaDisk with dummies.
181+
Can be help to find interference bugs between ExaNICs and ExaDisks sharing limited PCIe bandwidth.
182+
</li>
183+
<li>
184+
Replace the ExaNIC, memory queue and ExaDisk interfaces with dummies.
185+
Useful for determining the overheads within the application (i.e. CPU speed) issues.
186+
</li>
187+
</td>
188+
</tr>
189+
190+
</table>

‎docs/src/expcap.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Exact Capture outputs packet captures to a modified `pcap` format called `expcap`.
2+
The `expcap` format is a backwards compatible extension to standard `pcap` format.
3+
A number of [tools and utilities](utils.md) are included for operating on these files and converting them into standard `pcap` format if necessary.
4+
5+
For reference, standard `pcap` files are formatted as follows (more details can be found on the [Wireshark](https://wiki.wireshark.org/Development/LibpcapFileFormat) website):
6+
![PCAP file format](img/exact-capture-expcap.png)
7+
8+
9+
## Padding Packets
10+
As a performance optimisation, Exact Capture occasionally needs to insert padding packets (e.g. to align to a 4k boundary) into the output file.
11+
These packets are easily recognizable because `pcap` header wire length field (as above) is set to 0B, with the on disk length field (again as above) is set to the size of the padding.
12+
13+
Although setting these header fields precisely captures the semantics of the padding packets (i.e bytes written to disk that were never found on the wire), this is technically a `pcap` file specification violation.
14+
Presumably the writers never envisaged this kind of use case.
15+
Nevertheless, standard tools like `Wireshark` operate correctly and ignore these packets as they should.
16+
The following figure depicts a padding packet directly after the file header.
17+
This will be found in all Exact Capture output files.
18+
![EXPCAP file padding](img/exact-capture-expcap-padding.png)
19+
20+
21+
## Packet Footers
22+
Each captured packet is extended with a packet footer.
23+
This footer contains a variety of extra fields, not available in the standard pcap format. When the footer is added, the standard pcap disk bytes field is updated to reflect the extra length on disk. Once again, this means that the byes on disk value may exceed the bytes on the wire value (though not always. e.g. when a snaplength is set). The addition of a footer adds bytes to the disk that were never found on the wire is again, technically a PCAP specification violation. However, once again, standard pcap processing tools like Wireshark operate correctly and ignore these extra bytes as they should. The above figure shows a representation of expcap packet footers added to the first packet.
24+
25+
The additional expcap footer fields are described in detail in the table below. They borrow the spirit of some of the fields found in the ERF format.
26+
27+
![EXPCAP file padding](img/exact-capture-expcap-footer.png)
28+
29+
30+
<table>
31+
<tr>
32+
<th>Field</th>
33+
<th>Width (bits)</th>
34+
<th>Description</th>
35+
</tr>
36+
<tr>
37+
<td>Time (seconds)</td>
38+
<td>32</td>
39+
<td>
40+
Time in seconds since the epoch
41+
</td>
42+
</tr>
43+
<tr>
44+
<td>Time (picoseconds)</td>
45+
<td>40</td>
46+
<td>
47+
Time in picoseconds since the last second boundary
48+
</td>
49+
</tr>
50+
<tr>
51+
<td>Flags</td>
52+
<td>8</td>
53+
<td>
54+
The following flags bits are currently supported:
55+
56+
<ol>
57+
<li> New CRC Calculated (The CRC field contains a new new value including the footer) </li>
58+
<li> Frame aborted - this frame was aborted on the wire by the sender.</li>
59+
<li> Frame corrupt - the hardware CRC checker detected an error with this frame.</li>
60+
<li> Frame truncated - this packet was longer than the snap length and has been truncated. </li>
61+
</ol>
62+
</td>
63+
</tr>
64+
<tr>
65+
<td>Device ID Number</td>
66+
<td>8</td>
67+
<td>
68+
The ID of the device that captured these packets.
69+
For example, when capturing on the exanic3:7 interface, the device number would be 3.
70+
</td>
71+
</tr>
72+
<tr>
73+
<td>Port ID Number</td>
74+
<td>8</td>
75+
<td>
76+
The port on the device that was used to capture the packet.
77+
For example, capturing on exanic3:7 interface, the port number would be 7.
78+
</td>
79+
</tr>
80+
<tr>
81+
<td>CRC top</td>
82+
<td>16</td>
83+
<td>
84+
If the new CRC flag <strong>is not</strong> set, contains the number of packets dropped between this packet and the previous packet.
85+
Otherwise this is the top 16 bits of the new CRC.
86+
</td>
87+
</tr>
88+
<tr>
89+
<td>CRC bottom</td>
90+
<td>16</td>
91+
<td>
92+
If the new CRC flag <strong>is</strong> set, contains the bottom 16 bits of the new CRC. Otherwise, unused.
93+
</td>
94+
</tr>
95+
<table>

‎docs/src/img/exact-capture-arch.png

23.4 KB
Loading

‎docs/src/img/exact-capture-expcap-footer.png

16.9 KB
Loading

‎docs/src/img/exact-capture-expcap-padding.png

16 KB
Loading

‎docs/src/img/exact-capture-expcap.png

15.7 KB
Loading

‎docs/src/index.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Exact Capture is a high-rate, lossless packet capture solution for ExaNIC network adapters.
2+
The system is fully open source and designed for performance as well as ease of configuration.
3+
It can be used with any ExaNIC network adapter, and is optimised for use with ExaDISK high speed NVMe SSDs.
4+
The system can be deployed on any suitably powerful server system.
5+
6+
This document covers full details on the hardware and configuration requirements for Exact Capture as well as building, operating, tuning and debugging instructions.

0 commit comments

Comments
 (0)