migration/rdma: prevent from double free the same mr
[qemu/kevin.git] / qapi / block-export.json
blob0ed63442a819fa1059f876cfde899866af82022c
1 # -*- Mode: Python -*-
2 # vim: filetype=python
4 ##
5 # == Block device exports
6 ##
8 { 'include': 'sockets.json' }
11 # @NbdServerOptions:
13 # Keep this type consistent with the nbd-server-start arguments. The only
14 # intended difference is using SocketAddress instead of SocketAddressLegacy.
16 # @addr: Address on which to listen.
17 # @tls-creds: ID of the TLS credentials object (since 2.6).
18 # @tls-authz: ID of the QAuthZ authorization object used to validate
19 #             the client's x509 distinguished name. This object is
20 #             is only resolved at time of use, so can be deleted and
21 #             recreated on the fly while the NBD server is active.
22 #             If missing, it will default to denying access (since 4.0).
23 # @max-connections: The maximum number of connections to allow at the same
24 #                   time, 0 for unlimited. (since 5.2; default: 0)
26 # Since: 4.2
28 { 'struct': 'NbdServerOptions',
29   'data': { 'addr': 'SocketAddress',
30             '*tls-creds': 'str',
31             '*tls-authz': 'str',
32             '*max-connections': 'uint32' } }
35 # @nbd-server-start:
37 # Start an NBD server listening on the given host and port.  Block
38 # devices can then be exported using @nbd-server-add.  The NBD
39 # server will present them as named exports; for example, another
40 # QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
42 # Keep this type consistent with the NbdServerOptions type. The only intended
43 # difference is using SocketAddressLegacy instead of SocketAddress.
45 # @addr: Address on which to listen.
46 # @tls-creds: ID of the TLS credentials object (since 2.6).
47 # @tls-authz: ID of the QAuthZ authorization object used to validate
48 #             the client's x509 distinguished name. This object is
49 #             is only resolved at time of use, so can be deleted and
50 #             recreated on the fly while the NBD server is active.
51 #             If missing, it will default to denying access (since 4.0).
52 # @max-connections: The maximum number of connections to allow at the same
53 #                   time, 0 for unlimited. (since 5.2; default: 0)
55 # Returns: error if the server is already running.
57 # Since: 1.3
59 { 'command': 'nbd-server-start',
60   'data': { 'addr': 'SocketAddressLegacy',
61             '*tls-creds': 'str',
62             '*tls-authz': 'str',
63             '*max-connections': 'uint32' } }
66 # @BlockExportOptionsNbdBase:
68 # An NBD block export (common options shared between nbd-server-add and
69 # the NBD branch of block-export-add).
71 # @name: Export name. If unspecified, the @device parameter is used as the
72 #        export name. (Since 2.12)
74 # @description: Free-form description of the export, up to 4096 bytes.
75 #               (Since 5.0)
77 # Since: 5.0
79 { 'struct': 'BlockExportOptionsNbdBase',
80   'data': { '*name': 'str', '*description': 'str' } }
83 # @BlockExportOptionsNbd:
85 # An NBD block export (distinct options used in the NBD branch of
86 # block-export-add).
88 # @bitmaps: Also export each of the named dirty bitmaps reachable from
89 #           @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
90 #           the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
91 #           each bitmap.
93 # @allocation-depth: Also export the allocation depth map for @device, so
94 #                    the NBD client can use NBD_OPT_SET_META_CONTEXT with
95 #                    the metadata context name "qemu:allocation-depth" to
96 #                    inspect allocation details. (since 5.2)
98 # Since: 5.2
100 { 'struct': 'BlockExportOptionsNbd',
101   'base': 'BlockExportOptionsNbdBase',
102   'data': { '*bitmaps': ['str'], '*allocation-depth': 'bool' } }
105 # @BlockExportOptionsVhostUserBlk:
107 # A vhost-user-blk block export.
109 # @addr: The vhost-user socket on which to listen. Both 'unix' and 'fd'
110 #        SocketAddress types are supported. Passed fds must be UNIX domain
111 #        sockets.
112 # @logical-block-size: Logical block size in bytes. Defaults to 512 bytes.
113 # @num-queues: Number of request virtqueues. Must be greater than 0. Defaults
114 #              to 1.
116 # Since: 5.2
118 { 'struct': 'BlockExportOptionsVhostUserBlk',
119   'data': { 'addr': 'SocketAddress',
120             '*logical-block-size': 'size',
121             '*num-queues': 'uint16'} }
124 # @FuseExportAllowOther:
126 # Possible allow_other modes for FUSE exports.
128 # @off: Do not pass allow_other as a mount option.
130 # @on: Pass allow_other as a mount option.
132 # @auto: Try mounting with allow_other first, and if that fails, retry
133 #        without allow_other.
135 # Since: 6.1
137 { 'enum': 'FuseExportAllowOther',
138   'data': ['off', 'on', 'auto'] }
141 # @BlockExportOptionsFuse:
143 # Options for exporting a block graph node on some (file) mountpoint
144 # as a raw image.
146 # @mountpoint: Path on which to export the block device via FUSE.
147 #              This must point to an existing regular file.
149 # @growable: Whether writes beyond the EOF should grow the block node
150 #            accordingly. (default: false)
152 # @allow-other: If this is off, only qemu's user is allowed access to
153 #               this export.  That cannot be changed even with chmod or
154 #               chown.
155 #               Enabling this option will allow other users access to
156 #               the export with the FUSE mount option "allow_other".
157 #               Note that using allow_other as a non-root user requires
158 #               user_allow_other to be enabled in the global fuse.conf
159 #               configuration file.
160 #               In auto mode (the default), the FUSE export driver will
161 #               first attempt to mount the export with allow_other, and
162 #               if that fails, try again without.
163 #               (since 6.1; default: auto)
165 # Since: 6.0
167 { 'struct': 'BlockExportOptionsFuse',
168   'data': { 'mountpoint': 'str',
169             '*growable': 'bool',
170             '*allow-other': 'FuseExportAllowOther' },
171   'if': 'defined(CONFIG_FUSE)' }
174 # @NbdServerAddOptions:
176 # An NBD block export, per legacy nbd-server-add command.
178 # @device: The device name or node name of the node to be exported
180 # @writable: Whether clients should be able to write to the device via the
181 #            NBD connection (default false).
183 # @bitmap: Also export a single dirty bitmap reachable from @device, so the
184 #          NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
185 #          context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
186 #          (since 4.0).
188 # Since: 5.0
190 { 'struct': 'NbdServerAddOptions',
191   'base': 'BlockExportOptionsNbdBase',
192   'data': { 'device': 'str',
193             '*writable': 'bool', '*bitmap': 'str' } }
196 # @nbd-server-add:
198 # Export a block node to QEMU's embedded NBD server.
200 # The export name will be used as the id for the resulting block export.
202 # Features:
203 # @deprecated: This command is deprecated. Use @block-export-add instead.
205 # Returns: error if the server is not running, or export with the same name
206 #          already exists.
208 # Since: 1.3
210 { 'command': 'nbd-server-add',
211   'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'] }
214 # @BlockExportRemoveMode:
216 # Mode for removing a block export.
218 # @safe: Remove export if there are no existing connections, fail otherwise.
220 # @hard: Drop all connections immediately and remove export.
222 # Potential additional modes to be added in the future:
224 # hide: Just hide export from new clients, leave existing connections as is.
225 # Remove export after all clients are disconnected.
227 # soft: Hide export from new clients, answer with ESHUTDOWN for all further
228 # requests from existing clients.
230 # Since: 2.12
232 {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']}
235 # @nbd-server-remove:
237 # Remove NBD export by name.
239 # @name: Block export id.
241 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
242 #        Default is 'safe'.
244 # Features:
245 # @deprecated: This command is deprecated. Use @block-export-del instead.
247 # Returns: error if
248 #            - the server is not running
249 #            - export is not found
250 #            - mode is 'safe' and there are existing connections
252 # Since: 2.12
254 { 'command': 'nbd-server-remove',
255   'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'},
256   'features': ['deprecated'] }
259 # @nbd-server-stop:
261 # Stop QEMU's embedded NBD server, and unregister all devices previously
262 # added via @nbd-server-add.
264 # Since: 1.3
266 { 'command': 'nbd-server-stop' }
269 # @BlockExportType:
271 # An enumeration of block export types
273 # @nbd: NBD export
274 # @vhost-user-blk: vhost-user-blk export (since 5.2)
275 # @fuse: FUSE export (since: 6.0)
277 # Since: 4.2
279 { 'enum': 'BlockExportType',
280   'data': [ 'nbd', 'vhost-user-blk',
281             { 'name': 'fuse', 'if': 'defined(CONFIG_FUSE)' } ] }
284 # @BlockExportOptions:
286 # Describes a block export, i.e. how single node should be exported on an
287 # external interface.
289 # @id: A unique identifier for the block export (across all export types)
291 # @node-name: The node name of the block node to be exported (since: 5.2)
293 # @writable: True if clients should be able to write to the export
294 #            (default false)
296 # @writethrough: If true, caches are flushed after every write request to the
297 #                export before completion is signalled. (since: 5.2;
298 #                default: false)
300 # @iothread: The name of the iothread object where the export will run. The
301 #            default is to use the thread currently associated with the
302 #            block node. (since: 5.2)
304 # @fixed-iothread: True prevents the block node from being moved to another
305 #                  thread while the export is active. If true and @iothread is
306 #                  given, export creation fails if the block node cannot be
307 #                  moved to the iothread. The default is false. (since: 5.2)
309 # Since: 4.2
311 { 'union': 'BlockExportOptions',
312   'base': { 'type': 'BlockExportType',
313             'id': 'str',
314             '*fixed-iothread': 'bool',
315             '*iothread': 'str',
316             'node-name': 'str',
317             '*writable': 'bool',
318             '*writethrough': 'bool' },
319   'discriminator': 'type',
320   'data': {
321       'nbd': 'BlockExportOptionsNbd',
322       'vhost-user-blk': 'BlockExportOptionsVhostUserBlk',
323       'fuse': { 'type': 'BlockExportOptionsFuse',
324                 'if': 'defined(CONFIG_FUSE)' }
325    } }
328 # @block-export-add:
330 # Creates a new block export.
332 # Since: 5.2
334 { 'command': 'block-export-add',
335   'data': 'BlockExportOptions', 'boxed': true }
338 # @block-export-del:
340 # Request to remove a block export. This drops the user's reference to the
341 # export, but the export may still stay around after this command returns until
342 # the shutdown of the export has completed.
344 # @id: Block export id.
346 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
347 #        Default is 'safe'.
349 # Returns: Error if the export is not found or @mode is 'safe' and the export
350 #          is still in use (e.g. by existing client connections)
352 # Since: 5.2
354 { 'command': 'block-export-del',
355   'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } }
358 # @BLOCK_EXPORT_DELETED:
360 # Emitted when a block export is removed and its id can be reused.
362 # @id: Block export id.
364 # Since: 5.2
366 { 'event': 'BLOCK_EXPORT_DELETED',
367   'data': { 'id': 'str' } }
370 # @BlockExportInfo:
372 # Information about a single block export.
374 # @id: The unique identifier for the block export
376 # @type: The block export type
378 # @node-name: The node name of the block node that is exported
380 # @shutting-down: True if the export is shutting down (e.g. after a
381 #                 block-export-del command, but before the shutdown has
382 #                 completed)
384 # Since:  5.2
386 { 'struct': 'BlockExportInfo',
387   'data': { 'id': 'str',
388             'type': 'BlockExportType',
389             'node-name': 'str',
390             'shutting-down': 'bool' } }
393 # @query-block-exports:
395 # Returns: A list of BlockExportInfo describing all block exports
397 # Since: 5.2
399 { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] }