ShuriZma
/
xemu
mirror of https://github.com/xemu-project/xemu.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

* Documentation updates 

-----BEGIN PGP SIGNATURE-----
 
 iQJFBAABCAAvFiEEJ7iIR+7gJQEY8+q5LtnXdP5wLbUFAmGbo7MRHHRodXRoQHJl
 ZGhhdC5jb20ACgkQLtnXdP5wLbUG5g/+NgstvV5IpqIPfs5BRfFZfFwrteo7/m7B
 KTOpicaWzWUB5f0xAiTg4h1dozDJaE4JItY03mwu+Vb+RQdeq0RUsilnPiGvUuo4
 FK+Ty9lfIH1XPDIG1trTFiO8mzXp6kklFX7/bFuW6lc+xxOFo00VQmlM1lEqmPOf
 PdILl6SdknIP+HbgYkH3Asg2ST+rx2OZJBtC9tqe/oFf7y4XlW9T6/nSgDVpH37q
 W9zaYOYVDrZfp7o31pc+1c4MwglBR4a8Wy/P5wEyAGI6W6qKlXOFqeVkqLw/8ftK
 wdpGeFYv9RlgnbT6zu/fShnUnDLzYNWxTH2fbaTdT0EaLjwh4mR+n5YlryM1gb+I
 LweaFZFkpkC/Kv2A3ka++pZLohwjyyDeII3vRKnvGDuX9ynCNdck86+kWstuc9LI
 v8jrh33CaFImIgrKoRh3K4hGGqhoK1By9bsvmoG7Kaalp6WCDGx2P6EDVBh6x6Sk
 fwXoW/B7KZW+W4bTmLqxQ3sP/qR7Vyhbg7gs91TRCRhv0044INBmnmEujTOw3cTP
 PFSHs0W90fKbOyER3KfDGQEPBR/TlxLOhtBVH8KhIy+K0aLyTAX9TMYg8+2Hwvzk
 VLXEkG1ZfAwKDDn4DOxBW08azbbtAga0DsnGn87VJ62ongtf/EOL61yoNUKY5emC
 Drpiym+4bBM=
 =BBr1
 -----END PGP SIGNATURE-----

Merge tag 'pull-request-2021-11-22' of https://gitlab.com/thuth/qemu into staging

* Documentation updates

# gpg: Signature made Mon 22 Nov 2021 03:05:39 PM CET
# gpg:                using RSA key 27B88847EEE0250118F3EAB92ED9D774FE702DB5
# gpg:                issuer "thuth@redhat.com"
# gpg: Good signature from "Thomas Huth <th.huth@gmx.de>" [full]
# gpg:                 aka "Thomas Huth <thuth@redhat.com>" [full]
# gpg:                 aka "Thomas Huth <th.huth@posteo.de>" [unknown]
# gpg:                 aka "Thomas Huth <huth@tuxfamily.org>" [full]

* tag 'pull-request-2021-11-22' of https://gitlab.com/thuth/qemu:
  docs: Render binary names as monospaced text
  docs: Use double quotes instead of single quotes for COLO
  docs: Drop deprecated 'props' from object-add
  Fix some typos in documentation (found by codespell)
  docs: List more commit-message tags in "submitting-a-patch"
  docs: Fix botched rST conversion of 'submitting-a-patch.rst'

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
This commit is contained in:
Richard Henderson 2021-11-22 23:21:28 +01:00
parent d8a6311dab c5ba621954
commit 3c87012e38
30 changed files with 307 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/COLO-FT.txt
View File

@ -209,9 +209,9 @@ children.0=childs0 \
3. On Secondary VM's QEMU monitor, issue command 3. On Secondary VM's QEMU monitor, issue command
{'execute':'qmp_capabilities'} {"execute":"qmp_capabilities"}
{'execute': 'nbd-server-start', 'arguments': {'addr': {'type': 'inet', 'data': {'host': '0.0.0.0', 'port': '9999'} } } } {"execute": "nbd-server-start", "arguments": {"addr": {"type": "inet", "data": {"host": "0.0.0.0", "port": "9999"} } } }
{'execute': 'nbd-server-add', 'arguments': {'device': 'parent0', 'writable': true } } {"execute": "nbd-server-add", "arguments": {"device": "parent0", "writable": true } }
Note: Note:
a. The qmp command nbd-server-start and nbd-server-add must be run a. The qmp command nbd-server-start and nbd-server-add must be run
@ -222,11 +222,11 @@ Note:
will be merged into the parent disk on failover. will be merged into the parent disk on failover.
4. On Primary VM's QEMU monitor, issue command: 4. On Primary VM's QEMU monitor, issue command:
{'execute':'qmp_capabilities'} {"execute":"qmp_capabilities"}
{'execute': 'human-monitor-command', 'arguments': {'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0'}} {"execute": "human-monitor-command", "arguments": {"command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0"}}
{'execute': 'x-blockdev-change', 'arguments':{'parent': 'colo-disk0', 'node': 'replication0' } } {"execute": "x-blockdev-change", "arguments":{"parent": "colo-disk0", "node": "replication0" } }
{'execute': 'migrate-set-capabilities', 'arguments': {'capabilities': [ {'capability': 'x-colo', 'state': true } ] } } {"execute": "migrate-set-capabilities", "arguments": {"capabilities": [ {"capability": "x-colo", "state": true } ] } }
{'execute': 'migrate', 'arguments': {'uri': 'tcp:127.0.0.2:9998' } } {"execute": "migrate", "arguments": {"uri": "tcp:127.0.0.2:9998" } }
Note: Note:
a. There should be only one NBD Client for each primary disk. a. There should be only one NBD Client for each primary disk.
@ -249,59 +249,59 @@ if you want to resume the replication, follow "Secondary resume replication"
== Primary Failover == == Primary Failover ==
The Secondary died, resume on the Primary The Secondary died, resume on the Primary
{'execute': 'x-blockdev-change', 'arguments':{ 'parent': 'colo-disk0', 'child': 'children.1'} } {"execute": "x-blockdev-change", "arguments":{ "parent": "colo-disk0", "child": "children.1"} }
{'execute': 'human-monitor-command', 'arguments':{ 'command-line': 'drive_del replication0' } } {"execute": "human-monitor-command", "arguments":{ "command-line": "drive_del replication0" } }
{'execute': 'object-del', 'arguments':{ 'id': 'comp0' } } {"execute": "object-del", "arguments":{ "id": "comp0" } }
{'execute': 'object-del', 'arguments':{ 'id': 'iothread1' } } {"execute": "object-del", "arguments":{ "id": "iothread1" } }
{'execute': 'object-del', 'arguments':{ 'id': 'm0' } } {"execute": "object-del", "arguments":{ "id": "m0" } }
{'execute': 'object-del', 'arguments':{ 'id': 'redire0' } } {"execute": "object-del", "arguments":{ "id": "redire0" } }
{'execute': 'object-del', 'arguments':{ 'id': 'redire1' } } {"execute": "object-del", "arguments":{ "id": "redire1" } }
{'execute': 'x-colo-lost-heartbeat' } {"execute": "x-colo-lost-heartbeat" }
== Secondary Failover == == Secondary Failover ==
The Primary died, resume on the Secondary and prepare to become the new Primary The Primary died, resume on the Secondary and prepare to become the new Primary
{'execute': 'nbd-server-stop'} {"execute": "nbd-server-stop"}
{'execute': 'x-colo-lost-heartbeat'} {"execute": "x-colo-lost-heartbeat"}
{'execute': 'object-del', 'arguments':{ 'id': 'f2' } } {"execute": "object-del", "arguments":{ "id": "f2" } }
{'execute': 'object-del', 'arguments':{ 'id': 'f1' } } {"execute": "object-del", "arguments":{ "id": "f1" } }
{'execute': 'chardev-remove', 'arguments':{ 'id': 'red1' } } {"execute": "chardev-remove", "arguments":{ "id": "red1" } }
{'execute': 'chardev-remove', 'arguments':{ 'id': 'red0' } } {"execute": "chardev-remove", "arguments":{ "id": "red0" } }
{'execute': 'chardev-add', 'arguments':{ 'id': 'mirror0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '0.0.0.0', 'port': '9003' } }, 'server': true } } } } {"execute": "chardev-add", "arguments":{ "id": "mirror0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "0.0.0.0", "port": "9003" } }, "server": true } } } }
{'execute': 'chardev-add', 'arguments':{ 'id': 'compare1', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '0.0.0.0', 'port': '9004' } }, 'server': true } } } } {"execute": "chardev-add", "arguments":{ "id": "compare1", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "0.0.0.0", "port": "9004" } }, "server": true } } } }
{'execute': 'chardev-add', 'arguments':{ 'id': 'compare0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9001' } }, 'server': true } } } } {"execute": "chardev-add", "arguments":{ "id": "compare0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9001" } }, "server": true } } } }
{'execute': 'chardev-add', 'arguments':{ 'id': 'compare0-0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9001' } }, 'server': false } } } } {"execute": "chardev-add", "arguments":{ "id": "compare0-0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9001" } }, "server": false } } } }
{'execute': 'chardev-add', 'arguments':{ 'id': 'compare_out', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9005' } }, 'server': true } } } } {"execute": "chardev-add", "arguments":{ "id": "compare_out", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9005" } }, "server": true } } } }
{'execute': 'chardev-add', 'arguments':{ 'id': 'compare_out0', 'backend': {'type': 'socket', 'data': {'addr': { 'type': 'inet', 'data': { 'host': '127.0.0.1', 'port': '9005' } }, 'server': false } } } } {"execute": "chardev-add", "arguments":{ "id": "compare_out0", "backend": {"type": "socket", "data": {"addr": { "type": "inet", "data": { "host": "127.0.0.1", "port": "9005" } }, "server": false } } } }
== Primary resume replication == == Primary resume replication ==
Resume replication after new Secondary is up. Resume replication after new Secondary is up.
Start the new Secondary (Steps 2 and 3 above), then on the Primary: Start the new Secondary (Steps 2 and 3 above), then on the Primary:
{'execute': 'drive-mirror', 'arguments':{ 'device': 'colo-disk0', 'job-id': 'resync', 'target': 'nbd://127.0.0.2:9999/parent0', 'mode': 'existing', 'format': 'raw', 'sync': 'full'} } {"execute": "drive-mirror", "arguments":{ "device": "colo-disk0", "job-id": "resync", "target": "nbd://127.0.0.2:9999/parent0", "mode": "existing", "format": "raw", "sync": "full"} }
Wait until disk is synced, then: Wait until disk is synced, then:
{'execute': 'stop'} {"execute": "stop"}
{'execute': 'block-job-cancel', 'arguments':{ 'device': 'resync'} } {"execute": "block-job-cancel", "arguments":{ "device": "resync"} }
{'execute': 'human-monitor-command', 'arguments':{ 'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0'}} {"execute": "human-monitor-command", "arguments":{ "command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.2,file.port=9999,file.export=parent0,node-name=replication0"}}
{'execute': 'x-blockdev-change', 'arguments':{ 'parent': 'colo-disk0', 'node': 'replication0' } } {"execute": "x-blockdev-change", "arguments":{ "parent": "colo-disk0", "node": "replication0" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-mirror', 'id': 'm0', 'props': { 'netdev': 'hn0', 'queue': 'tx', 'outdev': 'mirror0' } } } {"execute": "object-add", "arguments":{ "qom-type": "filter-mirror", "id": "m0", "netdev": "hn0", "queue": "tx", "outdev": "mirror0" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire0', 'props': { 'netdev': 'hn0', 'queue': 'rx', 'indev': 'compare_out' } } } {"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire0", "netdev": "hn0", "queue": "rx", "indev": "compare_out" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire1', 'props': { 'netdev': 'hn0', 'queue': 'rx', 'outdev': 'compare0' } } } {"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire1", "netdev": "hn0", "queue": "rx", "outdev": "compare0" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'iothread', 'id': 'iothread1' } } {"execute": "object-add", "arguments":{ "qom-type": "iothread", "id": "iothread1" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'colo-compare', 'id': 'comp0', 'props': { 'primary_in': 'compare0-0', 'secondary_in': 'compare1', 'outdev': 'compare_out0', 'iothread': 'iothread1' } } } {"execute": "object-add", "arguments":{ "qom-type": "colo-compare", "id": "comp0", "primary_in": "compare0-0", "secondary_in": "compare1", "outdev": "compare_out0", "iothread": "iothread1" } }
{'execute': 'migrate-set-capabilities', 'arguments':{ 'capabilities': [ {'capability': 'x-colo', 'state': true } ] } } {"execute": "migrate-set-capabilities", "arguments":{ "capabilities": [ {"capability": "x-colo", "state": true } ] } }
{'execute': 'migrate', 'arguments':{ 'uri': 'tcp:127.0.0.2:9998' } } {"execute": "migrate", "arguments":{ "uri": "tcp:127.0.0.2:9998" } }
Note: Note:
If this Primary previously was a Secondary, then we need to insert the If this Primary previously was a Secondary, then we need to insert the
filters before the filter-rewriter by using the filters before the filter-rewriter by using the
"'insert': 'before', 'position': 'id=rew0'" Options. See below. ""insert": "before", "position": "id=rew0"" Options. See below.
== Secondary resume replication == == Secondary resume replication ==
Become Primary and resume replication after new Secondary is up. Note Become Primary and resume replication after new Secondary is up. Note
@ -309,23 +309,23 @@ that now 127.0.0.1 is the Secondary and 127.0.0.2 is the Primary.
Start the new Secondary (Steps 2 and 3 above, but with primary_ip=127.0.0.2), Start the new Secondary (Steps 2 and 3 above, but with primary_ip=127.0.0.2),
then on the old Secondary: then on the old Secondary:
{'execute': 'drive-mirror', 'arguments':{ 'device': 'colo-disk0', 'job-id': 'resync', 'target': 'nbd://127.0.0.1:9999/parent0', 'mode': 'existing', 'format': 'raw', 'sync': 'full'} } {"execute": "drive-mirror", "arguments":{ "device": "colo-disk0", "job-id": "resync", "target": "nbd://127.0.0.1:9999/parent0", "mode": "existing", "format": "raw", "sync": "full"} }
Wait until disk is synced, then: Wait until disk is synced, then:
{'execute': 'stop'} {"execute": "stop"}
{'execute': 'block-job-cancel', 'arguments':{ 'device': 'resync' } } {"execute": "block-job-cancel", "arguments":{ "device": "resync" } }
{'execute': 'human-monitor-command', 'arguments':{ 'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.1,file.port=9999,file.export=parent0,node-name=replication0'}} {"execute": "human-monitor-command", "arguments":{ "command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=127.0.0.1,file.port=9999,file.export=parent0,node-name=replication0"}}
{'execute': 'x-blockdev-change', 'arguments':{ 'parent': 'colo-disk0', 'node': 'replication0' } } {"execute": "x-blockdev-change", "arguments":{ "parent": "colo-disk0", "node": "replication0" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-mirror', 'id': 'm0', 'props': { 'insert': 'before', 'position': 'id=rew0', 'netdev': 'hn0', 'queue': 'tx', 'outdev': 'mirror0' } } } {"execute": "object-add", "arguments":{ "qom-type": "filter-mirror", "id": "m0", "insert": "before", "position": "id=rew0", "netdev": "hn0", "queue": "tx", "outdev": "mirror0" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire0', 'props': { 'insert': 'before', 'position': 'id=rew0', 'netdev': 'hn0', 'queue': 'rx', 'indev': 'compare_out' } } } {"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire0", "insert": "before", "position": "id=rew0", "netdev": "hn0", "queue": "rx", "indev": "compare_out" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'filter-redirector', 'id': 'redire1', 'props': { 'insert': 'before', 'position': 'id=rew0', 'netdev': 'hn0', 'queue': 'rx', 'outdev': 'compare0' } } } {"execute": "object-add", "arguments":{ "qom-type": "filter-redirector", "id": "redire1", "insert": "before", "position": "id=rew0", "netdev": "hn0", "queue": "rx", "outdev": "compare0" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'iothread', 'id': 'iothread1' } } {"execute": "object-add", "arguments":{ "qom-type": "iothread", "id": "iothread1" } }
{'execute': 'object-add', 'arguments':{ 'qom-type': 'colo-compare', 'id': 'comp0', 'props': { 'primary_in': 'compare0-0', 'secondary_in': 'compare1', 'outdev': 'compare_out0', 'iothread': 'iothread1' } } } {"execute": "object-add", "arguments":{ "qom-type": "colo-compare", "id": "comp0", "primary_in": "compare0-0", "secondary_in": "compare1", "outdev": "compare_out0", "iothread": "iothread1" } }
{'execute': 'migrate-set-capabilities', 'arguments':{ 'capabilities': [ {'capability': 'x-colo', 'state': true } ] } } {"execute": "migrate-set-capabilities", "arguments":{ "capabilities": [ {"capability": "x-colo", "state": true } ] } }
{'execute': 'migrate', 'arguments':{ 'uri': 'tcp:127.0.0.1:9998' } } {"execute": "migrate", "arguments":{ "uri": "tcp:127.0.0.1:9998" } }
== TODO == == TODO ==
1. Support shared storage. 1. Support shared storage.

8
docs/about/removed-features.rst
View File

@ -658,8 +658,8 @@ enforce that any failure to open the backing image (including if the
backing file is missing or an incorrect format was specified) is an backing file is missing or an incorrect format was specified) is an
error when ``-u`` is not used. error when ``-u`` is not used.
qemu-img amend to adjust backing file (removed in 6.1) ``qemu-img amend`` to adjust backing file (removed in 6.1)
'''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
The use of ``qemu-img amend`` to modify the name or format of a qcow2 The use of ``qemu-img amend`` to modify the name or format of a qcow2
backing image was never fully documented or tested, and interferes backing image was never fully documented or tested, and interferes
@ -670,8 +670,8 @@ backing chain should be performed with ``qemu-img rebase -u`` either
before or after the remaining changes being performed by amend, as before or after the remaining changes being performed by amend, as
appropriate. appropriate.
qemu-img backing file without format (removed in 6.1) ``qemu-img`` backing file without format (removed in 6.1)
''''''''''''''''''''''''''''''''''''''''''''''''''''' '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img
convert`` to create or modify an image that depends on a backing file convert`` to create or modify an image that depends on a backing file

52
docs/block-replication.txt
View File

@ -156,15 +156,15 @@ Primary:
children.0.driver=raw children.0.driver=raw
Run qmp command in primary qemu: Run qmp command in primary qemu:
{ 'execute': 'human-monitor-command', { "execute": "human-monitor-command",
'arguments': { "arguments": {
'command-line': 'drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=xxxx,file.port=xxxx,file.export=colo1,node-name=nbd_client1' "command-line": "drive_add -n buddy driver=replication,mode=primary,file.driver=nbd,file.host=xxxx,file.port=xxxx,file.export=colo1,node-name=nbd_client1"
} }
} }
{ 'execute': 'x-blockdev-change', { "execute": "x-blockdev-change",
'arguments': { "arguments": {
'parent': 'colo1', "parent": "colo1",
'node': 'nbd_client1' "node": "nbd_client1"
} }
} }
Note: Note:
@ -189,21 +189,21 @@ Secondary:
vote-threshold=1,children.0=childs1 vote-threshold=1,children.0=childs1
Then run qmp command in secondary qemu: Then run qmp command in secondary qemu:
{ 'execute': 'nbd-server-start', { "execute": "nbd-server-start",
'arguments': { "arguments": {
'addr': { "addr": {
'type': 'inet', "type": "inet",
'data': { "data": {
'host': 'xxx', "host": "xxx",
'port': 'xxx' "port": "xxx"
} }
} }
} }
} }
{ 'execute': 'nbd-server-add', { "execute": "nbd-server-add",
'arguments': { "arguments": {
'device': 'colo1', "device": "colo1",
'writable': true "writable": true
} }
} }
@ -223,22 +223,22 @@ After Failover:
Primary: Primary:
The secondary host is down, so we should run the following qmp command The secondary host is down, so we should run the following qmp command
to remove the nbd child from the quorum: to remove the nbd child from the quorum:
{ 'execute': 'x-blockdev-change', { "execute": "x-blockdev-change",
'arguments': { "arguments": {
'parent': 'colo1', "parent": "colo1",
'child': 'children.1' "child": "children.1"
} }
} }
{ 'execute': 'human-monitor-command', { "execute": "human-monitor-command",
'arguments': { "arguments": {
'command-line': 'drive_del xxxx' "command-line": "drive_del xxxx"
} }
} }
Note: there is no qmp command to remove the blockdev now Note: there is no qmp command to remove the blockdev now
Secondary: Secondary:
The primary host is down, so we should do the following thing: The primary host is down, so we should do the following thing:
{ 'execute': 'nbd-server-stop' } { "execute": "nbd-server-stop" }
Promote Secondary to Primary: Promote Secondary to Primary:
see COLO-FT.txt see COLO-FT.txt

6
docs/devel/build-system.rst
View File

@ -121,11 +121,11 @@ process for:
1) executables, which include: 1) executables, which include:
- Tools - qemu-img, qemu-nbd, qga (guest agent), etc - Tools - ``qemu-img``, ``qemu-nbd``, ``qga`` (guest agent), etc
- System emulators - qemu-system-$ARCH - System emulators - ``qemu-system-$ARCH``
- Userspace emulators - qemu-$ARCH - Userspace emulators - ``qemu-$ARCH``
- Unit tests - Unit tests

8
docs/devel/multi-process.rst
View File

@ -187,9 +187,9 @@ desired, in which the emulation application should only be allowed to
access the files or devices the VM it's running on behalf of can access. access the files or devices the VM it's running on behalf of can access.
#### qemu-io model #### qemu-io model
Qemu-io is a test harness used to test changes to the QEMU block backend ``qemu-io`` is a test harness used to test changes to the QEMU block backend
object code. (e.g., the code that implements disk images for disk driver object code (e.g., the code that implements disk images for disk driver
emulation) Qemu-io is not a device emulation application per se, but it emulation). ``qemu-io`` is not a device emulation application per se, but it
does compile the QEMU block objects into a separate binary from the main does compile the QEMU block objects into a separate binary from the main
QEMU one. This could be useful for disk device emulation, since its QEMU one. This could be useful for disk device emulation, since its
emulation applications will need to include the QEMU block objects. emulation applications will need to include the QEMU block objects.
@ -641,7 +641,7 @@ the CPU that issued the MMIO.
+==========+========================+ +==========+========================+
| rid | range MMIO is within | | rid | range MMIO is within |
+----------+------------------------+ +----------+------------------------+
| offset | offset withing *rid* | | offset | offset within *rid* |
+----------+------------------------+ +----------+------------------------+
| type | e.g., load or store | | type | e.g., load or store |
+----------+------------------------+ +----------+------------------------+

2
docs/devel/qgraph.rst
View File

@ -14,7 +14,7 @@ support that device.
Using only libqos APIs, the test has to manually take care of Using only libqos APIs, the test has to manually take care of
covering all the setups, and build the correct command line. covering all the setups, and build the correct command line.
This also introduces backward compability issues: if a device/driver command This also introduces backward compatibility issues: if a device/driver command
line name is changed, all tests that use that will not work line name is changed, all tests that use that will not work
properly anymore and need to be adjusted. properly anymore and need to be adjusted.

2
docs/devel/stable-process.rst
View File

@ -1,3 +1,5 @@
.. _stable-process:
QEMU and the stable process QEMU and the stable process
=========================== ===========================

2
docs/devel/style.rst
View File

@ -1,3 +1,5 @@
.. _coding-style:
================= =================
QEMU Coding Style QEMU Coding Style
================= =================

202
docs/devel/submitting-a-patch.rst
View File

@ -1,3 +1,5 @@
.. _submitting-a-patch:
Submitting a Patch Submitting a Patch
================== ==================
@ -20,11 +22,11 @@ one-shot fix, the bare minimum we ask is that:
should not be posted on the bug tracker, posted on forums, or should not be posted on the bug tracker, posted on forums, or
externally hosted and linked to. (We have other mailing lists too, externally hosted and linked to. (We have other mailing lists too,
but all patches must go to qemu-devel, possibly with a Cc: to another but all patches must go to qemu-devel, possibly with a Cc: to another
list.) ``git send-email`` works best for delivering the patch without list.) ``git send-email`` (`step-by-step setup
mangling it (`hints for setting it guide <https://git-send-email.io/>`__ and `hints and
up <http://lxr.free-electrons.com/source/Documentation/process/email-clients.rst>`__), tips <https://elixir.bootlin.com/linux/latest/source/Documentation/process/email-clients.rst>`__)
but attachments can be used as a last resort on a first-time works best for delivering the patch without mangling it, but
submission. attachments can be used as a last resort on a first-time submission.
- You must read replies to your message, and be willing to act on them. - You must read replies to your message, and be willing to act on them.
Note, however, that maintainers are often willing to manually fix up Note, however, that maintainers are often willing to manually fix up
first-time contributions, since there is a learning curve involved in first-time contributions, since there is a learning curve involved in
@ -45,6 +47,8 @@ Reading the table of contents below should already give you an idea of
the basic requirements. Use the table of contents as a reference, and the basic requirements. Use the table of contents as a reference, and
read the parts that you have doubts about. read the parts that you have doubts about.
.. contents:: Table of Contents
.. _writing_your_patches: .. _writing_your_patches:
Writing your Patches Writing your Patches
@ -60,11 +64,9 @@ check that you are in compliance with our coding standards. Be aware
that ``checkpatch.pl`` is not infallible, though, especially where C that ``checkpatch.pl`` is not infallible, though, especially where C
preprocessor macros are involved; use some common sense too. See also: preprocessor macros are involved; use some common sense too. See also:
- `QEMU Coding Style - :ref:`coding-style`
<https://qemu-project.gitlab.io/qemu/devel/style.html>`__
- `Automate a checkpatch run on - `Automate a checkpatch run on
commit <http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__ commit <https://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
.. _base_patches_against_current_git_master: .. _base_patches_against_current_git_master:
@ -76,6 +78,13 @@ of QEMU because development will have moved on from then and it probably
won't even apply to master. We only apply selected bugfixes to release won't even apply to master. We only apply selected bugfixes to release
branches and then only as backports once the code has gone into master. branches and then only as backports once the code has gone into master.
It is also okay to base patches on top of other on-going work that is
not yet part of the git master branch. To aid continuous integration
tools, such as `patchew <http://patchew.org/QEMU/>`__, you should `add a
tag <https://lists.gnu.org/archive/html/qemu-devel/2017-08/msg01288.html>`__
line ``Based-on: $MESSAGE_ID`` to your cover letter to make the series
dependency obvious.
.. _split_up_long_patches: .. _split_up_long_patches:
Split up long patches Split up long patches
@ -104,18 +113,17 @@ Make code motion patches easy to review
If a series requires large blocks of code motion, there are tricks for If a series requires large blocks of code motion, there are tricks for
making the refactoring easier to review. Split up the series so that making the refactoring easier to review. Split up the series so that
semantic changes (or even function renames) are done in a separate patch semantic changes (or even function renames) are done in a separate patch
from the raw code motion. Use a one-time setup of from the raw code motion. Use a one-time setup of ``git config
``git config diff.renames true; git config diff.algorithm patience`` diff.renames true;`` ``git config diff.algorithm patience`` (refer to
(Refer to `git-config <http://git-scm.com/docs/git-config>`__.) The `git-config <http://git-scm.com/docs/git-config>`__). The 'diff.renames'
``diff.renames`` property ensures file rename patches will be given in a property ensures file rename patches will be given in a more compact
more compact representation that focuses only on the differences across representation that focuses only on the differences across the file
the file rename, instead of showing the entire old file as a deletion rename, instead of showing the entire old file as a deletion and the new
and the new file as an insertion. Meanwhile, the 'diff.algorithm' file as an insertion. Meanwhile, the 'diff.algorithm' property ensures
property ensures that extracting a non-contiguous subset of one file that extracting a non-contiguous subset of one file into a new file, but
into a new file, but where all extracted parts occur in the same order where all extracted parts occur in the same order both before and after
both before and after the patch, will reduce churn in trying to treat the patch, will reduce churn in trying to treat unrelated ``}`` lines in
unrelated ``}`` lines in the original file as separating hunks of the original file as separating hunks of changes.
changes.
Ideally, a code motion patch can be reviewed by doing:: Ideally, a code motion patch can be reviewed by doing::
@ -138,8 +146,7 @@ as a separate patch which makes no semantic changes; don't put it in the
same patch as your bug fix. same patch as your bug fix.
For smaller patches in less frequently changed areas of QEMU, consider For smaller patches in less frequently changed areas of QEMU, consider
using the `trivial patches process using the :ref:`trivial-patches` process.
<https://qemu-project.gitlab.io/qemu/devel/style.html>`__.
.. _write_a_meaningful_commit_message: .. _write_a_meaningful_commit_message:
@ -154,7 +161,7 @@ QEMU follows the usual standard for git commit messages: the first line
(which becomes the email subject line) is "subsystem: single line (which becomes the email subject line) is "subsystem: single line
summary of change". Whether the "single line summary of change" starts summary of change". Whether the "single line summary of change" starts
with a capital is a matter of taste, but we prefer that the summary does with a capital is a matter of taste, but we prefer that the summary does
not end in ".". Look at ``git shortlog -30`` for an idea of sample not end in a dot. Look at ``git shortlog -30`` for an idea of sample
subject lines. Then there is a blank line and a more detailed subject lines. Then there is a blank line and a more detailed
description of the patch, another blank and your Signed-off-by: line. description of the patch, another blank and your Signed-off-by: line.
Please do not use lines that are longer than 76 characters in your Please do not use lines that are longer than 76 characters in your
@ -170,11 +177,79 @@ displays the subject line some distance apart (that is, a body that
starts with "... so that" as a continuation of the subject line is starts with "... so that" as a continuation of the subject line is
harder to follow). harder to follow).
If your patch fixes a commit that is already in the repository, please
add an additional line with "Fixes: <at-least-12-digits-of-SHA-commit-id>
("Fixed commit subject")" below the patch description / before your
"Signed-off-by:" line in the commit message.
If your patch fixes a bug in the gitlab bug tracker, please add a line
with "Resolves: <URL-of-the-bug>" to the commit message, too. Gitlab can
close bugs automatically once commits with the "Resolved:" keyword get
merged into the master branch of the project. And if your patch addresses
a bug in another public bug tracker, you can also use a line with
"Buglink: <URL-of-the-bug>" for reference here, too.
Example::
Fixes: 14055ce53c2d ("s390x/tcg: avoid overflows in time2tod/tod2time")
Resolves: https://gitlab.com/qemu-project/qemu/-/issues/42
Buglink: https://bugs.launchpad.net/qemu/+bug/1804323``
Some other tags that are used in commit messages include "Message-Id:"
"Tested-by:", "Acked-by:", "Reported-by:", "Suggested-by:". See ``git
log`` for these keywords for example usage.
.. _test_your_patches:
Test your patches
~~~~~~~~~~~~~~~~~
Although QEMU has `continuous integration
services <Testing#Continuous_Integration>`__ that attempt to test
patches submitted to the list, it still saves everyone time if you have
already tested that your patch compiles and works. Because QEMU is such
a large project, it's okay to use configure arguments to limit what is
built for faster turnaround during your development time; but it is
still wise to also check that your patches work with a full build before
submitting a series, especially if your changes might have an unintended
effect on other areas of the code you don't normally experiment with.
See `Testing <Testing>`__ for more details on what tests are available.
Also, it is a wise idea to include a testsuite addition as part of your
patches - either to ensure that future changes won't regress your new
feature, or to add a test which exposes the bug that the rest of your
series fixes. Keeping separate commits for the test and the fix allows
reviewers to rebase the test to occur first to prove it catches the
problem, then again to place it last in the series so that bisection
doesn't land on a known-broken state.
.. _submitting_your_patches: .. _submitting_your_patches:
Submitting your Patches Submitting your Patches
----------------------- -----------------------
.. _if_you_cannot_send_patch_emails:
If you cannot send patch emails
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In rare cases it may not be possible to send properly formatted patch
emails. You can use `sourcehut <https://sourcehut.org/>`__ to send your
patches to the QEMU mailing list by following these steps:
#. Register or sign in to your account
#. Add your SSH public key in `meta \|
keys <https://meta.sr.ht/keys>`__.
#. Publish your git branch using **git push git@git.sr.ht:~USERNAME/qemu
HEAD**
#. Send your patches to the QEMU mailing list using the web-based
``git-send-email`` UI at https://git.sr.ht/~USERNAME/qemu/send-email
`This video
<https://spacepub.space/videos/watch/ad258d23-0ac6-488c-83fc-2bacf578de3a>`__
shows the web-based ``git-send-email`` workflow. Documentation is
available `here
<https://man.sr.ht/git.sr.ht/#sending-patches-upstream>`__.
.. _cc_the_relevant_maintainer: .. _cc_the_relevant_maintainer:
CC the relevant maintainer CC the relevant maintainer
@ -219,17 +294,26 @@ such as 'git-email' on Fedora-based systems.) Patch series need a cover
letter, with shallow threading (all patches in the series are letter, with shallow threading (all patches in the series are
in-reply-to the cover letter, but not to each other); single unrelated in-reply-to the cover letter, but not to each other); single unrelated
patches do not need a cover letter (but if you do send a cover letter, patches do not need a cover letter (but if you do send a cover letter,
use --numbered so the cover and the patch have distinct subject lines). use ``--numbered`` so the cover and the patch have distinct subject lines).
Patches are easier to find if they start a new top-level thread, rather Patches are easier to find if they start a new top-level thread, rather
than being buried in-reply-to another existing thread. than being buried in-reply-to another existing thread.
.. _avoid_posting_large_binary_blob:
Avoid posting large binary blob
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you added binaries to the repository, consider producing the patch
emails using ``git format-patch --no-binary`` and include a link to a
git repository to fetch the original commit.
.. _patch_emails_must_include_a_signed_off_by_line: .. _patch_emails_must_include_a_signed_off_by_line:
Patch emails must include a ``Signed-off-by:`` line Patch emails must include a ``Signed-off-by:`` line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For more information see `1.12) Sign your work For more information see `SubmittingPatches 1.12
<http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=f6f94e2ab1b33f0082ac22d71f66385a60d8157f#n296>`__. <http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=f6f94e2ab1b33f0082ac22d71f66385a60d8157f#n297>`__.
This is vital or we will not be able to apply your patch! Please use This is vital or we will not be able to apply your patch! Please use
your real name to sign a patch (not an alias or acronym). your real name to sign a patch (not an alias or acronym).
@ -246,8 +330,13 @@ that author's Signed-off-by: line is mandatory, with the same spelling.
Include a meaningful cover letter Include a meaningful cover letter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This usually applies only to a series that includes multiple patches; This is a requirement for any series with multiple patches (as it aids
the cover letter explains the overall goal of such a series. continuous integration), but optional for an isolated patch. The cover
letter explains the overall goal of such a series, and also provides a
convenient 0/N email for others to reply to the series as a whole. A
one-time setup of ``git config format.coverletter auto`` (refer to
`git-config <http://git-scm.com/docs/git-config>`__) will generate the
cover letter as needed.
When reviewers don't know your goal at the start of their review, they When reviewers don't know your goal at the start of their review, they
may object to early changes that don't make sense until the end of the may object to early changes that don't make sense until the end of the
@ -288,6 +377,18 @@ it's best to:
of the patchset you're looking for review on, and why reviewers of the patchset you're looking for review on, and why reviewers
should care should care
.. _consider_whether_your_patch_is_applicable_for_stable:
Consider whether your patch is applicable for stable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your patch fixes a severe issue or a regression, it may be applicable
for stable. In that case, consider adding ``Cc: qemu-stable@nongnu.org``
to your patch to notify the stable maintainers.
For more details on how QEMU's stable process works, refer to the
:ref:`stable-process` page.
.. _participating_in_code_review: .. _participating_in_code_review:
Participating in Code Review Participating in Code Review
@ -367,19 +468,19 @@ Include version history in patchset revisions
For later versions of patches, include a summary of changes from For later versions of patches, include a summary of changes from
previous versions, but not in the commit message itself. In an email previous versions, but not in the commit message itself. In an email
formatted as a git patch, the commit message is the part above the "---" formatted as a git patch, the commit message is the part above the ``---``
line, and this will go into the git changelog when the patch is line, and this will go into the git changelog when the patch is
committed. This part should be a self-contained description of what this committed. This part should be a self-contained description of what this
version of the patch does, written to make sense to anybody who comes version of the patch does, written to make sense to anybody who comes
back to look at this commit in git in six months' time. The part below back to look at this commit in git in six months' time. The part below
the "---" line and above the patch proper (git format-patch puts the the ``---`` line and above the patch proper (git format-patch puts the
diffstat here) is a good place to put remarks for people reading the diffstat here) is a good place to put remarks for people reading the
patch email, and this is where the "changes since previous version" patch email, and this is where the "changes since previous version"
summary belongs. The summary belongs. The `git-publish
`git-publish <https://github.com/stefanha/git-publish>`__ script can <https://github.com/stefanha/git-publish>`__ script can help with
help with tracking a good summary across versions. Also, the tracking a good summary across versions. Also, the `git-backport-diff
`git-backport-diff <https://github.com/codyprime/git-scripts>`__ script <https://github.com/codyprime/git-scripts>`__ script can help focus
can help focus reviewers on what changed between revisions. reviewers on what changed between revisions.
.. _tips_and_tricks: .. _tips_and_tricks:
@ -411,27 +512,32 @@ If your patch seems to have been ignored
If your patchset has received no replies you should "ping" it after a If your patchset has received no replies you should "ping" it after a
week or two, by sending an email as a reply-to-all to the patch mail, week or two, by sending an email as a reply-to-all to the patch mail,
including the word "ping" and ideally also a link to the page for the including the word "ping" and ideally also a link to the page for the
patch on patch on `patchew <https://patchew.org/QEMU/>`__ or
`patchwork <http://patchwork.ozlabs.org/project/qemu-devel/list/>`__ or `lore.kernel.org <https://lore.kernel.org/qemu-devel/>`__. It's worth
GMANE. It's worth double-checking for reasons why your patch might have double-checking for reasons why your patch might have been ignored
been ignored (forgot to CC the maintainer? annoyed people by failing to (forgot to CC the maintainer? annoyed people by failing to respond to
respond to review comments on an earlier version?), but often for review comments on an earlier version?), but often for less-maintained
less-maintained areas of QEMU patches do just slip through the cracks. areas of QEMU patches do just slip through the cracks. If your ping is
If your ping is also ignored, ping again after another week or so. As also ignored, ping again after another week or so. As the submitter, you
the submitter, you are the person with the most motivation to get your are the person with the most motivation to get your patch applied, so
patch applied, so you have to be persistent. you have to be persistent.
.. _is_my_patch_in: .. _is_my_patch_in:
Is my patch in? Is my patch in?
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
QEMU has some Continuous Integration machines that try to catch patch
submission problems as soon as possible. `patchew
<http://patchew.org/QEMU/>`__ includes a web interface for tracking the
status of various threads that have been posted to the list, and may
send you an automated mail if it detected a problem with your patch.
Once your patch has had enough review on list, the maintainer for that Once your patch has had enough review on list, the maintainer for that
area of code will send notification to the list that they are including area of code will send notification to the list that they are including
your patch in a particular staging branch. Periodically, the maintainer your patch in a particular staging branch. Periodically, the maintainer
then sends a `pull request then takes care of :ref:`submitting-a-pull-request`
<https://qemu-project.gitlab.io/qemu/devel/submitting-a-pull-request.html>`__ for aggregating topic branches into mainline QEMU. Generally, you do not
for aggregating topic branches into mainline qemu. Generally, you do not
need to send a pull request unless you have contributed enough patches need to send a pull request unless you have contributed enough patches
to become a maintainer over a particular section of code. Maintainers to become a maintainer over a particular section of code. Maintainers
may further modify your commit, by resolving simple merge conflicts or may further modify your commit, by resolving simple merge conflicts or

9
docs/devel/submitting-a-pull-request.rst
View File

@ -1,10 +1,11 @@
Submit a Pull Request .. _submitting-a-pull-request:
=====================
Submitting a Pull Request
=========================
QEMU welcomes contributions of code, but we generally expect these to be QEMU welcomes contributions of code, but we generally expect these to be
sent as simple patch emails to the mailing list (see our page on sent as simple patch emails to the mailing list (see our page on
`submitting a patch :ref:`submitting-a-patch`
<https://qemu-project.gitlab.io/qemu/devel/submitting-a-patch.html>`__
for more details). Generally only existing submaintainers of a tree for more details). Generally only existing submaintainers of a tree
will need to submit pull requests, although occasionally for a large will need to submit pull requests, although occasionally for a large
patch series we might ask a submitter to send a pull request. This page patch series we might ask a submitter to send a pull request. This page

8
docs/devel/testing.rst
View File

@ -564,11 +564,11 @@ exploiting a QEMU security bug to compromise the host.
QEMU binaries QEMU binaries
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there By default, ``qemu-system-x86_64`` is searched in $PATH to run the guest. If
isn't one, or if it is older than 2.10, the test won't work. In this case, there isn't one, or if it is older than 2.10, the test won't work. In this case,
provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``. provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``.
Likewise the path to qemu-img can be set in QEMU_IMG environment variable. Likewise the path to ``qemu-img`` can be set in QEMU_IMG environment variable.
Make jobs Make jobs
~~~~~~~~~ ~~~~~~~~~
@ -650,7 +650,7 @@ supported. To start the fuzzer, run
tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2 tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
Alternatively, some command different from "qemu-img info" can be tested, by Alternatively, some command different from ``qemu-img info`` can be tested, by
changing the ``-c`` option. changing the ``-c`` option.
Integration tests using the Avocado Framework Integration tests using the Avocado Framework

2
docs/devel/trivial-patches.rst
View File

@ -1,3 +1,5 @@
.. _trivial-patches:
Trivial Patches Trivial Patches
=============== ===============

2
docs/devel/writing-monitor-commands.rst
View File

@ -677,7 +677,7 @@ return a single text string::
The ``HumanReadableText`` struct is intended to be used for all The ``HumanReadableText`` struct is intended to be used for all
commands, under the ``x-`` name prefix that are returning unstructured commands, under the ``x-`` name prefix that are returning unstructured
text targetted at humans. It should never be used for commands outside text targeted at humans. It should never be used for commands outside
the ``x-`` name prefix, as those should be using structured QAPI types. the ``x-`` name prefix, as those should be using structured QAPI types.
Implementing the QMP command Implementing the QMP command

2
docs/hyperv.txt
View File

@ -195,7 +195,7 @@ The enlightenment allows to use Hyper-V SynIC with hardware APICv/AVIC enabled.
Normally, Hyper-V SynIC disables these hardware feature and suggests the guest Normally, Hyper-V SynIC disables these hardware feature and suggests the guest
to use paravirtualized AutoEOI feature. to use paravirtualized AutoEOI feature.
Note: enabling this feature on old hardware (without APICv/AVIC support) may Note: enabling this feature on old hardware (without APICv/AVIC support) may
have negative effect on guest's performace. have negative effect on guest's performance.
3.19. hv-no-nonarch-coresharing=on/off/auto 3.19. hv-no-nonarch-coresharing=on/off/auto
=========================================== ===========================================

6
docs/image-fuzzer.txt
View File

@ -51,10 +51,10 @@ assumes that core dumps will be generated in the current working directory.
For comprehensive test results, please, set up your test environment For comprehensive test results, please, set up your test environment
properly. properly.
Paths to binaries under test (SUTs) qemu-img and qemu-io are retrieved from Paths to binaries under test (SUTs) ``qemu-img`` and ``qemu-io`` are retrieved
environment variables. If the environment check fails the runner will from environment variables. If the environment check fails the runner will
use SUTs installed in system paths. use SUTs installed in system paths.
qemu-img is required for creation of backing files, so it's mandatory to set ``qemu-img`` is required for creation of backing files, so it's mandatory to set
the related environment variable if it's not installed in the system path. the related environment variable if it's not installed in the system path.
For details about environment variables see qemu-iotests/check. For details about environment variables see qemu-iotests/check.

2
docs/system/arm/orangepi.rst
View File

@ -128,7 +128,7 @@ Alternatively, you can also choose to build you own image with buildroot
using the orangepi_pc_defconfig. Also see https://buildroot.org for more information. using the orangepi_pc_defconfig. Also see https://buildroot.org for more information.
When using an image as an SD card, it must be resized to a power of two. This can be When using an image as an SD card, it must be resized to a power of two. This can be
done with the qemu-img command. It is recommended to only increase the image size done with the ``qemu-img`` command. It is recommended to only increase the image size
instead of shrinking it to a power of two, to avoid loss of data. For example, instead of shrinking it to a power of two, to avoid loss of data. For example,
to prepare a downloaded Armbian image, first extract it and then increase to prepare a downloaded Armbian image, first extract it and then increase
its size to one gigabyte as follows: its size to one gigabyte as follows:

26
docs/system/authz.rst
View File

@ -77,9 +77,7 @@ To create an instance of this driver via QMP:
"arguments": { "arguments": {
"qom-type": "authz-simple", "qom-type": "authz-simple",
"id": "authz0", "id": "authz0",
"props": { "identity": "fred"
"identity": "fred"
}
} }
} }
@ -110,15 +108,13 @@ To create an instance of this class via QMP:
"arguments": { "arguments": {
"qom-type": "authz-list", "qom-type": "authz-list",
"id": "authz0", "id": "authz0",
"props": { "rules": [
"rules": [ { "match": "fred", "policy": "allow", "format": "exact" },
{ "match": "fred", "policy": "allow", "format": "exact" }, { "match": "bob", "policy": "allow", "format": "exact" },
{ "match": "bob", "policy": "allow", "format": "exact" }, { "match": "danb", "policy": "deny", "format": "exact" },
{ "match": "danb", "policy": "deny", "format": "exact" }, { "match": "dan*", "policy": "allow", "format": "glob" }
{ "match": "dan*", "policy": "allow", "format": "glob" } ],
], "policy": "deny"
"policy": "deny"
}
} }
} }
@ -143,10 +139,8 @@ To create an instance of this class via QMP:
"arguments": { "arguments": {
"qom-type": "authz-list-file", "qom-type": "authz-list-file",
"id": "authz0", "id": "authz0",
"props": { "filename": "/etc/qemu/myvm-vnc.acl",
"filename": "/etc/qemu/myvm-vnc.acl", "refresh": true
"refresh": true
}
} }
} }

2
docs/system/cpu-models-x86.rst.inc
View File

@ -49,7 +49,7 @@ future OS and toolchains are likely to target newer ABIs. The
table that follows illustrates which ABI compatibility levels table that follows illustrates which ABI compatibility levels
can be satisfied by the QEMU CPU models. Note that the table only can be satisfied by the QEMU CPU models. Note that the table only
lists the long term stable CPU model versions (eg Haswell-v4). lists the long term stable CPU model versions (eg Haswell-v4).
In addition to whats listed, there are also many CPU model In addition to what is listed, there are also many CPU model
aliases which resolve to a different CPU model version, aliases which resolve to a different CPU model version,
depending on the machine type is in use. depending on the machine type is in use.

2
docs/system/devices/nvme.rst
View File

@ -70,7 +70,7 @@ namespaces and additional features, the ``nvme-ns`` device must be used.
The namespaces defined by the ``nvme-ns`` device will attach to the most The namespaces defined by the ``nvme-ns`` device will attach to the most
recently defined ``nvme-bus`` that is created by the ``nvme`` device. Namespace recently defined ``nvme-bus`` that is created by the ``nvme`` device. Namespace
identifers are allocated automatically, starting from ``1``. identifiers are allocated automatically, starting from ``1``.
There are a number of parameters available: There are a number of parameters available:

2
docs/system/gdb.rst
View File

@ -56,7 +56,7 @@ machine has more than one CPU, QEMU exposes each CPU cluster as a
separate "inferior", where each CPU within the cluster is a separate separate "inferior", where each CPU within the cluster is a separate
"thread". Most QEMU machine types have identical CPUs, so there is a "thread". Most QEMU machine types have identical CPUs, so there is a
single cluster which has all the CPUs in it. A few machine types are single cluster which has all the CPUs in it. A few machine types are
heterogenous and have multiple clusters: for example the ``sifive_u`` heterogeneous and have multiple clusters: for example the ``sifive_u``
machine has a cluster with one E51 core and a second cluster with four machine has a cluster with one E51 core and a second cluster with four
U54 cores. Here the E51 is the only thread in the first inferior, and U54 cores. Here the E51 is the only thread in the first inferior, and
the U54 cores are all threads in the second inferior. the U54 cores are all threads in the second inferior.

2
docs/system/images.rst
View File

@ -20,7 +20,7 @@ where myimage.img is the disk image filename and mysize is its size in
kilobytes. You can add an ``M`` suffix to give the size in megabytes and kilobytes. You can add an ``M`` suffix to give the size in megabytes and
a ``G`` suffix for gigabytes. a ``G`` suffix for gigabytes.
See the qemu-img invocation documentation for more information. See the ``qemu-img`` invocation documentation for more information.
.. _disk_005fimages_005fsnapshot_005fmode: .. _disk_005fimages_005fsnapshot_005fmode:

2
docs/system/ppc/ppce500.rst
View File

@ -75,7 +75,7 @@ as the BIOS. QEMU follows below truth table to select which payload to execute:
When both -bios and -kernel are present, QEMU loads U-Boot and U-Boot in turns When both -bios and -kernel are present, QEMU loads U-Boot and U-Boot in turns
automatically loads the kernel image specified by the -kernel parameter via automatically loads the kernel image specified by the -kernel parameter via
U-Boot's built-in "bootm" command, hence a legacy uImage format is required in U-Boot's built-in "bootm" command, hence a legacy uImage format is required in
such senario. such scenario.
Running Linux kernel Running Linux kernel
-------------------- --------------------

6
docs/system/qemu-block-drivers.rst.inc
View File

@ -511,13 +511,13 @@ of an inet socket:
|qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket |qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
In this case, the block device must be exported using qemu-nbd: In this case, the block device must be exported using ``qemu-nbd``:
.. parsed-literal:: .. parsed-literal::
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
The use of qemu-nbd allows sharing of a disk between several guests: The use of ``qemu-nbd`` allows sharing of a disk between several guests:
.. parsed-literal:: .. parsed-literal::
@ -530,7 +530,7 @@ and then you can use it with two guests:
|qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket |qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
|qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket |qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's If the ``nbd-server`` uses named exports (supported since NBD 2.9.18, or with QEMU's
own embedded NBD server), you must specify an export name in the URI: own embedded NBD server), you must specify an export name in the URI:
.. parsed-literal:: .. parsed-literal::

2
docs/system/riscv/shakti-c.rst
View File

@ -45,7 +45,7 @@ Shakti SDK can be used to generate the baremetal example UART applications.
Binary would be generated in: Binary would be generated in:
software/examples/uart_applns/loopback/output/loopback.shakti software/examples/uart_applns/loopback/output/loopback.shakti
You could also download the precompiled example applicatons using below You could also download the precompiled example applications using below
commands. commands.
.. code-block:: bash .. code-block:: bash

2
docs/system/tls.rst
View File

@ -311,7 +311,7 @@ containing one or more usernames and random keys::
mkdir -m 0700 /tmp/keys mkdir -m 0700 /tmp/keys
psktool -u rich -p /tmp/keys/keys.psk psktool -u rich -p /tmp/keys/keys.psk
TLS-enabled servers such as qemu-nbd can use this directory like so:: TLS-enabled servers such as ``qemu-nbd`` can use this directory like so::
qemu-nbd \ qemu-nbd \
-t -x / \ -t -x / \

8
docs/throttle.txt
View File

@ -273,11 +273,9 @@ A group can be created using the object-add QMP function:
"arguments": { "arguments": {
"qom-type": "throttle-group", "qom-type": "throttle-group",
"id": "group0", "id": "group0",
"props": { "limits" : {
"limits" : { "iops-total": 1000,
"iops-total": 1000 "bps-write": 2097152
"bps-write": 2097152
}
} }
} }
} }

18
docs/tools/qemu-img.rst
View File

@ -127,9 +127,9 @@ by the used format or see the format descriptions below for details.
.. option:: -S SIZE .. option:: -S SIZE
Indicates the consecutive number of bytes that must contain only zeros Indicates the consecutive number of bytes that must contain only zeros
for qemu-img to create a sparse image during conversion. This value is rounded for ``qemu-img`` to create a sparse image during conversion. This value is
down to the nearest 512 bytes. You may use the common size suffixes like rounded down to the nearest 512 bytes. You may use the common size suffixes
``k`` for kilobytes. like ``k`` for kilobytes.
.. option:: -t CACHE .. option:: -t CACHE
@ -431,7 +431,7 @@ Command description:
suppressed from the destination image. suppressed from the destination image.
*SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k) *SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k)
that must contain only zeros for qemu-img to create a sparse image during that must contain only zeros for ``qemu-img`` to create a sparse image during
conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for
unallocated or zero sectors, and the destination image will always be unallocated or zero sectors, and the destination image will always be
fully allocated. fully allocated.
@ -447,7 +447,7 @@ Command description:
If the ``-n`` option is specified, the target volume creation will be If the ``-n`` option is specified, the target volume creation will be
skipped. This is useful for formats such as ``rbd`` if the target skipped. This is useful for formats such as ``rbd`` if the target
volume has already been created with site specific options that cannot volume has already been created with site specific options that cannot
be supplied through qemu-img. be supplied through ``qemu-img``.
Out of order writes can be enabled with ``-W`` to improve performance. Out of order writes can be enabled with ``-W`` to improve performance.
This is only recommended for preallocated devices like host devices or other This is only recommended for preallocated devices like host devices or other
@ -472,7 +472,7 @@ Command description:
If the option *BACKING_FILE* is specified, then the image will record If the option *BACKING_FILE* is specified, then the image will record
only the differences from *BACKING_FILE*. No size needs to be specified in only the differences from *BACKING_FILE*. No size needs to be specified in
this case. *BACKING_FILE* will never be modified unless you use the this case. *BACKING_FILE* will never be modified unless you use the
``commit`` monitor command (or qemu-img commit). ``commit`` monitor command (or ``qemu-img commit``).
If a relative path name is given, the backing file is looked up relative to If a relative path name is given, the backing file is looked up relative to
the directory containing *FILENAME*. the directory containing *FILENAME*.
@ -684,7 +684,7 @@ Command description:
Safe mode Safe mode
This is the default mode and performs a real rebase operation. The This is the default mode and performs a real rebase operation. The
new backing file may differ from the old one and qemu-img rebase new backing file may differ from the old one and ``qemu-img rebase``
will take care of keeping the guest-visible content of *FILENAME* will take care of keeping the guest-visible content of *FILENAME*
unchanged. unchanged.
@ -697,7 +697,7 @@ Command description:
exists. exists.
Unsafe mode Unsafe mode
qemu-img uses the unsafe mode if ``-u`` is specified. In this ``qemu-img`` uses the unsafe mode if ``-u`` is specified. In this
mode, only the backing file name and format of *FILENAME* is changed mode, only the backing file name and format of *FILENAME* is changed
without any checks on the file contents. The user must take care of without any checks on the file contents. The user must take care of
specifying the correct new backing file, or the guest-visible specifying the correct new backing file, or the guest-visible
@ -735,7 +735,7 @@ Command description:
sizes accordingly. Failure to do so will result in data loss! sizes accordingly. Failure to do so will result in data loss!
When shrinking images, the ``--shrink`` option must be given. This informs When shrinking images, the ``--shrink`` option must be given. This informs
qemu-img that the user acknowledges all loss of data beyond the truncated ``qemu-img`` that the user acknowledges all loss of data beyond the truncated
image's end. image's end.
After using this command to grow a disk image, you must use file system and After using this command to grow a disk image, you must use file system and

6
docs/tools/qemu-nbd.rst
View File

@ -31,14 +31,14 @@ driver options if ``--image-opts`` is specified.
*dev* is an NBD device. *dev* is an NBD device.
.. option:: --object type,id=ID,...props... .. option:: --object type,id=ID,...
Define a new instance of the *type* object class identified by *ID*. Define a new instance of the *type* object class identified by *ID*.
See the :manpage:`qemu(1)` manual page for full details of the properties See the :manpage:`qemu(1)` manual page for full details of the properties
supported. The common object types that it makes sense to define are the supported. The common object types that it makes sense to define are the
``secret`` object, which is used to supply passwords and/or encryption ``secret`` object, which is used to supply passwords and/or encryption
keys, and the ``tls-creds`` object, which is used to supply TLS keys, and the ``tls-creds`` object, which is used to supply TLS
credentials for the qemu-nbd server or client. credentials for the ``qemu-nbd`` server or client.
.. option:: -p, --port=PORT .. option:: -p, --port=PORT
@ -238,7 +238,7 @@ daemon:
Expose the guest-visible contents of a qcow2 file via a block device Expose the guest-visible contents of a qcow2 file via a block device
/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
partitions found within), then disconnect the device when done. partitions found within), then disconnect the device when done.
Access to bind qemu-nbd to an /dev/nbd device generally requires root Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root
privileges, and may also require the execution of ``modprobe nbd`` privileges, and may also require the execution of ``modprobe nbd``
to enable the kernel NBD client module. *CAUTION*: Do not use to enable the kernel NBD client module. *CAUTION*: Do not use
this method to mount filesystems from an untrusted guest image - a this method to mount filesystems from an untrusted guest image - a

7
docs/tools/qemu-storage-daemon.rst
View File

@ -10,9 +10,10 @@ Synopsis
Description Description
----------- -----------
qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and ``qemu-storage-daemon`` provides disk image functionality from QEMU,
qemu-nbd in a long-running process controlled via QMP commands without running ``qemu-img``, and ``qemu-nbd`` in a long-running process controlled via QMP
a virtual machine. It can export disk images, run block job operations, and commands without running a virtual machine.
It can export disk images, run block job operations, and
perform other disk-related operations. The daemon is controlled via a QMP perform other disk-related operations. The daemon is controlled via a QMP
monitor and initial configuration from the command-line. monitor and initial configuration from the command-line.

4
docs/tools/virtiofsd.rst
View File

@ -136,8 +136,8 @@ Extended attribute (xattr) mapping
By default the name of xattr's used by the client are passed through to the server By default the name of xattr's used by the client are passed through to the server
file system. This can be a problem where either those xattr names are used file system. This can be a problem where either those xattr names are used
by something on the server (e.g. selinux client/server confusion) or if the by something on the server (e.g. selinux client/server confusion) or if the
virtiofsd is running in a container with restricted privileges where it cannot ``virtiofsd`` is running in a container with restricted privileges where it
access some attributes. cannot access some attributes.
Mapping syntax Mapping syntax
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~