]>
Commit | Line | Data |
---|---|---|
9f95a23c TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2010-2014 Intel Corporation. | |
7c673cae FG |
3 | |
4 | Netmap Compatibility Sample Application | |
5 | ======================================= | |
6 | ||
7 | Introduction | |
8 | ------------ | |
9 | ||
10 | The Netmap compatibility library provides a minimal set of APIs to give programs written against the Netmap APIs | |
11 | the ability to be run, with minimal changes to their source code, using the DPDK to perform the actual packet I/O. | |
12 | ||
13 | Since Netmap applications use regular system calls, like ``open()``, ``ioctl()`` and | |
14 | ``mmap()`` to communicate with the Netmap kernel module performing the packet I/O, | |
15 | the ``compat_netmap`` library provides a set of similar APIs to use in place of those system calls, | |
16 | effectively turning a Netmap application into a DPDK application. | |
17 | ||
18 | The provided library is currently minimal and doesn't support all the features that Netmap supports, | |
19 | but is enough to run simple applications, such as the bridge example detailed below. | |
20 | ||
21 | Knowledge of Netmap is required to understand the rest of this section. | |
22 | Please refer to the Netmap distribution for details about Netmap. | |
23 | ||
24 | Available APIs | |
25 | -------------- | |
26 | ||
27 | The library provides the following drop-in replacements for system calls usually used in Netmap applications: | |
28 | ||
29 | * ``rte_netmap_close()`` | |
30 | ||
31 | * ``rte_netmap_ioctl()`` | |
32 | ||
33 | * ``rte_netmap_open()`` | |
34 | ||
35 | * ``rte_netmap_mmap()`` | |
36 | ||
37 | * ``rte_netmap_poll()`` | |
38 | ||
39 | They use the same signature as their libc counterparts, and can be used as drop-in replacements in most cases. | |
40 | ||
41 | Caveats | |
42 | ------- | |
43 | ||
44 | Given the difference between the way Netmap and the DPDK approach packet I/O, | |
45 | 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. | |
46 | These may change as the library is updated: | |
47 | ||
48 | * Any system call that can potentially affect file descriptors cannot be used with a descriptor returned by the ``rte_netmap_open()`` function. | |
49 | ||
50 | Note that: | |
51 | ||
52 | * The ``rte_netmap_mmap()`` function merely returns the address of a DPDK memzone. | |
53 | The address, length, flags, offset, and other arguments are ignored. | |
54 | ||
55 | * The ``rte_netmap_poll()`` function only supports infinite (negative) or zero time outs. | |
56 | It effectively turns calls to the ``poll()`` system call made in a Netmap application into polling of the DPDK ports, | |
57 | changing the semantics of the usual POSIX defined poll. | |
58 | ||
59 | * Not all of Netmap's features are supported: host rings, | |
60 | slot flags and so on are not supported or are simply not relevant in the DPDK model. | |
61 | ||
62 | * The Netmap manual page states that "*a device obtained through /dev/netmap also supports the ioctl supported by network devices*". | |
63 | This is not the case with this compatibility layer. | |
64 | ||
65 | * The Netmap kernel module exposes a sysfs interface to change some internal parameters, such as the size of the shared memory region. | |
66 | This interface is not available when using this compatibility layer. | |
67 | ||
68 | Porting Netmap Applications | |
69 | --------------------------- | |
70 | ||
71 | Porting Netmap applications typically involves two major steps: | |
72 | ||
73 | * Changing the system calls to use their ``compat_netmap`` library counterparts. | |
74 | ||
75 | * Adding further DPDK initialization code. | |
76 | ||
77 | Since the ``compat_netmap`` functions have the same signature as the usual libc calls, the change is trivial in most cases. | |
78 | ||
11fdf7f2 | 79 | The usual DPDK initialization code involving ``rte_eal_init()`` and ``rte_pci_probe()`` |
7c673cae FG |
80 | has to be added to the Netmap application in the same way it is used in all other DPDK sample applications. |
81 | Please refer to the *DPDK Programmer's Guide* and example source code for details about initialization. | |
82 | ||
83 | In addition of the regular DPDK initialization code, | |
84 | the ported application needs to call initialization functions for the ``compat_netmap`` library, | |
85 | namely ``rte_netmap_init()`` and ``rte_netmap_init_port()``. | |
86 | ||
87 | These two initialization functions take ``compat_netmap`` specific data structures as parameters: | |
88 | ``struct rte_netmap_conf`` and ``struct rte_netmap_port_conf``. | |
89 | The structures' fields are Netmap related and are self-explanatory for developers familiar with Netmap. | |
90 | They are defined in ``$RTE_SDK/examples/netmap_compat/lib/compat_netmap.h``. | |
91 | ||
92 | The bridge application is an example largely based on the bridge example shipped with the Netmap distribution. | |
93 | It shows how a minimal Netmap application with minimal and straightforward source code changes can be run on top of the DPDK. | |
94 | Please refer to ``$RTE_SDK/examples/netmap_compat/bridge/bridge.c`` for an example of a ported application. | |
95 | ||
9f95a23c TL |
96 | Compiling the Application |
97 | ------------------------- | |
7c673cae | 98 | |
9f95a23c | 99 | To compile the sample application see :doc:`compiling`. |
7c673cae | 100 | |
9f95a23c | 101 | The application is located in the ``netmap_compat`` sub-directory. |
7c673cae FG |
102 | |
103 | Running the "bridge" Sample Application | |
104 | --------------------------------------- | |
105 | ||
106 | The application requires a single command line option: | |
107 | ||
108 | .. code-block:: console | |
109 | ||
110 | ./build/bridge [EAL options] -- -i INTERFACE_A [-i INTERFACE_B] | |
111 | ||
112 | where, | |
113 | ||
114 | * ``-i INTERFACE``: Interface (DPDK port number) to use. | |
115 | ||
116 | If a single ``-i`` parameter is given, the interface will send back all the traffic it receives. | |
117 | If two ``-i`` parameters are given, the two interfaces form a bridge, | |
118 | where traffic received on one interface is replicated and sent to the other interface. | |
119 | ||
9f95a23c | 120 | For example, to run the application in a linux environment using port 0 and 2: |
7c673cae FG |
121 | |
122 | .. code-block:: console | |
123 | ||
124 | ./build/bridge [EAL options] -- -i 0 -i 2 | |
125 | ||
126 | Refer to the *DPDK Getting Started Guide for Linux* for general information on running applications and | |
127 | the Environment Abstraction Layer (EAL) options. | |
128 | ||
129 | Note that unlike a traditional bridge or the ``l2fwd`` sample application, no MAC address changes are done on the frames. | |
130 | Do not forget to take this into account when configuring a traffic generators and testing this sample application. |