mirror of https://github.com/proxmox/mirror_qemu
Pull request
-----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEE+ber27ys35W+dsvQfe+BBqr8OQ4FAl0mOtYACgkQfe+BBqr8 OQ6ExBAAu8SRJA7/+crHNLrpemSTuD8IWhqyBET1hNN2F7E73kGq4YcZt5xMiH8W kgrytVslc4JZfXdbTKADEDDaNV/24HUOeGQjo7MwrzrouuFbFoxp1I89xi3hLQbZ w4rwnhUfbqc41wH4WlHan+gt5oD27S4Lvd410OEn2tv5pKE8eb4NIt7Jwsbtqa5C 1/yMWIry7PIbUPPAP/ghYniCg8dyKXttSTaWnKfdo/BR+NbJcNJ3wa53KoZxlXuT U/DN6PBnCE4WAL3y8a2wyTv2upDXz4/bKlbqqTHE6zz6XkgfJl2I2+UwbMQzlEAN dmmp7JHikoxpW+go6VT2ihMOTdGP00yvgwRuHHYGQwFJkoApZC9t8SDg0D3tBJcs rYFcs/5dlq96pLXIhIECs8zVe0plqFbEaXpg8RhRmtr9m2Eafir8u8J9OKCCXXAQ PAot+7UNR/aXLFwVCjfq5A/lwvxfnVUj8V61aCu6GaCH8RSthXyHLY8IoVZ+r6Cb IVFmTiy1tcwakT6Wg0CuDfdU07sxdnSqzJJqhGjKpFyayiQxjxdeujI2mYSZcSLT ZPANZybTVnZzGZsnFCB7wjiJAkAOuj34isISP2Dn4eaCTBqrcF19imNLJD0ey1SX gUWD9U6bcPeUDI+iVdHmZ5bmabomgXiBt/ELgwPxRWxS8qrdYXY= =xLgo -----END PGP SIGNATURE----- Merge remote-tracking branch 'remotes/jnsnow/tags/bitmaps-pull-request' into staging Pull request # gpg: Signature made Wed 10 Jul 2019 20:21:58 BST # gpg: using RSA key F9B7ABDBBCACDF95BE76CBD07DEF8106AAFC390E # gpg: Good signature from "John Snow (John Huston) <jsnow@redhat.com>" [full] # Primary key fingerprint: FAEB 9711 A12C F475 812F 18F2 88A9 064D 1835 61EB # Subkey fingerprint: F9B7 ABDB BCAC DF95 BE76 CBD0 7DEF 8106 AAFC 390E * remotes/jnsnow/tags/bitmaps-pull-request: docs/bitmaps: use QMP lexer instead of json sphinx: add qmp_lexer docs/interop/bitmaps.rst: Fix typos Signed-off-by: Peter Maydell <peter.maydell@linaro.org>master
commit
9411db8f37
|
@ -41,7 +41,7 @@ except NameError:
|
||||||
# add these directories to sys.path here. If the directory is relative to the
|
# add these directories to sys.path here. If the directory is relative to the
|
||||||
# documentation root, use an absolute path starting from qemu_docdir.
|
# documentation root, use an absolute path starting from qemu_docdir.
|
||||||
#
|
#
|
||||||
# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir"))
|
sys.path.insert(0, os.path.join(qemu_docdir, "sphinx"))
|
||||||
|
|
||||||
|
|
||||||
# -- General configuration ------------------------------------------------
|
# -- General configuration ------------------------------------------------
|
||||||
|
@ -54,7 +54,7 @@ needs_sphinx = '1.3'
|
||||||
# Add any Sphinx extension module names here, as strings. They can be
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
# ones.
|
# ones.
|
||||||
extensions = []
|
extensions = ['qmp_lexer']
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
templates_path = ['_templates']
|
templates_path = ['_templates']
|
||||||
|
|
|
@ -199,7 +199,7 @@ persistence, and recording state can be adjusted at creation time.
|
||||||
|
|
||||||
to create a new, actively recording persistent bitmap:
|
to create a new, actively recording persistent bitmap:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> { "execute": "block-dirty-bitmap-add",
|
-> { "execute": "block-dirty-bitmap-add",
|
||||||
"arguments": {
|
"arguments": {
|
||||||
|
@ -220,7 +220,7 @@ persistence, and recording state can be adjusted at creation time.
|
||||||
To create a new, disabled (``-recording``), transient bitmap that tracks
|
To create a new, disabled (``-recording``), transient bitmap that tracks
|
||||||
changes in 32KiB segments:
|
changes in 32KiB segments:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> { "execute": "block-dirty-bitmap-add",
|
-> { "execute": "block-dirty-bitmap-add",
|
||||||
"arguments": {
|
"arguments": {
|
||||||
|
@ -254,7 +254,7 @@ Deletes a bitmap. Bitmaps that are ``+busy`` cannot be removed.
|
||||||
|
|
||||||
Remove a bitmap named ``bitmap0`` from node ``drive0``:
|
Remove a bitmap named ``bitmap0`` from node ``drive0``:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> { "execute": "block-dirty-bitmap-remove",
|
-> { "execute": "block-dirty-bitmap-remove",
|
||||||
"arguments": {
|
"arguments": {
|
||||||
|
@ -280,7 +280,7 @@ Clears all dirty bits from a bitmap. ``+busy`` bitmaps cannot be cleared.
|
||||||
|
|
||||||
Clear all dirty bits from bitmap ``bitmap0`` on node ``drive0``:
|
Clear all dirty bits from bitmap ``bitmap0`` on node ``drive0``:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> { "execute": "block-dirty-bitmap-clear",
|
-> { "execute": "block-dirty-bitmap-clear",
|
||||||
"arguments": {
|
"arguments": {
|
||||||
|
@ -309,7 +309,7 @@ begin being recorded. ``+busy`` bitmaps cannot be enabled.
|
||||||
|
|
||||||
To set ``+recording`` on bitmap ``bitmap0`` on node ``drive0``:
|
To set ``+recording`` on bitmap ``bitmap0`` on node ``drive0``:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> { "execute": "block-dirty-bitmap-enable",
|
-> { "execute": "block-dirty-bitmap-enable",
|
||||||
"arguments": {
|
"arguments": {
|
||||||
|
@ -347,7 +347,7 @@ writes to begin being ignored. ``+busy`` bitmaps cannot be disabled.
|
||||||
|
|
||||||
To set ``-recording`` on bitmap ``bitmap0`` on node ``drive0``:
|
To set ``-recording`` on bitmap ``bitmap0`` on node ``drive0``:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> { "execute": "block-dirty-bitmap-disable",
|
-> { "execute": "block-dirty-bitmap-disable",
|
||||||
"arguments": {
|
"arguments": {
|
||||||
|
@ -393,13 +393,13 @@ in any one source bitmap, the target bitmap will mark that segment dirty.
|
||||||
``drive0``. If ``new_bitmap`` was empty prior to this command, this achieves
|
``drive0``. If ``new_bitmap`` was empty prior to this command, this achieves
|
||||||
a copy.
|
a copy.
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> { "execute": "block-dirty-bitmap-merge",
|
-> { "execute": "block-dirty-bitmap-merge",
|
||||||
"arguments": {
|
"arguments": {
|
||||||
"node": "drive0",
|
"node": "drive0",
|
||||||
"target": "new_bitmap",
|
"target": "new_bitmap",
|
||||||
"bitmaps: [ "bitmap0" ]
|
"bitmaps": [ "bitmap0" ]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -424,7 +424,7 @@ attached to nodes serving as the root for guest devices.
|
||||||
API. This result highlights a bitmap ``bitmap0`` attached to the root node of
|
API. This result highlights a bitmap ``bitmap0`` attached to the root node of
|
||||||
device ``drive0``.
|
device ``drive0``.
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "query-block",
|
"execute": "query-block",
|
||||||
|
@ -562,7 +562,7 @@ new, empty bitmap that records writes from this point in time forward.
|
||||||
destination. These writes will be recorded in the bitmap
|
destination. These writes will be recorded in the bitmap
|
||||||
accordingly.
|
accordingly.
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "transaction",
|
"execute": "transaction",
|
||||||
|
@ -650,7 +650,7 @@ Example: Resetting an Incremental Backup Anchor Point
|
||||||
If we want to start a new backup chain with an existing bitmap, we can also
|
If we want to start a new backup chain with an existing bitmap, we can also
|
||||||
use a transaction to reset the bitmap while making a new full backup:
|
use a transaction to reset the bitmap while making a new full backup:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "transaction",
|
"execute": "transaction",
|
||||||
|
@ -730,7 +730,7 @@ Example: First Incremental Backup
|
||||||
|
|
||||||
#. Issue an incremental backup command:
|
#. Issue an incremental backup command:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "drive-backup",
|
"execute": "drive-backup",
|
||||||
|
@ -788,7 +788,7 @@ Example: Second Incremental Backup
|
||||||
#. Issue a new incremental backup command. The only difference here is that we
|
#. Issue a new incremental backup command. The only difference here is that we
|
||||||
have changed the target image below.
|
have changed the target image below.
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "drive-backup",
|
"execute": "drive-backup",
|
||||||
|
@ -869,7 +869,7 @@ image:
|
||||||
#. Issue a new incremental backup command. Apart from the new destination
|
#. Issue a new incremental backup command. Apart from the new destination
|
||||||
image, there is no difference from the last two examples.
|
image, there is no difference from the last two examples.
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "drive-backup",
|
"execute": "drive-backup",
|
||||||
|
@ -932,7 +932,7 @@ point in time.
|
||||||
|
|
||||||
#. Create a full (anchor) backup for each drive, with accompanying bitmaps:
|
#. Create a full (anchor) backup for each drive, with accompanying bitmaps:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "transaction",
|
"execute": "transaction",
|
||||||
|
@ -1018,7 +1018,7 @@ point in time.
|
||||||
|
|
||||||
#. Issue a multi-drive incremental push backup transaction:
|
#. Issue a multi-drive incremental push backup transaction:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "transaction",
|
"execute": "transaction",
|
||||||
|
@ -1121,7 +1121,7 @@ described above. This example demonstrates the single-job failure case:
|
||||||
|
|
||||||
#. Attempt to create an incremental backup via QMP:
|
#. Attempt to create an incremental backup via QMP:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "drive-backup",
|
"execute": "drive-backup",
|
||||||
|
@ -1139,7 +1139,7 @@ described above. This example demonstrates the single-job failure case:
|
||||||
|
|
||||||
#. Receive a pair of events indicating failure:
|
#. Receive a pair of events indicating failure:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- {
|
<- {
|
||||||
"timestamp": {...},
|
"timestamp": {...},
|
||||||
|
@ -1175,7 +1175,7 @@ described above. This example demonstrates the single-job failure case:
|
||||||
#. Retry the command after fixing the underlying problem, such as
|
#. Retry the command after fixing the underlying problem, such as
|
||||||
freeing up space on the backup volume:
|
freeing up space on the backup volume:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "drive-backup",
|
"execute": "drive-backup",
|
||||||
|
@ -1193,7 +1193,7 @@ described above. This example demonstrates the single-job failure case:
|
||||||
|
|
||||||
#. Receive confirmation that the job completed successfully:
|
#. Receive confirmation that the job completed successfully:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- {
|
<- {
|
||||||
"timestamp": {...},
|
"timestamp": {...},
|
||||||
|
@ -1233,7 +1233,7 @@ and one succeeds:
|
||||||
|
|
||||||
#. Issue the transaction to start a backup of both drives.
|
#. Issue the transaction to start a backup of both drives.
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "transaction",
|
"execute": "transaction",
|
||||||
|
@ -1267,13 +1267,13 @@ and one succeeds:
|
||||||
#. Receive notice that the Transaction was accepted, and jobs were
|
#. Receive notice that the Transaction was accepted, and jobs were
|
||||||
launched:
|
launched:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- { "return": {} }
|
<- { "return": {} }
|
||||||
|
|
||||||
#. Receive notice that the first job has completed:
|
#. Receive notice that the first job has completed:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- {
|
<- {
|
||||||
"timestamp": {...},
|
"timestamp": {...},
|
||||||
|
@ -1289,7 +1289,7 @@ and one succeeds:
|
||||||
|
|
||||||
#. Receive notice that the second job has failed:
|
#. Receive notice that the second job has failed:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- {
|
<- {
|
||||||
"timestamp": {...},
|
"timestamp": {...},
|
||||||
|
@ -1365,7 +1365,7 @@ applied:
|
||||||
|
|
||||||
#. Issue the multi-drive incremental backup transaction:
|
#. Issue the multi-drive incremental backup transaction:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
-> {
|
-> {
|
||||||
"execute": "transaction",
|
"execute": "transaction",
|
||||||
|
@ -1401,13 +1401,13 @@ applied:
|
||||||
|
|
||||||
#. Receive notice that the Transaction was accepted, and jobs were launched:
|
#. Receive notice that the Transaction was accepted, and jobs were launched:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- { "return": {} }
|
<- { "return": {} }
|
||||||
|
|
||||||
#. Receive notification that the backup job for ``drive1`` has failed:
|
#. Receive notification that the backup job for ``drive1`` has failed:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- {
|
<- {
|
||||||
"timestamp": {...},
|
"timestamp": {...},
|
||||||
|
@ -1434,10 +1434,10 @@ applied:
|
||||||
|
|
||||||
#. Receive notification that the job for ``drive0`` has been cancelled:
|
#. Receive notification that the job for ``drive0`` has been cancelled:
|
||||||
|
|
||||||
.. code:: json
|
.. code-block:: QMP
|
||||||
|
|
||||||
<- {
|
<- {
|
||||||
"timestamp": {...}
|
"timestamp": {...},
|
||||||
"data": {
|
"data": {
|
||||||
"device": "drive0",
|
"device": "drive0",
|
||||||
"type": "backup",
|
"type": "backup",
|
||||||
|
|
|
@ -0,0 +1,43 @@
|
||||||
|
# QEMU Monitor Protocol Lexer Extension
|
||||||
|
#
|
||||||
|
# Copyright (C) 2019, Red Hat Inc.
|
||||||
|
#
|
||||||
|
# Authors:
|
||||||
|
# Eduardo Habkost <ehabkost@redhat.com>
|
||||||
|
# John Snow <jsnow@redhat.com>
|
||||||
|
#
|
||||||
|
# This work is licensed under the terms of the GNU GPLv2 or later.
|
||||||
|
# See the COPYING file in the top-level directory.
|
||||||
|
"""qmp_lexer is a Sphinx extension that provides a QMP lexer for code blocks."""
|
||||||
|
|
||||||
|
from pygments.lexer import RegexLexer, DelegatingLexer
|
||||||
|
from pygments.lexers.data import JsonLexer
|
||||||
|
from pygments import token
|
||||||
|
from sphinx import errors
|
||||||
|
|
||||||
|
class QMPExampleMarkersLexer(RegexLexer):
|
||||||
|
"""
|
||||||
|
QMPExampleMarkersLexer lexes QMP example annotations.
|
||||||
|
This lexer adds support for directionality flow and elision indicators.
|
||||||
|
"""
|
||||||
|
tokens = {
|
||||||
|
'root': [
|
||||||
|
(r'-> ', token.Generic.Prompt),
|
||||||
|
(r'<- ', token.Generic.Prompt),
|
||||||
|
(r' ?\.{3} ?', token.Generic.Prompt),
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
class QMPExampleLexer(DelegatingLexer):
|
||||||
|
"""QMPExampleLexer lexes annotated QMP examples."""
|
||||||
|
def __init__(self, **options):
|
||||||
|
super(QMPExampleLexer, self).__init__(JsonLexer, QMPExampleMarkersLexer,
|
||||||
|
token.Error, **options)
|
||||||
|
|
||||||
|
def setup(sphinx):
|
||||||
|
"""For use by the Sphinx extensions API."""
|
||||||
|
try:
|
||||||
|
sphinx.require_sphinx('2.1')
|
||||||
|
sphinx.add_lexer('QMP', QMPExampleLexer)
|
||||||
|
except errors.VersionRequirementError:
|
||||||
|
sphinx.add_lexer('QMP', QMPExampleLexer())
|
Loading…
Reference in New Issue