]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. BSD LICENSE |
2 | Copyright(c) 2010-2014 Intel Corporation. All rights reserved. | |
3 | All rights reserved. | |
4 | ||
5 | Redistribution and use in source and binary forms, with or without | |
6 | modification, are permitted provided that the following conditions | |
7 | are met: | |
8 | ||
9 | * Redistributions of source code must retain the above copyright | |
10 | notice, this list of conditions and the following disclaimer. | |
11 | * Redistributions in binary form must reproduce the above copyright | |
12 | notice, this list of conditions and the following disclaimer in | |
13 | the documentation and/or other materials provided with the | |
14 | distribution. | |
15 | * Neither the name of Intel Corporation nor the names of its | |
16 | contributors may be used to endorse or promote products derived | |
17 | from this software without specific prior written permission. | |
18 | ||
19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
20 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
21 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
22 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
23 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
24 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
25 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
26 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
27 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
28 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
30 | ||
31 | ||
32 | Netmap Compatibility Sample Application | |
33 | ======================================= | |
34 | ||
35 | Introduction | |
36 | ------------ | |
37 | ||
38 | The Netmap compatibility library provides a minimal set of APIs to give programs written against the Netmap APIs | |
39 | the ability to be run, with minimal changes to their source code, using the DPDK to perform the actual packet I/O. | |
40 | ||
41 | Since Netmap applications use regular system calls, like ``open()``, ``ioctl()`` and | |
42 | ``mmap()`` to communicate with the Netmap kernel module performing the packet I/O, | |
43 | the ``compat_netmap`` library provides a set of similar APIs to use in place of those system calls, | |
44 | effectively turning a Netmap application into a DPDK application. | |
45 | ||
46 | The provided library is currently minimal and doesn't support all the features that Netmap supports, | |
47 | but is enough to run simple applications, such as the bridge example detailed below. | |
48 | ||
49 | Knowledge of Netmap is required to understand the rest of this section. | |
50 | Please refer to the Netmap distribution for details about Netmap. | |
51 | ||
52 | Available APIs | |
53 | -------------- | |
54 | ||
55 | The library provides the following drop-in replacements for system calls usually used in Netmap applications: | |
56 | ||
57 | * ``rte_netmap_close()`` | |
58 | ||
59 | * ``rte_netmap_ioctl()`` | |
60 | ||
61 | * ``rte_netmap_open()`` | |
62 | ||
63 | * ``rte_netmap_mmap()`` | |
64 | ||
65 | * ``rte_netmap_poll()`` | |
66 | ||
67 | They use the same signature as their libc counterparts, and can be used as drop-in replacements in most cases. | |
68 | ||
69 | Caveats | |
70 | ------- | |
71 | ||
72 | Given the difference between the way Netmap and the DPDK approach packet I/O, | |
73 | there are caveats and limitations to be aware of when trying to use the ``compat_netmap`` library, the most important of these are listed below. | |
74 | These may change as the library is updated: | |
75 | ||
76 | * Any system call that can potentially affect file descriptors cannot be used with a descriptor returned by the ``rte_netmap_open()`` function. | |
77 | ||
78 | Note that: | |
79 | ||
80 | * The ``rte_netmap_mmap()`` function merely returns the address of a DPDK memzone. | |
81 | The address, length, flags, offset, and other arguments are ignored. | |
82 | ||
83 | * The ``rte_netmap_poll()`` function only supports infinite (negative) or zero time outs. | |
84 | It effectively turns calls to the ``poll()`` system call made in a Netmap application into polling of the DPDK ports, | |
85 | changing the semantics of the usual POSIX defined poll. | |
86 | ||
87 | * Not all of Netmap's features are supported: host rings, | |
88 | slot flags and so on are not supported or are simply not relevant in the DPDK model. | |
89 | ||
90 | * The Netmap manual page states that "*a device obtained through /dev/netmap also supports the ioctl supported by network devices*". | |
91 | This is not the case with this compatibility layer. | |
92 | ||
93 | * The Netmap kernel module exposes a sysfs interface to change some internal parameters, such as the size of the shared memory region. | |
94 | This interface is not available when using this compatibility layer. | |
95 | ||
96 | Porting Netmap Applications | |
97 | --------------------------- | |
98 | ||
99 | Porting Netmap applications typically involves two major steps: | |
100 | ||
101 | * Changing the system calls to use their ``compat_netmap`` library counterparts. | |
102 | ||
103 | * Adding further DPDK initialization code. | |
104 | ||
105 | Since the ``compat_netmap`` functions have the same signature as the usual libc calls, the change is trivial in most cases. | |
106 | ||
107 | The usual DPDK initialization code involving ``rte_eal_init()`` and ``rte_eal_pci_probe()`` | |
108 | has to be added to the Netmap application in the same way it is used in all other DPDK sample applications. | |
109 | Please refer to the *DPDK Programmer's Guide* and example source code for details about initialization. | |
110 | ||
111 | In addition of the regular DPDK initialization code, | |
112 | the ported application needs to call initialization functions for the ``compat_netmap`` library, | |
113 | namely ``rte_netmap_init()`` and ``rte_netmap_init_port()``. | |
114 | ||
115 | These two initialization functions take ``compat_netmap`` specific data structures as parameters: | |
116 | ``struct rte_netmap_conf`` and ``struct rte_netmap_port_conf``. | |
117 | The structures' fields are Netmap related and are self-explanatory for developers familiar with Netmap. | |
118 | They are defined in ``$RTE_SDK/examples/netmap_compat/lib/compat_netmap.h``. | |
119 | ||
120 | The bridge application is an example largely based on the bridge example shipped with the Netmap distribution. | |
121 | It shows how a minimal Netmap application with minimal and straightforward source code changes can be run on top of the DPDK. | |
122 | Please refer to ``$RTE_SDK/examples/netmap_compat/bridge/bridge.c`` for an example of a ported application. | |
123 | ||
124 | Compiling the "bridge" Sample Application | |
125 | ----------------------------------------- | |
126 | ||
127 | #. Go to the example directory: | |
128 | ||
129 | .. code-block:: console | |
130 | ||
131 | export RTE_SDK=/path/to/rte_sdk | |
132 | cd ${RTE_SDK}/examples/netmap_compat | |
133 | ||
134 | #. Set the target (a default target is used if not specified). For example: | |
135 | ||
136 | .. code-block:: console | |
137 | ||
138 | export RTE_TARGET=x86_64-native-linuxapp-gcc | |
139 | ||
140 | See the *DPDK Getting Started Guide for Linux* for possible ``RTE_TARGET`` values. | |
141 | ||
142 | #. Build the application: | |
143 | ||
144 | .. code-block:: console | |
145 | ||
146 | make | |
147 | ||
148 | Running the "bridge" Sample Application | |
149 | --------------------------------------- | |
150 | ||
151 | The application requires a single command line option: | |
152 | ||
153 | .. code-block:: console | |
154 | ||
155 | ./build/bridge [EAL options] -- -i INTERFACE_A [-i INTERFACE_B] | |
156 | ||
157 | where, | |
158 | ||
159 | * ``-i INTERFACE``: Interface (DPDK port number) to use. | |
160 | ||
161 | If a single ``-i`` parameter is given, the interface will send back all the traffic it receives. | |
162 | If two ``-i`` parameters are given, the two interfaces form a bridge, | |
163 | where traffic received on one interface is replicated and sent to the other interface. | |
164 | ||
165 | For example, to run the application in a linuxapp environment using port 0 and 2: | |
166 | ||
167 | .. code-block:: console | |
168 | ||
169 | ./build/bridge [EAL options] -- -i 0 -i 2 | |
170 | ||
171 | Refer to the *DPDK Getting Started Guide for Linux* for general information on running applications and | |
172 | the Environment Abstraction Layer (EAL) options. | |
173 | ||
174 | Note that unlike a traditional bridge or the ``l2fwd`` sample application, no MAC address changes are done on the frames. | |
175 | Do not forget to take this into account when configuring a traffic generators and testing this sample application. |