2 *------------------------------------------------------------------
3 * Copyright (c) 2020 Cisco and/or its affiliates.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at:
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 *------------------------------------------------------------------
18 // Package memif provides the implementation of shared memory interface (memif).
20 // Memif network interfaces communicate using UNIX domain socket. This socket
21 // must be first created using NewSocket(). Then interfaces can be added
22 // to this socket using NewInterface(). To start communication on each socket
23 // socket.StartPolling() must be called. socket.StopPolling() will stop
24 // the communication. When the interface changes link status Connected and
25 // Disconencted callbacks set in Arguments for each interface are called
26 // respectively. Once the interface is connected rx and tx queues can be
27 // aquired using interface.GetRxQueue() and interface.GetTxQueue().
28 // Packets can be transmitted by calling queue.ReadPacket() on rx queues and
29 // queue.WritePacket() on tx queues. If the interface is disconnected
30 // queue.ReadPacket() and queue.WritePacket() MUST not be called.
32 // Data transmission is backed by shared memory. The driver works in
33 // promiscuous mode only.
44 DefaultSocketFilename = "/run/vpp/memif.sock"
45 DefaultNumQueuePairs = 1
46 DefaultLog2RingSize = 10
47 DefaultPacketBufferSize = 2048
50 const mfd_allow_sealing = 2
51 const sys_memfd_create = 319
52 const f_add_seals = 1033
53 const f_seal_shrink = 0x0002
55 const efd_nonblock = 04000
57 // ConnectedFunc is a callback called when an interface is connected
58 type ConnectedFunc func(i *Interface) error
60 // DisconnectedFunc is a callback called when an interface is disconnected
61 type DisconnectedFunc func(i *Interface) error
63 // MemoryConfig represents shared memory configuration
64 type MemoryConfig struct {
65 NumQueuePairs uint16 // number of queue pairs
66 Log2RingSize uint8 // ring size as log2
67 PacketBufferSize uint32 // size of single packet buffer
70 // Arguments represent interface configuration
71 type Arguments struct {
72 Id uint32 // Interface identifier unique across socket. Used to identify peer interface when connecting
73 IsMaster bool // Interface role master/slave
75 Secret [24]byte // optional parameter, secrets of the interfaces must match if they are to connect
76 MemoryConfig MemoryConfig
77 ConnectedFunc ConnectedFunc // callback called when interface changes status to connected
78 DisconnectedFunc DisconnectedFunc // callback called when interface changes status to disconnected
79 PrivateData interface{} // private data used by client program
82 // memoryRegion represents a shared memory mapped file
83 type memoryRegion struct {
87 packetBufferOffset uint32
90 // Queue represents rx or tx queue
99 // Interface represents memif network interface
100 type Interface struct {
103 privateData interface{}
104 listRef *list.Element
109 regions []memoryRegion
114 // IsMaster returns true if the interfaces role is master, else returns false
115 func (i *Interface) IsMaster() bool {
116 return i.args.IsMaster
119 // GetRemoteName returns the name of the application on which the peer
121 func (i *Interface) GetRemoteName() string {
125 // GetPeerName returns peer interfaces name
126 func (i *Interface) GetPeerName() string {
130 // GetName returens interfaces name
131 func (i *Interface) GetName() string {
135 // GetMemoryConfig returns interfaces active memory config.
136 // If interface is not connected the config is invalid.
137 func (i *Interface) GetMemoryConfig() MemoryConfig {
141 // GetRxQueue returns an rx queue specified by queue index
142 func (i *Interface) GetRxQueue(qid int) (*Queue, error) {
143 if qid >= len(i.rxQueues) {
144 return nil, fmt.Errorf("Invalid Queue index")
146 return &i.rxQueues[qid], nil
149 // GetRxQueue returns a tx queue specified by queue index
150 func (i *Interface) GetTxQueue(qid int) (*Queue, error) {
151 if qid >= len(i.txQueues) {
152 return nil, fmt.Errorf("Invalid Queue index")
154 return &i.txQueues[qid], nil
157 // GetEventFd returns queues interrupt event fd
158 func (q *Queue) GetEventFd() (int, error) {
159 return q.interruptFd, nil
162 // GetFilename returns sockets filename
163 func (socket *Socket) GetFilename() string {
164 return socket.filename
167 // close closes the queue
168 func (q *Queue) close() {
169 syscall.Close(q.interruptFd)
172 // IsConnecting returns true if the interface is connecting
173 func (i *Interface) IsConnecting() bool {
180 // IsConnected returns true if the interface is connected
181 func (i *Interface) IsConnected() bool {
182 if i.cc != nil && i.cc.isConnected {
188 // Disconnect disconnects the interface
189 func (i *Interface) Disconnect() (err error) {
191 // close control and disconenct interface
192 return i.cc.close(true, "Interface disconnected")
197 // disconnect finalizes interface disconnection
198 func (i *Interface) disconnect() (err error) {
199 if i.cc == nil { // disconnected
203 err = i.args.DisconnectedFunc(i)
205 return fmt.Errorf("DisconnectedFunc: ", err)
208 for _, q := range i.txQueues {
211 i.txQueues = []Queue{}
213 for _, q := range i.rxQueues {
216 i.rxQueues = []Queue{}
219 for _, r := range i.regions {
220 err = syscall.Munmap(r.data)
224 err = syscall.Close(r.fd)
238 // Delete deletes the interface
239 func (i *Interface) Delete() (err error) {
242 // remove referance on socket
243 i.socket.interfaceList.Remove(i.listRef)
249 // GetSocket returns the socket the interface belongs to
250 func (i *Interface) GetSocket() *Socket {
254 // GetPrivateDate returns interfaces private data
255 func (i *Interface) GetPrivateData() interface{} {
256 return i.args.PrivateData
259 // GetId returns interfaces id
260 func (i *Interface) GetId() uint32 {
264 // RoleToString returns 'Master' if isMaster os true, else returns 'Slave'
265 func RoleToString(isMaster bool) string {
272 // RequestConnection is used by slave interface to connect to a socket and
273 // create a control channel
274 func (i *Interface) RequestConnection() error {
276 return fmt.Errorf("Only slave can request connection")
279 fd, err := syscall.Socket(syscall.AF_UNIX, syscall.SOCK_SEQPACKET, 0)
281 return fmt.Errorf("Failed to create UNIX domain socket: %v", err)
283 usa := &syscall.SockaddrUnix{Name: i.socket.filename}
285 // Connect to listener socket
286 err = syscall.Connect(fd, usa)
288 return fmt.Errorf("Failed to connect socket %s : %v", i.socket.filename, err)
291 // Create control channel
292 i.cc, err = i.socket.addControlChannel(fd, i)
294 return fmt.Errorf("Failed to create control channel: %v", err)
300 // NewInterface returns a new memif network interface. When creating an interface
301 // it's id must be unique across socket with the exception of loopback interface
302 // in which case the id is the same but role differs
303 func (socket *Socket) NewInterface(args *Arguments) (*Interface, error) {
305 // make sure the ID is unique on this socket
306 for elt := socket.interfaceList.Front(); elt != nil; elt = elt.Next() {
307 i, ok := elt.Value.(*Interface)
309 if i.args.Id == args.Id && i.args.IsMaster == args.IsMaster {
310 return nil, fmt.Errorf("Interface with id %u role %s already exists on this socket", args.Id, RoleToString(args.IsMaster))
315 // copy interface configuration
319 // set default values
320 if i.args.MemoryConfig.NumQueuePairs == 0 {
321 i.args.MemoryConfig.NumQueuePairs = DefaultNumQueuePairs
323 if i.args.MemoryConfig.Log2RingSize == 0 {
324 i.args.MemoryConfig.Log2RingSize = DefaultLog2RingSize
326 if i.args.MemoryConfig.PacketBufferSize == 0 {
327 i.args.MemoryConfig.PacketBufferSize = DefaultPacketBufferSize
332 // append interface to the list
333 i.listRef = socket.interfaceList.PushBack(&i)
336 if socket.listener == nil {
337 err = socket.addListener()
339 return nil, fmt.Errorf("Failed to create listener channel: %s", err)
347 // eventFd returns an eventfd (SYS_EVENTFD2)
348 func eventFd() (efd int, err error) {
349 u_efd, _, errno := syscall.Syscall(syscall.SYS_EVENTFD2, uintptr(0), uintptr(efd_nonblock), 0)
351 return -1, os.NewSyscallError("eventfd", errno)
353 return int(u_efd), nil
356 // addRegions creates and adds a new memory region to the interface (slave only)
357 func (i *Interface) addRegion(hasPacketBuffers bool, hasRings bool) (err error) {
361 r.packetBufferOffset = uint32((i.run.NumQueuePairs + i.run.NumQueuePairs) * (ringSize + descSize*(1<<i.run.Log2RingSize)))
363 r.packetBufferOffset = 0
366 if hasPacketBuffers {
367 r.size = uint64(r.packetBufferOffset + i.run.PacketBufferSize*uint32(1<<i.run.Log2RingSize)*uint32(i.run.NumQueuePairs+i.run.NumQueuePairs))
369 r.size = uint64(r.packetBufferOffset)
372 r.fd, err = memfdCreate()
377 _, _, errno := syscall.Syscall(syscall.SYS_FCNTL, uintptr(r.fd), uintptr(f_add_seals), uintptr(f_seal_shrink))
380 return fmt.Errorf("memfdCreate: %s", os.NewSyscallError("fcntl", errno))
383 err = syscall.Ftruncate(r.fd, int64(r.size))
387 return fmt.Errorf("memfdCreate: %s", err)
390 r.data, err = syscall.Mmap(r.fd, 0, int(r.size), syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED)
392 return fmt.Errorf("addRegion: %s", err)
395 i.regions = append(i.regions, r)
400 // initializeRegions initializes interfaces regions (slave only)
401 func (i *Interface) initializeRegions() (err error) {
403 err = i.addRegion(true, true)
405 return fmt.Errorf("initializeRegions: %s", err)
411 // initializeQueues initializes interfaces queues (slave only)
412 func (i *Interface) initializeQueues() (err error) {
420 desc.setLength(int(i.run.PacketBufferSize))
422 for qid := 0; qid < int(i.run.NumQueuePairs); qid++ {
425 ring: i.newRing(0, ringTypeS2M, qid),
430 q.ring.setCookie(cookie)
432 q.interruptFd, err = eventFd()
437 i.txQueues = append(i.txQueues, *q)
439 for j := 0; j < q.ring.size; j++ {
440 slot = qid*q.ring.size + j
441 desc.setOffset(int(i.regions[0].packetBufferOffset + uint32(slot)*i.run.PacketBufferSize))
442 q.putDescBuf(slot, desc)
445 for qid := 0; qid < int(i.run.NumQueuePairs); qid++ {
448 ring: i.newRing(0, ringTypeM2S, qid),
453 q.ring.setCookie(cookie)
455 q.interruptFd, err = eventFd()
460 i.rxQueues = append(i.rxQueues, *q)
462 for j := 0; j < q.ring.size; j++ {
463 slot = qid*q.ring.size + j
464 desc.setOffset(int(i.regions[0].packetBufferOffset + uint32(slot)*i.run.PacketBufferSize))
465 q.putDescBuf(slot, desc)
472 // connect finalizes interface connection
473 func (i *Interface) connect() (err error) {
474 for rid, _ := range i.regions {
477 r.data, err = syscall.Mmap(r.fd, 0, int(r.size), syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED)
479 return fmt.Errorf("Mmap: %s", err)
484 for _, q := range i.txQueues {
487 if q.ring.getCookie() != cookie {
488 return fmt.Errorf("Wrong cookie")
495 for _, q := range i.rxQueues {
498 if q.ring.getCookie() != cookie {
499 return fmt.Errorf("Wrong cookie")
506 return i.args.ConnectedFunc(i)