jcs.org
qemu with hax to log dma reads & writes
jcs.org/2018/11/12/vfio
1# -*- Mode: Python -*-
2#
3
4##
5# = Net devices
6##
7
8{ 'include': 'common.json' }
9
10##
11# @set_link:
12#
13# Sets the link status of a virtual network adapter.
14#
15# @name: the device name of the virtual network adapter
16#
17# @up: true to set the link status to be up
18#
19# Returns: Nothing on success
20# If @name is not a valid network device, DeviceNotFound
21#
22# Since: 0.14.0
23#
24# Notes: Not all network adapters support setting link status. This command
25# will succeed even if the network adapter does not support link status
26# notification.
27#
28# Example:
29#
30# -> { "execute": "set_link",
31# "arguments": { "name": "e1000.0", "up": false } }
32# <- { "return": {} }
33#
34##
35{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
36
37##
38# @netdev_add:
39#
40# Add a network backend.
41#
42# Additional arguments depend on the type.
43#
44# Since: 0.14.0
45#
46# Returns: Nothing on success
47# If @type is not a valid network backend, DeviceNotFound
48#
49# Example:
50#
51# -> { "execute": "netdev_add",
52# "arguments": { "type": "user", "id": "netdev1",
53# "dnssearch": "example.org" } }
54# <- { "return": {} }
55#
56##
57{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true }
58
59##
60# @netdev_del:
61#
62# Remove a network backend.
63#
64# @id: the name of the network backend to remove
65#
66# Returns: Nothing on success
67# If @id is not a valid network backend, DeviceNotFound
68#
69# Since: 0.14.0
70#
71# Example:
72#
73# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
74# <- { "return": {} }
75#
76##
77{ 'command': 'netdev_del', 'data': {'id': 'str'} }
78
79##
80# @NetLegacyNicOptions:
81#
82# Create a new Network Interface Card.
83#
84# @netdev: id of -netdev to connect to
85#
86# @macaddr: MAC address
87#
88# @model: device model (e1000, rtl8139, virtio etc.)
89#
90# @addr: PCI device address
91#
92# @vectors: number of MSI-x vectors, 0 to disable MSI-X
93#
94# Since: 1.2
95##
96{ 'struct': 'NetLegacyNicOptions',
97 'data': {
98 '*netdev': 'str',
99 '*macaddr': 'str',
100 '*model': 'str',
101 '*addr': 'str',
102 '*vectors': 'uint32' } }
103
104##
105# @NetdevUserOptions:
106#
107# Use the user mode network stack which requires no administrator privilege to
108# run.
109#
110# @hostname: client hostname reported by the builtin DHCP server
111#
112# @restrict: isolate the guest from the host
113#
114# @ipv4: whether to support IPv4, default true for enabled
115# (since 2.6)
116#
117# @ipv6: whether to support IPv6, default true for enabled
118# (since 2.6)
119#
120# @ip: legacy parameter, use net= instead
121#
122# @net: IP network address that the guest will see, in the
123# form addr[/netmask] The netmask is optional, and can be
124# either in the form a.b.c.d or as a number of valid top-most
125# bits. Default is 10.0.2.0/24.
126#
127# @host: guest-visible address of the host
128#
129# @tftp: root directory of the built-in TFTP server
130#
131# @bootfile: BOOTP filename, for use with tftp=
132#
133# @dhcpstart: the first of the 16 IPs the built-in DHCP server can
134# assign
135#
136# @dns: guest-visible address of the virtual nameserver
137#
138# @dnssearch: list of DNS suffixes to search, passed as DHCP option
139# to the guest
140#
141# @domainname: guest-visible domain name of the virtual nameserver
142# (since 3.0)
143#
144# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since
145# 2.6). The network prefix is given in the usual
146# hexadecimal IPv6 address notation.
147#
148# @ipv6-prefixlen: IPv6 network prefix length (default is 64)
149# (since 2.6)
150#
151# @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
152#
153# @ipv6-dns: guest-visible IPv6 address of the virtual
154# nameserver (since 2.6)
155#
156# @smb: root directory of the built-in SMB server
157#
158# @smbserver: IP address of the built-in SMB server
159#
160# @hostfwd: redirect incoming TCP or UDP host connections to guest
161# endpoints
162#
163# @guestfwd: forward guest TCP connections
164#
165# @tftp-server-name: RFC2132 "TFTP server name" string (Since 3.1)
166#
167# Since: 1.2
168##
169{ 'struct': 'NetdevUserOptions',
170 'data': {
171 '*hostname': 'str',
172 '*restrict': 'bool',
173 '*ipv4': 'bool',
174 '*ipv6': 'bool',
175 '*ip': 'str',
176 '*net': 'str',
177 '*host': 'str',
178 '*tftp': 'str',
179 '*bootfile': 'str',
180 '*dhcpstart': 'str',
181 '*dns': 'str',
182 '*dnssearch': ['String'],
183 '*domainname': 'str',
184 '*ipv6-prefix': 'str',
185 '*ipv6-prefixlen': 'int',
186 '*ipv6-host': 'str',
187 '*ipv6-dns': 'str',
188 '*smb': 'str',
189 '*smbserver': 'str',
190 '*hostfwd': ['String'],
191 '*guestfwd': ['String'],
192 '*tftp-server-name': 'str' } }
193
194##
195# @NetdevTapOptions:
196#
197# Used to configure a host TAP network interface backend.
198#
199# @ifname: interface name
200#
201# @fd: file descriptor of an already opened tap
202#
203# @fds: multiple file descriptors of already opened multiqueue capable
204# tap
205#
206# @script: script to initialize the interface
207#
208# @downscript: script to shut down the interface
209#
210# @br: bridge name (since 2.8)
211#
212# @helper: command to execute to configure bridge
213#
214# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
215#
216# @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface
217#
218# @vhost: enable vhost-net network accelerator
219#
220# @vhostfd: file descriptor of an already opened vhost net device
221#
222# @vhostfds: file descriptors of multiple already opened vhost net
223# devices
224#
225# @vhostforce: vhost on for non-MSIX virtio guests
226#
227# @queues: number of queues to be created for multiqueue capable tap
228#
229# @poll-us: maximum number of microseconds that could
230# be spent on busy polling for tap (since 2.7)
231#
232# Since: 1.2
233##
234{ 'struct': 'NetdevTapOptions',
235 'data': {
236 '*ifname': 'str',
237 '*fd': 'str',
238 '*fds': 'str',
239 '*script': 'str',
240 '*downscript': 'str',
241 '*br': 'str',
242 '*helper': 'str',
243 '*sndbuf': 'size',
244 '*vnet_hdr': 'bool',
245 '*vhost': 'bool',
246 '*vhostfd': 'str',
247 '*vhostfds': 'str',
248 '*vhostforce': 'bool',
249 '*queues': 'uint32',
250 '*poll-us': 'uint32'} }
251
252##
253# @NetdevSocketOptions:
254#
255# Socket netdevs are used to establish a network connection to another
256# QEMU virtual machine via a TCP socket.
257#
258# @fd: file descriptor of an already opened socket
259#
260# @listen: port number, and optional hostname, to listen on
261#
262# @connect: port number, and optional hostname, to connect to
263#
264# @mcast: UDP multicast address and port number
265#
266# @localaddr: source address and port for multicast and udp packets
267#
268# @udp: UDP unicast address and port number
269#
270# Since: 1.2
271##
272{ 'struct': 'NetdevSocketOptions',
273 'data': {
274 '*fd': 'str',
275 '*listen': 'str',
276 '*connect': 'str',
277 '*mcast': 'str',
278 '*localaddr': 'str',
279 '*udp': 'str' } }
280
281##
282# @NetdevL2TPv3Options:
283#
284# Configure an Ethernet over L2TPv3 tunnel.
285#
286# @src: source address
287#
288# @dst: destination address
289#
290# @srcport: source port - mandatory for udp, optional for ip
291#
292# @dstport: destination port - mandatory for udp, optional for ip
293#
294# @ipv6: force the use of ipv6
295#
296# @udp: use the udp version of l2tpv3 encapsulation
297#
298# @cookie64: use 64 bit coookies
299#
300# @counter: have sequence counter
301#
302# @pincounter: pin sequence counter to zero -
303# workaround for buggy implementations or
304# networks with packet reorder
305#
306# @txcookie: 32 or 64 bit transmit cookie
307#
308# @rxcookie: 32 or 64 bit receive cookie
309#
310# @txsession: 32 bit transmit session
311#
312# @rxsession: 32 bit receive session - if not specified
313# set to the same value as transmit
314#
315# @offset: additional offset - allows the insertion of
316# additional application-specific data before the packet payload
317#
318# Since: 2.1
319##
320{ 'struct': 'NetdevL2TPv3Options',
321 'data': {
322 'src': 'str',
323 'dst': 'str',
324 '*srcport': 'str',
325 '*dstport': 'str',
326 '*ipv6': 'bool',
327 '*udp': 'bool',
328 '*cookie64': 'bool',
329 '*counter': 'bool',
330 '*pincounter': 'bool',
331 '*txcookie': 'uint64',
332 '*rxcookie': 'uint64',
333 'txsession': 'uint32',
334 '*rxsession': 'uint32',
335 '*offset': 'uint32' } }
336
337##
338# @NetdevVdeOptions:
339#
340# Connect to a vde switch running on the host.
341#
342# @sock: socket path
343#
344# @port: port number
345#
346# @group: group owner of socket
347#
348# @mode: permissions for socket
349#
350# Since: 1.2
351##
352{ 'struct': 'NetdevVdeOptions',
353 'data': {
354 '*sock': 'str',
355 '*port': 'uint16',
356 '*group': 'str',
357 '*mode': 'uint16' } }
358
359##
360# @NetdevBridgeOptions:
361#
362# Connect a host TAP network interface to a host bridge device.
363#
364# @br: bridge name
365#
366# @helper: command to execute to configure bridge
367#
368# Since: 1.2
369##
370{ 'struct': 'NetdevBridgeOptions',
371 'data': {
372 '*br': 'str',
373 '*helper': 'str' } }
374
375##
376# @NetdevHubPortOptions:
377#
378# Connect two or more net clients through a software hub.
379#
380# @hubid: hub identifier number
381# @netdev: used to connect hub to a netdev instead of a device (since 2.12)
382#
383# Since: 1.2
384##
385{ 'struct': 'NetdevHubPortOptions',
386 'data': {
387 'hubid': 'int32',
388 '*netdev': 'str' } }
389
390##
391# @NetdevNetmapOptions:
392#
393# Connect a client to a netmap-enabled NIC or to a VALE switch port
394#
395# @ifname: Either the name of an existing network interface supported by
396# netmap, or the name of a VALE port (created on the fly).
397# A VALE port name is in the form 'valeXXX:YYY', where XXX and
398# YYY are non-negative integers. XXX identifies a switch and
399# YYY identifies a port of the switch. VALE ports having the
400# same XXX are therefore connected to the same switch.
401#
402# @devname: path of the netmap device (default: '/dev/netmap').
403#
404# Since: 2.0
405##
406{ 'struct': 'NetdevNetmapOptions',
407 'data': {
408 'ifname': 'str',
409 '*devname': 'str' } }
410
411##
412# @NetdevVhostUserOptions:
413#
414# Vhost-user network backend
415#
416# @chardev: name of a unix socket chardev
417#
418# @vhostforce: vhost on for non-MSIX virtio guests (default: false).
419#
420# @queues: number of queues to be created for multiqueue vhost-user
421# (default: 1) (Since 2.5)
422#
423# Since: 2.1
424##
425{ 'struct': 'NetdevVhostUserOptions',
426 'data': {
427 'chardev': 'str',
428 '*vhostforce': 'bool',
429 '*queues': 'int' } }
430
431##
432# @NetdevVhostVDPAOptions:
433#
434# Vhost-vdpa network backend
435#
436# vDPA device is a device that uses a datapath which complies with the virtio
437# specifications with a vendor specific control path.
438#
439# @vhostdev: path of vhost-vdpa device
440# (default:'/dev/vhost-vdpa-0')
441#
442# @queues: number of queues to be created for multiqueue vhost-vdpa
443# (default: 1)
444#
445# Since: 5.1
446##
447{ 'struct': 'NetdevVhostVDPAOptions',
448 'data': {
449 '*vhostdev': 'str',
450 '*queues': 'int' } }
451
452##
453# @NetClientDriver:
454#
455# Available netdev drivers.
456#
457# Since: 2.7
458#
459# @vhost-vdpa since 5.1
460##
461{ 'enum': 'NetClientDriver',
462 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
463 'bridge', 'hubport', 'netmap', 'vhost-user', 'vhost-vdpa' ] }
464
465##
466# @Netdev:
467#
468# Captures the configuration of a network device.
469#
470# @id: identifier for monitor commands.
471#
472# @type: Specify the driver used for interpreting remaining arguments.
473#
474# Since: 1.2
475#
476# 'l2tpv3' - since 2.1
477##
478{ 'union': 'Netdev',
479 'base': { 'id': 'str', 'type': 'NetClientDriver' },
480 'discriminator': 'type',
481 'data': {
482 'nic': 'NetLegacyNicOptions',
483 'user': 'NetdevUserOptions',
484 'tap': 'NetdevTapOptions',
485 'l2tpv3': 'NetdevL2TPv3Options',
486 'socket': 'NetdevSocketOptions',
487 'vde': 'NetdevVdeOptions',
488 'bridge': 'NetdevBridgeOptions',
489 'hubport': 'NetdevHubPortOptions',
490 'netmap': 'NetdevNetmapOptions',
491 'vhost-user': 'NetdevVhostUserOptions',
492 'vhost-vdpa': 'NetdevVhostVDPAOptions' } }
493
494##
495# @NetFilterDirection:
496#
497# Indicates whether a netfilter is attached to a netdev's transmit queue or
498# receive queue or both.
499#
500# @all: the filter is attached both to the receive and the transmit
501# queue of the netdev (default).
502#
503# @rx: the filter is attached to the receive queue of the netdev,
504# where it will receive packets sent to the netdev.
505#
506# @tx: the filter is attached to the transmit queue of the netdev,
507# where it will receive packets sent by the netdev.
508#
509# Since: 2.5
510##
511{ 'enum': 'NetFilterDirection',
512 'data': [ 'all', 'rx', 'tx' ] }
513
514##
515# @RxState:
516#
517# Packets receiving state
518#
519# @normal: filter assigned packets according to the mac-table
520#
521# @none: don't receive any assigned packet
522#
523# @all: receive all assigned packets
524#
525# Since: 1.6
526##
527{ 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }
528
529##
530# @RxFilterInfo:
531#
532# Rx-filter information for a NIC.
533#
534# @name: net client name
535#
536# @promiscuous: whether promiscuous mode is enabled
537#
538# @multicast: multicast receive state
539#
540# @unicast: unicast receive state
541#
542# @vlan: vlan receive state (Since 2.0)
543#
544# @broadcast-allowed: whether to receive broadcast
545#
546# @multicast-overflow: multicast table is overflowed or not
547#
548# @unicast-overflow: unicast table is overflowed or not
549#
550# @main-mac: the main macaddr string
551#
552# @vlan-table: a list of active vlan id
553#
554# @unicast-table: a list of unicast macaddr string
555#
556# @multicast-table: a list of multicast macaddr string
557#
558# Since: 1.6
559##
560{ 'struct': 'RxFilterInfo',
561 'data': {
562 'name': 'str',
563 'promiscuous': 'bool',
564 'multicast': 'RxState',
565 'unicast': 'RxState',
566 'vlan': 'RxState',
567 'broadcast-allowed': 'bool',
568 'multicast-overflow': 'bool',
569 'unicast-overflow': 'bool',
570 'main-mac': 'str',
571 'vlan-table': ['int'],
572 'unicast-table': ['str'],
573 'multicast-table': ['str'] }}
574
575##
576# @query-rx-filter:
577#
578# Return rx-filter information for all NICs (or for the given NIC).
579#
580# @name: net client name
581#
582# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
583# Returns an error if the given @name doesn't exist, or given
584# NIC doesn't support rx-filter querying, or given net client
585# isn't a NIC.
586#
587# Since: 1.6
588#
589# Example:
590#
591# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
592# <- { "return": [
593# {
594# "promiscuous": true,
595# "name": "vnet0",
596# "main-mac": "52:54:00:12:34:56",
597# "unicast": "normal",
598# "vlan": "normal",
599# "vlan-table": [
600# 4,
601# 0
602# ],
603# "unicast-table": [
604# ],
605# "multicast": "normal",
606# "multicast-overflow": false,
607# "unicast-overflow": false,
608# "multicast-table": [
609# "01:00:5e:00:00:01",
610# "33:33:00:00:00:01",
611# "33:33:ff:12:34:56"
612# ],
613# "broadcast-allowed": false
614# }
615# ]
616# }
617#
618##
619{ 'command': 'query-rx-filter',
620 'data': { '*name': 'str' },
621 'returns': ['RxFilterInfo'] }
622
623##
624# @NIC_RX_FILTER_CHANGED:
625#
626# Emitted once until the 'query-rx-filter' command is executed, the first event
627# will always be emitted
628#
629# @name: net client name
630#
631# @path: device path
632#
633# Since: 1.6
634#
635# Example:
636#
637# <- { "event": "NIC_RX_FILTER_CHANGED",
638# "data": { "name": "vnet0",
639# "path": "/machine/peripheral/vnet0/virtio-backend" },
640# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
641# }
642#
643##
644{ 'event': 'NIC_RX_FILTER_CHANGED',
645 'data': { '*name': 'str', 'path': 'str' } }
646
647##
648# @AnnounceParameters:
649#
650# Parameters for self-announce timers
651#
652# @initial: Initial delay (in ms) before sending the first GARP/RARP
653# announcement
654#
655# @max: Maximum delay (in ms) between GARP/RARP announcement packets
656#
657# @rounds: Number of self-announcement attempts
658#
659# @step: Delay increase (in ms) after each self-announcement attempt
660#
661# @interfaces: An optional list of interface names, which restricts the
662# announcement to the listed interfaces. (Since 4.1)
663#
664# @id: A name to be used to identify an instance of announce-timers
665# and to allow it to modified later. Not for use as
666# part of the migration parameters. (Since 4.1)
667#
668# Since: 4.0
669##
670
671{ 'struct': 'AnnounceParameters',
672 'data': { 'initial': 'int',
673 'max': 'int',
674 'rounds': 'int',
675 'step': 'int',
676 '*interfaces': ['str'],
677 '*id' : 'str' } }
678
679##
680# @announce-self:
681#
682# Trigger generation of broadcast RARP frames to update network switches.
683# This can be useful when network bonds fail-over the active slave.
684#
685# Example:
686#
687# -> { "execute": "announce-self",
688# "arguments": {
689# "initial": 50, "max": 550, "rounds": 10, "step": 50,
690# "interfaces": ["vn2", "vn3"], "id": "bob" } }
691# <- { "return": {} }
692#
693# Since: 4.0
694##
695{ 'command': 'announce-self', 'boxed': true,
696 'data' : 'AnnounceParameters'}
697
698##
699# @FAILOVER_NEGOTIATED:
700#
701# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation.
702# Failover primary devices which were hidden (not hotplugged when requested)
703# before will now be hotplugged by the virtio-net standby device.
704#
705# device-id: QEMU device id of the unplugged device
706# Since: 4.2
707#
708# Example:
709#
710# <- { "event": "FAILOVER_NEGOTIATED",
711# "data": "net1" }
712#
713##
714{ 'event': 'FAILOVER_NEGOTIATED',
715 'data': {'device-id': 'str'} }