block: add blockdev-attach QMP command
PATCH 1/1 block: add blockdev-attach QMP command
Add a blockdev-attach QMP command that attaches a block driver state tree to a device's block backend. Unlike blockdev-insert-medium, this works for non-removable devices such as NVMe namespaces.
After drive_del removes a device's backing store, the BlockBackend remains attached to the guest device but has no BlockDriverState. blockdev-attach reconnects a block node (previously created with blockdev-add) to the device's BlockBackend via blk_insert_bs().
This separates the two concerns as recommended: blockdev-add creates the block node, blockdev-attach associates it with the device.
Example usage with NVMe namespace hot-swap:
drive_del drv0
blockdev-add node-name=node0 driver=qcow2 file.driver=file \
file.filename=disk.qcow2
blockdev-attach id=ns0 node-name=node0
An HMP wrapper is included for convenience.
--- block/monitor/block-hmp-cmds.c | 10 ++++++++++ block/qapi-system.c | 36 ++++++++++++++++++++++++++++++++++ hmp-commands.hx | 16 +++++++++++++++ include/block/block-hmp-cmds.h | 1 + qapi/block.json | 33 +++++++++++++++++++++++++++++++ 5 files changed, 96 insertions(+)
block/monitor/block-hmp-cmds.c +10 -0
@@ -195,6 +195,16 @@ unlock:hmp_handle_error (mon, err); } +void hmp_blockdev_attach (Monitor *mon,const QDict *qdict) +{ +const char *id =qdict_get_str (qdict,"id" ); +const char *node_name =qdict_get_str (qdict,"node-name" ); +Error *err =NULL ; + +qmp_blockdev_attach (id, node_name, &err); +hmp_handle_error (mon, err); +} +void hmp_commit (Monitor *mon,const QDict *qdict) {const char *device =qdict_get_str (qdict,"device" );
block/qapi-system.c +36 -0
@@ -304,6 +304,42 @@ void qmp_blockdev_insert_medium(const char *id, const char *node_name,blockdev_insert_medium (NULL , id, node_name, errp); } +void qmp_blockdev_attach (const char *id,const char *node_name, +Error **errp) +{ +BlockBackend *blk; +BlockDriverState *bs; +int ret; + +GRAPH_RDLOCK_GUARD_MAINLOOP (); + + blk =qmp_get_blk (NULL , id, errp); +if (!blk) { +return ; + } + +if (blk_bs (blk)) { +error_setg (errp,"Device already has a medium inserted" ); +return ; + } + + bs =bdrv_find_node (node_name); +if (!bs) { +error_setg (errp,"Node '%s' not found" , node_name); +return ; + } + +if (bdrv_has_blk (bs)) { +error_setg (errp,"Node '%s' is already in use" , node_name); +return ; + } + + ret =blk_insert_bs (blk, bs, errp); +if (ret <0 ) { +return ; + } +} + void qmp_blockdev_change_medium(const char *device, const char *id, const char *filename,
hmp-commands.hx +16 -0
@@ -207,6 +207,22 @@ SRST actions (drive options rerror, werror). ERST + { + .name = "blockdev-attach", + .args_type = "id:s,node-name:s", + .params = "id node-name", + .help = "attach a block node to a device (non-removable)", + .cmd = hmp_blockdev_attach, + }, + +SRST +``blockdev-attach`` *id* *node-name* + Attach a block driver state tree (created with ``blockdev-add``) to a + device's block backend. Unlike ``blockdev-insert-medium``, this works + for non-removable devices such as NVMe namespaces. The device must + have no medium inserted (e.g. after ``drive_del``). +ERST + { .name = "change", .args_type = "device:B,force:-f,target:F,arg:s?,read-only-mode:s?",
include/block/block-hmp-cmds.h +1 -0
@@ -21,6 +21,7 @@ void hmp_drive_add(Monitor *mon, const QDict *qdict);void hmp_commit (Monitor *mon,const QDict *qdict);void hmp_drive_del (Monitor *mon,const QDict *qdict); +void hmp_blockdev_attach (Monitor *mon,const QDict *qdict);void hmp_drive_mirror (Monitor *mon,const QDict *qdict);void hmp_drive_backup (Monitor *mon,const QDict *qdict);
qapi/block.json +33 -0
@@ -295,6 +295,39 @@ 'data': { 'id': 'str', 'node-name': 'str'} } +## +# @blockdev-attach: +# +# Attach a block driver state tree to a device's block backend. +# Unlike blockdev-insert-medium, this works for non-removable +# devices such as NVMe namespaces. The device must currently have +# no medium inserted (e.g. after drive_del removed the backing). +# +# @id: The name or QOM path of the guest device +# +# @node-name: name of a node in the block driver state graph +# +# Since: 11.1 +# +# .. qmp-example:: +# +# -> { "execute": "blockdev-add", +# "arguments": { +# "node-name": "node0", +# "driver": "qcow2", +# "file": { "driver": "file", +# "filename": "disk.qcow2" } } } +# <- { "return": {} } +# +# -> { "execute": "blockdev-attach", +# "arguments": { "id": "ns0", +# "node-name": "node0" } } +# <- { "return": {} } +## +{ 'command': 'blockdev-attach', + 'data': { 'id': 'str', + 'node-name': 'str'} } + ## # @BlockdevChangeReadOnlyMode: #
Signature · 1 line
2.53.0
Quoted 9 lines · On Wed, Apr 15, 2026 at 07:39:05PM +0200, mr-083 wrote:
Add a blockdev-attach QMP command that attaches a block driver state tree to a device's block backend. Unlike blockdev-insert-medium, this works for non-removable devices such as NVMe namespaces.
After
drive_delremoves a device's backing store, the BlockBackend remains attached to the guest device but has no BlockDriverState. blockdev-attach reconnects a block node (previously created with blockdev-add) to the device's BlockBackend viablk_insert_bs().
Quoted 8 lines
This separates the two concerns as recommended: blockdev-add creates the block node, blockdev-attach associates it with the device.
Example usage with NVMe namespace hot-swap:
drive_deldrv0
blockdev-add node-name=node0 driver=qcow2 file.driver=file \
file.filename=disk.qcow2
blockdev-attach id=ns0 node-name=node0
Hi Matthieu,
I came across a quirk here:
$ qemu-system-x86_64 \
--blockdev file,filename=my-lun.img,node-name=drive1 \
--device nvme,serial=nvme0 \
--device nvme-ns,id=nvme-ns0,drive=drive1
(qemu) drive_del drive1
Error: drive drive1 is in useBut when I change --blockdev to --drive, it succeeds. I think this second scenario is the one that you have been testing.
I also tried the QMP blockdev-del command together with --blockdev, and it fails:
$ qemu-system-x86_64 ... \
-qmp unix:/tmp/qmp.sock,server=on,wait=off
$ qmp-shell /tmp/qmp.sock
(QEMU) blockdev-del node-name=drive1
{"error": {"class": "GenericError", "desc": "Node drive1 is in use"}}It seems logical that a disk image that's in use by NVMe emulation cannot be removed. So now I'm wondering if there is a bug or a historical reason why drive_del allows drives to the removed at runtime even when media change is not supported.
CCing Kevin Wolf and Markus Amrbruster as they may know the answer.
Depending on the answer this may influence the test workflow in this patch. It's unclear to me what is being tested here since this does not simulate a real error that a physical NVMe drive could raise?
I think the intention is to fail I/O so a test can simulate a period where the drive is down. QEMU has the blkdebug driver which could be inserted into the block graph to fail I/O requests - maybe that is appropriate for your test and may not require new monitor commands (see blkdebug examples in tests/)?
Stefan
Quoted 166 lines
An HMP wrapper is included for convenience.
Signed-off-by Matthieu <[email protected]>--- block/monitor/block-hmp-cmds.c | 10 ++++++++++ block/qapi-system.c | 36 ++++++++++++++++++++++++++++++++++ hmp-commands.hx | 16 +++++++++++++++ include/block/block-hmp-cmds.h | 1 + qapi/block.json | 33 +++++++++++++++++++++++++++++++ 5 files changed, 96 insertions(+)block/monitor/block-hmp-cmds.c +10
-0@@ -195,6 +195,16 @@ unlock:hmp_handle_error (mon, err); } +void hmp_blockdev_attach (Monitor *mon,const QDict *qdict) +{ +const char *id =qdict_get_str (qdict,"id" ); +const char *node_name =qdict_get_str (qdict,"node-name" ); +Error *err =NULL ; + +qmp_blockdev_attach (id, node_name, &err); +hmp_handle_error (mon, err); +} +void hmp_commit (Monitor *mon,const QDict *qdict) {const char *device =qdict_get_str (qdict,"device" );block/qapi-system.c +36
-0@@ -304,6 +304,42 @@ void qmp_blockdev_insert_medium(const char *id, const char *node_name,blockdev_insert_medium (NULL , id, node_name, errp); } +void qmp_blockdev_attach (const char *id,const char *node_name, +Error **errp) +{ +BlockBackend *blk; +BlockDriverState *bs; +int ret; + +GRAPH_RDLOCK_GUARD_MAINLOOP (); + + blk =qmp_get_blk (NULL , id, errp); +if (!blk) { +return ; + } + +if (blk_bs (blk)) { +error_setg (errp,"Device already has a medium inserted" ); +return ; + } + + bs =bdrv_find_node (node_name); +if (!bs) { +error_setg (errp,"Node '%s' not found" , node_name); +return ; + } + +if (bdrv_has_blk (bs)) { +error_setg (errp,"Node '%s' is already in use" , node_name); +return ; + } + + ret =blk_insert_bs (blk, bs, errp); +if (ret <0 ) { +return ; + } +} + void qmp_blockdev_change_medium(const char *device, const char *id, const char *filename,hmp-commands.hx +16
-0@@ -207,6 +207,22 @@ SRST actions (drive options rerror, werror). ERST + { + .name = "blockdev-attach", + .args_type = "id:s,node-name:s", + .params = "id node-name", + .help = "attach a block node to a device (non-removable)", + .cmd = hmp_blockdev_attach, + }, + +SRST +``blockdev-attach`` *id* *node-name* + Attach a block driver state tree (created with ``blockdev-add``) to a + device's block backend. Unlike ``blockdev-insert-medium``, this works + for non-removable devices such as NVMe namespaces. The device must + have no medium inserted (e.g. after ``drive_del``). +ERST + { .name = "change", .args_type = "device:B,force:-f,target:F,arg:s?,read-only-mode:s?",include/block/block-hmp-cmds.h +1
-0@@ -21,6 +21,7 @@ void hmp_drive_add(Monitor *mon, const QDict *qdict);void hmp_commit (Monitor *mon,const QDict *qdict);void hmp_drive_del (Monitor *mon,const QDict *qdict); +void hmp_blockdev_attach (Monitor *mon,const QDict *qdict);void hmp_drive_mirror (Monitor *mon,const QDict *qdict);void hmp_drive_backup (Monitor *mon,const QDict *qdict);qapi/block.json +33
-0@@ -295,6 +295,39 @@ 'data': { 'id': 'str', 'node-name': 'str'} } +## +# @blockdev-attach: +# +# Attach a block driver state tree to a device's block backend. +# Unlike blockdev-insert-medium, this works for non-removable +# devices such as NVMe namespaces. The device must currently have +# no medium inserted (e.g. after drive_del removed the backing). +# +# @id: The name or QOM path of the guest device +# +# @node-name: name of a node in the block driver state graph +# +# Since: 11.1 +# +# .. qmp-example:: +# +# -> { "execute": "blockdev-add", +# "arguments": { +# "node-name": "node0", +# "driver": "qcow2", +# "file": { "driver": "file", +# "filename": "disk.qcow2" } } } +# <- { "return": {} } +# +# -> { "execute": "blockdev-attach", +# "arguments": { "id": "ns0", +# "node-name": "node0" } } +# <- { "return": {} } +## +{ 'command': 'blockdev-attach', + 'data': { 'id': 'str', + 'node-name': 'str'} } + ## # @BlockdevChangeReadOnlyMode: #Signature · 1 line
2.53.0
Quoted 22 lines · Stefan Hajnoczi
Quoted 9 lines · On Wed, Apr 15, 2026 at 07:39:05PM +0200, mr-083 wrote:
Add a blockdev-attach QMP command that attaches a block driver state tree to a device's block backend. Unlike blockdev-insert-medium, this works for non-removable devices such as NVMe namespaces.
After
drive_delremoves a device's backing store, the BlockBackend remains attached to the guest device but has no BlockDriverState. blockdev-attach reconnects a block node (previously created with blockdev-add) to the device's BlockBackend viablk_insert_bs().Quoted 8 lines
This separates the two concerns as recommended: blockdev-add creates the block node, blockdev-attach associates it with the device.
Example usage with NVMe namespace hot-swap:
drive_deldrv0
blockdev-add node-name=node0 driver=qcow2 file.driver=file \
file.filename=disk.qcow2
blockdev-attach id=ns0 node-name=node0Hi Matthieu,
I came across a quirk here:
Quoted 6 lines
$ qemu-system-x86_64 \
--blockdev file,filename=my-lun.img,node-name=drive1 \
--device nvme,serial=nvme0 \
--device nvme-ns,id=nvme-ns0,drive=drive1
(qemu) drive_del drive1
Error: drive drive1 is in useI see "Error: Node drive1 is in use".
It's from qmp_blockdev_del():
bs = bdrv_find_node(node_name);
if (!bs) {
error_setg(errp, "Failed to find node with node-name='%s'", node_name);
return;
}
if (bdrv_has_blk(bs)) {
error_setg(errp, "Node %s is in use", node_name);
return;
}Called from hmp_drive_del():
bs = bdrv_find_node(id);
if (bs) {
qmp_blockdev_del(id, &err);
goto unlock;
}Quoted 2 lines
But when I change --blockdev to --drive, it succeeds. I think this second scenario is the one that you have been testing.
I *guess* you changed it to something like
-drive if=none,file=test.img,id=drive1
hmp_drive_del()'s call of bdrv_find_node() then fails, and we take a completely different path, which succeeds:
(qemu) info block
drive1 (#block195): test.img (raw)
Attached to: nvme-ns0
Cache mode: writeback
(qemu) drive_del drive1
(qemu) info block
nvme-ns0: [not inserted]
Attached to: nvme-ns0
This rips nvme-ns0's drive right off. Feels *unsafe*: the frontend (here: nvme-ns) may reasonably assume that a non-removable medium stays put, use it without checking it's still there, and crash.
Quoted 9 lines
I also tried the QMP blockdev-del command together with --blockdev, and it fails:
$ qemu-system-x86_64 ... \ -qmp unix:/tmp/qmp.sock,server=on,wait=off $ qmp-shell /tmp/qmp.sock (QEMU) blockdev-del node-name=drive1 {"error": {"class": "GenericError", "desc": "Node drive1 is in use"}}
Quoted 6 lines
It seems logical that a disk image that's in use by NVMe emulation cannot be removed. So now I'm wondering if there is a bug or a historical reason why
drive_delallows drives to the removed at runtime even when media change is not supported.CCing Kevin Wolf and Markus Amrbruster as they may know the answer.
I suspect this is simply a bug, and likely a regression. Can you find out?
Quoted 16 lines
Depending on the answer this may influence the test workflow in this patch. It's unclear to me what is being tested here since this does not simulate a real error that a physical NVMe drive could raise?
I think the intention is to fail I/O so a test can simulate a period where the drive is down. QEMU has the blkdebug driver which could be inserted into the block graph to fail I/O requests - maybe that is appropriate for your test and may not require new monitor commands (see blkdebug examples in tests/)?
Stefan
Quoted 4 lines
An HMP wrapper is included for convenience.
Signed-off-by Matthieu <[email protected]>
Quoted 53 lines · Markus Armbruster
Quoted 22 lines · Stefan Hajnoczi
Quoted 9 lines · On Wed, Apr 15, 2026 at 07:39:05PM +0200, mr-083 wrote:
Add a blockdev-attach QMP command that attaches a block driver state tree to a device's block backend. Unlike blockdev-insert-medium, this works for non-removable devices such as NVMe namespaces.
After
drive_delremoves a device's backing store, the BlockBackend remains attached to the guest device but has no BlockDriverState. blockdev-attach reconnects a block node (previously created with blockdev-add) to the device's BlockBackend viablk_insert_bs().Quoted 8 lines
This separates the two concerns as recommended: blockdev-add creates the block node, blockdev-attach associates it with the device.
Example usage with NVMe namespace hot-swap:
drive_deldrv0
blockdev-add node-name=node0 driver=qcow2 file.driver=file \
file.filename=disk.qcow2
blockdev-attach id=ns0 node-name=node0Hi Matthieu,
I came across a quirk here:Quoted 6 lines
$ qemu-system-x86_64 \ --blockdev file,filename=my-lun.img,node-name=drive1 \ --device nvme,serial=nvme0 \ --device nvme-ns,id=nvme-ns0,drive=drive1 (qemu) drive_del drive1 Error: drive drive1 is in useI see "Error: Node drive1 is in use".
It's from
qmp_blockdev_del():bs = bdrv_find_node(node_name); if (!bs) { error_setg(errp, "Failed to find node with node-name='%s'", node_name); return; } if (bdrv_has_blk(bs)) { error_setg(errp, "Node %s is in use", node_name); return; }Called from
hmp_drive_del():bs = bdrv_find_node(id); if (bs) { qmp_blockdev_del(id, &err); goto unlock; }
Quoted 6 lines
Quoted 2 lines
But when I change --blockdev to --drive, it succeeds. I think this second scenario is the one that you have been testing.
I *guess* you changed it to something like
-drive if=none,file=test.img,id=drive1
Yes.
Quoted 13 lines
hmp_drive_del()'s call of
bdrv_find_node()then fails, and we take a completely different path, which succeeds:(qemu) info block
drive1 (#block195): test.img (raw)
Attached to: nvme-ns0
Cache mode: writeback
(qemu)drive_deldrive1
(qemu) info block
nvme-ns0: [not inserted]
Attached to: nvme-ns0
Quoted 3 lines
This rips nvme-ns0's drive right off. Feels *unsafe*: the frontend (here: nvme-ns) may reasonably assume that a non-removable medium stays put, use it without checking it's still there, and crash.
I/O requests fail with -ENOMEDIUM when blk->root.bs is NULL but it's still a bit concerning that the medium can be removed without the device emulation being aware.
Quoted 15 lines
Quoted 15 lines
I also tried the QMP blockdev-del command together with --blockdev, and it fails:
$ qemu-system-x86_64 ... \ -qmp unix:/tmp/qmp.sock,server=on,wait=off $ qmp-shell /tmp/qmp.sock (QEMU) blockdev-del node-name=drive1 {"error": {"class": "GenericError", "desc": "Node drive1 is in use"}}It seems logical that a disk image that's in use by NVMe emulation cannot be removed. So now I'm wondering if there is a bug or a historical reason why
drive_delallows drives to the removed at runtime even when media change is not supported.
Quoted 4 lines
Quoted 1 line
CCing Kevin Wolf and Markus Amrbruster as they may know the answer.
I suspect this is simply a bug, and likely a regression. Can you find out?
Okay. I thought maybe there is some backwards compatibility reason that requires -drive if=none to behave like this.
It's a long-standing bug:
v3.0.0 Affected v4.0.0 Affected v6.0.0 Affected v8.0.0 Affected master Affected
I didn't go back beyond v3.0.0 because Python 2 is required to build really old versions of QEMU.
Stefan
Quoted 18 lines
Quoted 17 lines
Depending on the answer this may influence the test workflow in this patch. It's unclear to me what is being tested here since this does not simulate a real error that a physical NVMe drive could raise?
I think the intention is to fail I/O so a test can simulate a period where the drive is down. QEMU has the blkdebug driver which could be inserted into the block graph to fail I/O requests - maybe that is appropriate for your test and may not require new monitor commands (see blkdebug examples in tests/)?
Stefan
Quoted 4 lines
An HMP wrapper is included for convenience.
Signed-off-by Matthieu <[email protected]>
Am 15.04.2026 um 19:39 hat mr-083 geschrieben:
Quoted 9 lines
Add a blockdev-attach QMP command that attaches a block driver state tree to a device's block backend. Unlike blockdev-insert-medium, this works for non-removable devices such as NVMe namespaces.
After
drive_delremoves a device's backing store, the BlockBackend remains attached to the guest device but has no BlockDriverState. blockdev-attach reconnects a block node (previously created with blockdev-add) to the device's BlockBackend viablk_insert_bs().
Quoted 8 lines
This separates the two concerns as recommended: blockdev-add creates the block node, blockdev-attach associates it with the device.
Example usage with NVMe namespace hot-swap:
drive_deldrv0
blockdev-add node-name=node0 driver=qcow2 file.driver=file \
file.filename=disk.qcow2
blockdev-attach id=ns0 node-name=node0
Is the intended functionality the same as the following?
blockdev-add node-name=node0 driver=qcow2 file.driver=file \
file.filename=disk.qcow2
qom-set path=ns0 property=drive value=node0
drive-del drv0 / blockdev-del node-name=old-nodeThis seems cleaner because there is no window where the namespace isn't backed by any block node.
If this does what you want, it's unclear to me if we want a separate QMP command to do the same in a maybe more discoverable way. Markus, do we have precedence for this?
Quoted 1 line
An HMP wrapper is included for convenience.
An HMP convenience command mapping to qom-set should still be possible either way.
Kevin