3 Package **libmemif** is a Golang adapter for the **libmemif library**
4 (`extras/libmemif` in the [VPP](https://wiki.fd.io/view/VPP) repository).
5 To differentiate between the adapter and the underlying C-written library,
6 labels `Go-libmemif` and `C-libmemif` are used in the documentation.
10 libmemif for Golang is build on the top of the original, C-written
11 libmemif library using `cgo`. It is therefore necessary to have C-libmemif
12 header files and the library itself installed in locations known
15 For example, to install C-libmemif system-wide into the standard
18 $ git clone https://gerrit.fd.io/r/vpp
19 $ cd vpp/extras/libmemif
27 Package **libmemif** is not part of the **GoVPP** core and as such it is
28 not included in the [make build](../../Makefile) target.
29 Instead, it has its own target in the [top-level Makefile](../../Makefile)
30 used to build the attached examples with the adapter:
37 All **Go-libmemif** public APIs can be found in [adapter.go](adapter.go).
38 Please see the comments for a more detailed description.
39 Additionally, a list of all errors thrown by libmemif can be found
40 in [error.go](error.go).
44 **libmemif** needs to be first initialized with `Init(appName)`.
45 This has to be done only once in the context of the entire process.
46 Make sure to call `Cleanup()` to release all the resources allocated
47 by **libmemif** before exiting your application. Consider calling
48 `Init()` followed by `Cleanup()` scheduled with `defer` in the `main()`
51 Log messages are by default printed to stdout. Use `SetLogger()` to use
52 your own customized logger (can be changed before `Init()`).
54 Once **libmemif** is initialized, new memif interfaces can be created
55 with `CreateInterface(config, callbacks)`. See `MemifConfig` structure
56 definition to learn about possible memif configuration options.
57 If successful, `CreateInterface()` returns an instance of `Memif`
58 structure representing the underlying memif interface.
60 Callbacks are optional and can be shared across multiple memif instances.
61 Available callbacks are:
62 1. **OnConnect**: called when the connection is established.
63 By the time the callback is called, the Rx/Tx queues are initialized
64 and ready for data transmission. Interrupt channels are also
65 created and ready to be read from.
66 The user is expected to start polling for input packets via repeated
67 calls to `Memif.RxBurst(queueID, count)` or to initiate select
68 on the interrupt channels obtained with `Get*InterruptChan()`,
69 depending on the Rx mode. By default, all memif Rx queues are created
70 in the interrupt mode, but this can be changed per-queue with
71 `Memif.SetRxMode(queueID, mode)`.
72 2. **OnDisconnect**: called after the connection was closed. Immediately
73 after the user callback returns, Rx/Tx queues and interrupt channels
74 are also deallocated. The user defined callback should therefore ensure
75 that all the Rx/Tx operations are stopped before it returns.
77 **libmemif** was designed for a maximum possible performance. Packets
78 are sent and received in bulks, rather than one-by-one, using
79 `Memif.TxBurst(queueID, packets)` and `Memif.RxBurst(queueID, count)`,
80 respectively. Memif connection can consists of multiple queues in both
81 directions. A queue is one-directional wait-free ring buffer.
82 It is the unit of parallelism for data transmission. The maximum possible
83 lock-free granularity is therefore one go routine for one queue.
85 Interrupt channel for one specific Rx queue can be obtained with
86 `GetQueueInterruptChan(queueID)` as opposed to `GetInterruptChan()`
87 for all the Rx queues. There is only one interrupt signal sent for
88 an entire burst of packets, therefore an interrupt handling routine
89 should repeatedly call RxBurst() until an empty slice of packets
90 is returned. This way it is ensured that there are no packets left
91 on the queue unread when the interrupt signal is cleared.
92 Study the `ReadAndPrintPackets()` function in [raw-data example](examples/raw-data/raw-data.go).
94 For **libmemif** the packet is just an array of bytes. It does not care
95 what the actual content is. It is not required for a packet to follow
96 any network protocol in order to get transported from one end to another.
97 See the type declaration for `RawPacketData` and its use in `Memif.TxBurst()`
98 and `Memif.RxBurst()`.
100 In order to remove a memif interface, call `Memif.Close()`. If the memif
101 is in the connected state, the connection is first properly closed.
102 Do not touch memif after it was closed, let garbage collector to remove
103 the `Memif` instance. In the end, `Cleanup()` will also ensure that all
104 active memif interfaces are closed before the cleanup finalizes.
106 To use libmemif with `google/gopacket`, simply call `Memif.NewPacketHandle()`
107 to create `google/gopacket/PacketDataSource` from memif queue. After this you
108 can use gopacket API to read from `MemifPacketHandle` as normal. You can pass
109 optional `rxCount` when creating the packet handle and then when reading data,
110 handle will try to read more packets at once and cache them for next iteration.
111 Handle also includes convenience method `MemifPacketHandle.WritePacketData()`
112 that is simply calling 1 `Memif.TxBurst()` for provided data.
116 **Go-libmemif** ships with two simple examples demonstrating the usage
117 of the package with a detailed commentary.
118 The examples can be found in the subdirectory [examples](./examples).
120 #### Raw data (libmemif <-> libmemif)
122 *raw-data* is a basic example showing how to create a memif interface,
123 handle events through callbacks and perform Rx/Tx of raw data. Before
124 handling an actual packets it is important to understand the skeleton
125 of libmemif-based applications.
127 Since VPP expects proper packet data, it is not very useful to connect
128 *raw-data* example with VPP, even though it will work, since all
129 the received data will get dropped on the VPP side.
131 To create a connection of two raw-data instances, start two processes
132 concurrently in an arbitrary order:
135 $ cd extras/libmemif/examples/raw-data
140 $ cd extras/libmemif/examples/raw-data
144 Every 3 seconds both sides send 3 raw-data packets to the opposite end
145 through each of the 3 queues. The received packets are printed to stdout.
147 Stop an instance of *raw-data* with an interrupt signal (^C).
149 #### Jumbo Frames Raw data (libmemif <-> libmemif)
151 *jumbo-frames* is simple example how to send larger and larger jumbo
152 packets with libmemif adapter. This is simple copy of *raw-data* but with
153 sending larger packets, so for more information read its code and documentation.
157 *icmp-responder* is a simple example showing how to answer APR and ICMP
158 echo requests through a memif interface. Package `google/gopacket` is
159 used to decode and construct packets.
161 The appropriate VPP configuration for the opposite memif is:
163 vpp$ create memif socket id 1 filename /tmp/icmp-responder-example
164 vpp$ create interface memif id 1 socket-id 1 slave secret secret no-zero-copy
165 vpp$ set int state memif1/1 up
166 vpp$ set int ip address memif1/1 192.168.1.2/24
169 To start the example, simply type:
171 root$ ./icmp-responder
174 *icmp-responder* needs to be run as root so that it can access the socket
177 Normally, the memif interface is in the master mode. Pass CLI flag `--slave`
178 to create memif in the slave mode:
180 root$ ./icmp-responder --slave
183 Don't forget to put the opposite memif into the master mode in that case.
185 To verify the connection, run:
187 vpp$ ping 192.168.1.1
188 64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=.6974 ms
189 64 bytes from 192.168.1.1: icmp_seq=3 ttl=255 time=.6310 ms
190 64 bytes from 192.168.1.1: icmp_seq=4 ttl=255 time=1.0350 ms
191 64 bytes from 192.168.1.1: icmp_seq=5 ttl=255 time=.5359 ms
193 Statistics: 5 sent, 4 received, 20% packet loss
195 Time IP4 Flags Ethernet Interface
196 68.5648 192.168.1.1 D aa:aa:aa:aa:aa:aa memif0/1
198 *Note*: it is expected that the first ping is shown as lost.
199 It was actually converted to an ARP request. This is a VPP
200 specific feature common to all interface types.
202 Stop the example with an interrupt signal (^C).
204 #### GoPacket ICMP Responder
206 *gopacket* is a simple example showing how to answer APR and ICMP echo
207 requests through a memif interface. This example is mostly identical
208 to icmp-responder example, but it is using MemifPacketHandle API to
209 read and write packets using gopacket API.
211 The appropriate VPP configuration for the opposite memif is:
213 vpp$ create memif socket id 1 filename /tmp/gopacket-example
214 vpp$ create interface memif id 1 socket-id 1 slave secret secret no-zero-copy
215 vpp$ set int state memif1/1 up
216 vpp$ set int ip address memif1/1 192.168.1.2/24
219 To start the example, simply type:
224 gopacket needs to be run as root so that it can access the socket
227 Normally, the memif interface is in the master mode. Pass CLI flag "--slave"
228 to create memif in the slave mode:
230 root$ ./gopacket --slave
233 Don't forget to put the opposite memif into the master mode in that case.
235 To verify the connection, run:
237 vpp$ ping 192.168.1.1
238 64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=.6974 ms
239 64 bytes from 192.168.1.1: icmp_seq=3 ttl=255 time=.6310 ms
240 64 bytes from 192.168.1.1: icmp_seq=4 ttl=255 time=1.0350 ms
241 64 bytes from 192.168.1.1: icmp_seq=5 ttl=255 time=.5359 ms
243 Statistics: 5 sent, 4 received, 20% packet loss
245 Time IP4 Flags Ethernet Interface
246 68.5648 192.168.1.1 D aa:aa:aa:aa:aa:aa memif0/1
249 *Note*: it is expected that the first ping is shown as lost.
250 It was actually converted to an ARP request. This is a VPP
251 specific feature common to all interface types.
253 Stop the example with an interrupt signal (^C).