doc: add tested Intel platforms with Intel NICs
[dpdk.git] / doc / guides / tools / testregex.rst
1 .. SPDX-License-Identifier: BSD-3-Clause
2    Copyright 2020 Mellanox Technologies, Ltd
3
4 dpdk-test-regex Tool
5 ====================
6
7 The ``dpdk-test-regex`` tool is a Data Plane Development Kit (DPDK)
8 application that allows functional testing and performance measurement for
9 the RegEx PMDs.
10
11 It is based on precompiled rule file, and an input file, both of them can
12 be selected using command-line options.
13
14 In general case, each PMD has its own rule file.
15
16 By default the test supports one QP per core, however a higher number of cores
17 and QPs can be configured. The QPs are evenly distributed on the cores. All QPs
18 are assigned the same number of segments of input file to parse.  Given n QPs
19 (per core) - the enqueue/dequeue RegEx operations are interleaved as follows::
20
21  enqueue(QP #1)
22  enqueue(QP #2)
23  ...
24  enqueue(QP #n)
25  dequeue(QP #1)
26  dequeue(QP #2)
27  ...
28  dequeue(QP #n)
29
30
31 The test outputs the following data per QP and core:
32
33 * Performance, in gigabit per second.
34
35 * Matching results (rule id, position, length), for each job.
36
37 * Matching results in absolute location (rule id, position , length),
38   relative to the start of the input data.
39
40
41 Limitations
42 ~~~~~~~~~~~
43
44 * Supports only precompiled rules.
45
46
47 Application Options
48 ~~~~~~~~~~~~~~~~~~~
49
50 ``--rules NAME``
51   precompiled rule file
52
53 ``--data NAME``
54   data file to use
55
56 ``--nb_jobs N``
57   number of jobs to use
58
59 ``--nb_qps N``
60   number of QPs to use
61
62 ``--nb_lcores N``
63   number of cores to use
64
65 ``--perf N``
66   only outputs the performance data
67
68 ``--nb_iter N``
69   number of iteration to run
70
71 ``--nb_segs N``
72   number of mbuf segment
73
74 ``--help``
75   print application options
76
77
78 Running the Tool
79 ----------------
80
81 **Step 1: Compile a rule file**
82
83 In order for the RegEx to work it must have a precompiled rule file.
84 to generate this file there is a need to use a RegEx compiler that matches the
85 RegEx PMD.
86
87 **Step 2: Generate a data file**
88
89 The data file, will be used as a source data for the RegEx to work on.
90
91 **Step 3: Run the tool**
92
93 The tool has a number of command line options. Here is the sample command line::
94
95    ./dpdk-test-regex -a 83:00.0 -- --rules rule_file.rof2 --data data_file.txt --job 100 \
96      --nb_qps 4 --nb_lcores 2